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

Исходный код: 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(), это возвращает допустимый путь.

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

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

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

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 ссылается на существующий путь. Возвращает True для прерванных символических ссылок. Эквивалентно 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: Больше не использует HOME в Windows.

os.path.expandvars(path)

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

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

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

os.path.getatime(path)

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

os.path.getmtime(path)

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

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

os.path.getctime(path)

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

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

os.path.getsize(path)

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

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

os.path.isabs(path)

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

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

os.path.isfile(path)

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

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

os.path.isdir(path)

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

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

os.path.islink(path)

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

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

os.path.ismount(path)

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

Введено в версии 3.4: Поддержка обнаружения точек монтирования, отличных от корня, в Windows.

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

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)

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

Если путь не существует или встречается цикл символических ссылок, и 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.

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

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

os.path.samefile(path1, path2)

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

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

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

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

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

os.path.sameopenfile(fp1, fp2)

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

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

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

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

os.path.samestat(stat1, stat2)

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

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

Изменено в версии 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.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 могут использоваться в качестве имён файлов (в рамках ограничений, налагаемых файловой системой).