os.path — Общие манипуляции с именами путей

Исходный код: Lib/genericpath.py, Lib/posixpath.py (для POSIX) и Lib/ntpath.py (для Windows).

Этот модуль реализует некоторые полезные функции для работы с именами путей. Для чтения или записи файлов см. open(), а для доступа к файловой системе см. модуль os. Параметры пути могут быть переданы в виде строк, байтов или любого объекта, реализующего протокол os.PathLike.

В отличие от оболочки Unix, Python не выполняет никаких автоматических расширений путей. Функции, такие как expanduser() и expandvars(), могут быть вызваны явно, когда приложение желает расширения путей в стиле оболочки. (См. также модуль glob.)

os.path.abspath(path)

Возвращает нормализованную абсолютизированную версию пути path. На большинстве платформ это эквивалентно вызову функции normpath() следующим образом: normpath(join(os.getcwd(), path)).

Изменено в версии 3.6: Принимает объект-путь.

os.path.basename(path)

Возвращает имя файла пути path. Это второй элемент пары, возвращаемой при передаче path в функцию split(). Обратите внимание, что результат этой функции отличается от программы Unix basename; где basename для '/foo/bar/' возвращает 'bar', функция basename() возвращает пустую строку ('').

Изменено в версии 3.6: Принимает объект-путь.

os.path.commonpath(paths)

Возвращает самое длинное общее подпапку для каждого пути в итерируемом paths. Генерирует ValueError, если paths содержит абсолютные и относительные пути, если пути находятся на разных дисках или если paths пусто. В отличие от commonprefix(), это возвращает допустимый путь.

Добавлена в версии 3.5.

Изменено в версии 3.6: Принимает последовательность объектов-путей.

Изменено в версии 3.13: Теперь может быть передан любой итерируемый объект, а не только последовательности.

os.path.commonprefix(list)

Возвращает самое длинное общее префиксное имя пути (символ за символом), являющееся префиксом всех путей в list. Если list пусто, вернуть пустую строку ('').

Примечание

Эта функция может вернуть недопустимые пути, так как она работает с символом за символом. Чтобы получить допустимый путь, см. commonpath().

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

Изменено в версии 3.6: Принимает объект-путь.

os.path.dirname(path)

Возвращает имя каталога пути path. Это первый элемент пары, возвращаемой при передаче path в функцию split().

Изменено в версии 3.6: Принимает объект-путь.

os.path.exists(path)

Возвращает True, если path ссылается на существующий путь или открытый дескриптор файла. Возвращает False для прерванных символических ссылок. На некоторых платформах эта функция может вернуть False, если разрешение не предоставлено для выполнения os.stat() на запрошенном файле, даже если path физически существует.

Изменено в версии 3.3: path теперь может быть целым числом: True возвращается, если это открытый дескриптор файла, False в противном случае.

Изменено в версии 3.6: Принимает объект-путь.

os.path.lexists(path)

Возвращает True, если path ссылается на существующий путь, включая прерванные символические ссылки. Эквивалентно exists() на платформах, не имеющих os.lstat().

Изменено в версии 3.6: Принимает объект-путь.

os.path.expanduser(path)

В Unix и Windows возвращает аргумент с начальным компонентом ~ или ~user, заменённым домашним каталогом данного пользователя.

В Unix, начальный ~ заменяется переменной окружения HOME, если она задана; в противном случае домашний каталог текущего пользователя ищется в каталоге паролей с помощью встроенного модуля pwd. Начальный ~user ищется напрямую в каталоге паролей.

В Windows, USERPROFILE используется, если задано, в противном случае используется сочетание HOMEPATH и HOMEDRIVE. Начальный ~user обрабатывается проверкой, соответствует ли последний компонент каталога домашнего каталога текущего пользователя USERNAME, и заменяется, если соответствует.

Если расширение завершается неудачно или путь не начинается с тильды, путь возвращается без изменений.

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.8: В Windows больше не используется HOME.

os.path.expandvars(path)

Возвращает аргумент с расширенными переменными окружения. Подстроки вида $name или ${name} заменяются значением переменной окружения имя. Неправильные имена переменных и ссылки на несуществующие переменные остаются без изменений.

