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. Оно не может надёжно определять монтирования по связям (bind mounts) на одной и той же файловой системе. В 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 Резолюция пути, если путь начинается ровно с двух косых черт, первый компонент, следующий за ведущими символами, может интерпретироваться способом, определённым реализацией, хотя более двух ведущих символов будут обрабатываться как один символ.

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