В Windows, дополнительно к $name и ${name}, поддерживаются расширения %name%.

Изменено в версии 3.6: Принимает объект-путь.

os.path.getatime(path)

Возвращает время последнего доступа к пути. Возвращаемое значение — число с плавающей точкой, представляющее количество секунд с эпохи (см. модуль time). Вызывает исключение OSError, если файл не существует или недоступен.

os.path.getmtime(path)

Возвращает время последнего изменения пути. Возвращаемое значение — число с плавающей точкой, представляющее количество секунд с эпохи (см. модуль time). Вызывает исключение OSError, если файл не существует или недоступен.

Изменено в версии 3.6: Принимает объект-путь.

os.path.getctime(path)

Возвращает системное время ctime, которое на некоторых системах (например, Unix) является временем последнего изменения метаданных, а на других (например, Windows) — временем создания пути. Возвращаемое значение — число, представляющее количество секунд с эпохи (см. модуль time). Вызывает исключение OSError, если файл не существует или недоступен.

Изменено в версии 3.6: Принимает объект-путь.

os.path.getsize(path)

Возвращает размер пути в байтах. Вызывает исключение OSError, если файл не существует или недоступен.

Изменено в версии 3.6: Принимает объект-путь.

os.path.isabs(path)

Возвращает True, если путь — абсолютный путь. В Unix это означает, что он начинается с косой черты, в Windows — с двух обратных косых черт или символа буквы диска, двоеточия и обратной косой черты вместе.

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.13: В Windows возвращает False, если заданный путь начинается ровно с одной обратной косой черты.

os.path.isfile(path)

Возвращает True, если путь является existing обычным файлом. Это учитывает символические ссылки, поэтому и islink(), и isfile() могут быть истинными для одного и того же пути.

Изменено в версии 3.6: Принимает объект-путь.

os.path.isdir(path)

Возвращает True, если путь является existing каталогом. Это учитывает символические ссылки, поэтому и islink(), и isdir() могут быть истинными для одного и того же пути.

Изменено в версии 3.6: Принимает объект-путь.

os.path.isjunction(path)

Возвращает True, если путь ссылается на existing элемент каталога, являющийся соединением. Всегда возвращает False, если соединения не поддерживаются на текущей платформе.

Добавлена в версии 3.12.

os.path.islink(path)

Возвращает True, если путь ссылается на existing элемент каталога, являющийся символической ссылкой. Всегда False, если символические ссылки не поддерживаются средой выполнения Python.

Изменено в версии 3.6: Принимает объект-путь.

os.path.ismount(path)

Возвращает True, если путь путь является точкой монтирования: точкой в файловой системе, где смонтирована другая файловая система. В POSIX функция проверяет, находится ли родитель пути, path/.., на другом устройстве, чем путь, или указывают ли path/.. и путь на один и тот же узел i на одном и том же устройстве — это должно определять точки монтирования для всех вариантов Unix и POSIX. Она не способна надёжно определять монтирования привязки в одной файловой системе. В Windows корневой каталог диска и общий UNC всегда являются точками монтирования, а для любого другого пути вызывается GetVolumePathName, чтобы проверить, отличается ли он от входного пути.

Изменено в версии 3.4: Добавлена поддержка обнаружения точек монтирования, не являющихся корневыми, в Windows.

Изменено в версии 3.6: Принимает объект-путь.

os.path.isdevdrive(path)

Возвращает True, если путь путь находится на диске разработки Windows. Диск разработки оптимизирован для сценариев разработчика и обеспечивает более высокую производительность при чтении и записи файлов. Рекомендуется использовать для исходного кода, временных каталогов сборки, кэшей пакетов и других операций ввода-вывода с высокой интенсивностью.

Может вызвать ошибку для некорректного пути, например, пути без распознаваемого диска, но возвращает False на платформах, которые не поддерживают диски разработки. См. документацию Windows для получения информации по включению и созданию дисков разработки.

Добавлена в версии 3.12.

Изменено в версии 3.13: Функция теперь доступна на всех платформах и всегда будет возвращать False на платформах, не поддерживающих диски разработки.

os.path.isreserved(path)

Возвращает значение True, если path является зарезервированным именем пути в текущей системе.

В Windows зарезервированные имена файлов включают те, которые оканчиваются пробелом или точкой; те, которые содержат двоеточия (например, потоки файлов, такие как «имя:поток»), символы подстановки (например, '*?"<>'), вертикальную черту, или управляющие символы ASCII; а также имена устройств DOS, такие как «NUL», «CON», «CONIN$», «CONOUT$», «AUX», «PRN», «COM1» и «LPT1».

Примечание

Эта функция приближённо имитирует правила для зарезервированных путей в большинстве систем Windows. Эти правила со временем изменяются в различных выпусках Windows. Эта функция может быть обновлена в будущих выпусках Python по мере широкого распространения изменений в правилах.

Доступность: Windows.

Добавлена в версии 3.13.

os.path.join(path, *paths)

Объединяет один или несколько сегментов пути интеллектуально. Возвращаемое значение — это конкатенация path и всех членов *paths, с ровно одним разделителем каталогов после каждой непустой части, за исключением последней. То есть результат будет содержать разделитель в конце только если последняя часть пуста или заканчивается разделителем. Если сегмент — это абсолютный путь (который в Windows требует как диск, так и корень), все предыдущие сегменты игнорируются, и объединение продолжается с сегмента абсолютного пути.

В Windows диск не сбрасывается при встрече сегмента пути с корнем (например, r'\foo'). Если сегмент находится на другом диске или является абсолютным путём, все предыдущие сегменты игнорируются, и диск сбрасывается. Обратите внимание, что так как есть текущий каталог для каждого диска, os.path.join("c:", "foo") представляет собой путь, относительный к текущему каталогу на диске C: (c:foo), а не к c:\foo.

Изменено в версии 3.6: Принимает объект, подобный пути для path и paths.

os.path.normcase(path)

Нормализует регистр имени пути. В Windows все символы в имени пути преобразуются в нижний регистр, а также слэши заменяются на обратные слэши. В других операционных системах возвращает путь без изменений.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.normpath(path)

Нормализует имя пути, сворачивая избыточные разделители и ссылки на верхний уровень, так что A//B, A/B/, A/./B и A/foo/../B все становятся A/B. Эта манипуляция строками может изменить смысл пути, содержащего символические ссылки. В Windows слэши преобразуются в обратные слэши. Чтобы нормализовать регистр, используйте normcase().

Примечание

В системах POSIX, в соответствии с IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution, если имя пути начинается ровно с двух слэшей, первый компонент, следующий за ведущими символами, может интерпретироваться способом, зависящим от реализации, хотя более чем два ведущих символа обрабатываются как один символ.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.realpath(path, *, strict=False)

Возвращает канонический путь указанного имени файла, устраняя любые символические ссылки, встречающиеся в пути (если они поддерживаются операционной системой). В Windows эта функция также разрешает имена в стиле MS-DOS (также называемые именами 8.3), такие как C:\\PROGRA~1 в C:\\Program Files.

Если путь не существует или обнаружен цикл символических ссылок, и strict равно True, возникает OSError. Если strict равно False, эти ошибки игнорируются, и результат может быть отсутствующим или недоступным по другим причинам.

Примечание

Эта функция эмулирует процедуру операционной системы для получения канонического пути, которая немного отличается между Windows и UNIX в отношении того, как ссылки и последующие компоненты пути взаимодействуют.

API операционной системы делают пути каноническими по мере необходимости, поэтому обычно нет необходимости вызывать эту функцию.

Изменено в версии 3.6: Принимает объект, подобный пути.

Изменено в версии 3.8: Символические ссылки и соединения теперь разрешаются в Windows.

Изменено в версии 3.10: Добавлен параметр strict.

os.path.relpath(path, start=os.curdir)

Возвращает относительный путь к path, либо от текущего каталога, либо от необязательного каталога start. Это вычисление пути: файловая система не используется для подтверждения существования или природы path или start. В Windows при path и start на разных дисках генерируется ValueError.

start по умолчанию равен os.curdir.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.samefile(path1, path2)

Возвращает True, если оба аргумента имени пути ссылаются на один и тот же файл или каталог. Это определяется номером устройства и узла i, и возникает исключение, если вызов os.stat() по любому из имён пути завершается неудачей.

Изменено в версии 3.2: Добавлена поддержка Windows.

Изменено в версии 3.4: Windows теперь использует ту же реализацию, что и все остальные платформы.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.sameopenfile(fp1, fp2)

Возвращает True, если дескрипторы файлов fp1 и fp2 ссылаются на один и тот же файл.

Изменено в версии 3.2: Добавлена поддержка Windows.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.samestat(stat1, stat2)

Возвращает True, если кортежи stat stat1 и stat2 ссылаются на один и тот же файл. Эти структуры могут быть возвращены функциями os.fstat(), os.lstat() или os.stat(). Эта функция реализует базовое сравнение, используемое функциями samefile() и sameopenfile().

Изменено в версии 3.4: Добавлена поддержка Windows.

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.split(path)

Разделяет имя пути path на пару, (head, tail), где tail — последний компонент имени пути, а head — всё, что предшествует ему. Часть tail никогда не будет содержать слэш; если path заканчивается слэшем, tail будет пустой. Если в path нет слэша, head будет пустой. Если path пусто, то head и tail также пустые. Конечные слэши удаляются из head, если это не корень (состоящий только из одного или нескольких слэшей). Во всех случаях, join(head, tail) возвращает путь к тому же расположению, что и path (но строки могут отличаться). Также см. функции dirname() и basename().

Изменено в версии 3.6: Принимает объект, подобный пути.

os.path.splitdrive(path)

Разделить путь path на пару (drive, tail), где drive — это точка монтирования или пустая строка. В системах, не использующих спецификации дисков, drive всегда будет пустой строкой. Во всех случаях, drive + tail будет таким же, как path.

В Windows разделяет путь на диск/совместное использование UNC и относительный путь.

Если путь содержит букву диска, drive будет содержать всё до и включая двоеточие:

>>> splitdrive("c:/dir")
("c:", "/dir")

Если путь содержит UNC-путь, drive будет содержать имя хоста и общий ресурс:

>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")

Изменено в версии 3.6: Принимает объект-путь.

os.path.splitroot(path)

Разделить путь path на тройку (drive, root, tail), где drive — это имя устройства или точка монтирования, root — это строка разделителей после диска, а tail — всё после корня. Любой из этих элементов может быть пустой строкой. Во всех случаях, drive + root + tail будет таким же, как path.

В системах POSIX drive всегда пустая строка. root может быть пустым (если path относительный), одним слешем (если path абсолютный) или двумя слешами (определяется реализацией по IEEE Std 1003.1-2017; 4.13 Pathname Resolution.) Например:

>>> splitroot('/home/sam')
('', '/', 'home/sam')
>>> splitroot('//home/sam')
('', '//', 'home/sam')
>>> splitroot('///home/sam')
('', '/', '//home/sam')

В Windows drive может быть пустой, именем буквы диска, UNC-совместным ресурсом или именем устройства. root может быть пустым, слешем или обратным слешем. Например:

>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')

Добавлена в версии 3.12.

os.path.splitext(path)

Разделить путь path на пару (root, ext) таким образом, что root + ext == path, а расширение ext пустое или начинается с точки и содержит не более одной точки.

Если путь не содержит расширения, ext будет '':

>>> splitext('bar')
('bar', '')

Если путь содержит расширение, то ext будет установлено на это расширение, включая ведущую точку. Обратите внимание, что предыдущие точки будут проигнорированы:

>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')

Ведущие точки последней компоненты пути считаются частью корня:

>>> splitext('.cshrc')
('.cshrc', '')
>>> splitext('/foo/....jpg')
('/foo/....jpg', '')

Изменено в версии 3.6: Принимает объект-путь.

os.path.supports_unicode_filenames

True, если произвольные строки Unicode могут использоваться в качестве имён файлов (в пределах ограничений, накладываемых файловой системой).