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

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

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

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

os.path.abspath(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.basename(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.commonpath(paths)¶

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

Availability: Unix, Windows.

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

Изменено в версии 3.6: Принимает последовательность path-like objects.

os.path.commonprefix(list)¶

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

Примечание

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

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

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

Изменено в версии 3.6: Принимает path-like object.

os.path.dirname(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.exists(path)¶

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

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

Изменено в версии 3.6: Принимает path-like object.

os.path.lexists(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.expanduser(path)¶

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

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

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

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

Изменено в версии 3.6: Принимает path-like object.

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

os.path.expandvars(path)¶

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

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

Изменено в версии 3.6: Принимает path-like object.

os.path.getatime(path)¶

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

os.path.getmtime(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.getctime(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.getsize(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.isabs(path)¶

Верните True, если path является абсолютным именем пути. В Unix это означает, что оно начинается со слэша, в Windows - что оно начинается с (обратного) слэша после отсечения потенциальной буквы диска.

Изменено в версии 3.6: Принимает path-like object.

os.path.isfile(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.isdir(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.islink(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.ismount(path)¶

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

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

Изменено в версии 3.6: Принимает path-like object.

os.path.join(path, *paths)¶

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

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

Изменено в версии 3.6: Принимает path-like object для path и paths.

os.path.normcase(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

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: Принимает path-like object.

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

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

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

Примечание

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

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

Изменено в версии 3.6: Принимает path-like object.

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

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

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

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

По умолчанию start имеет значение os.curdir.

Availability: Unix, Windows.

Изменено в версии 3.6: Принимает path-like object.

os.path.samefile(path1, path2)¶

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

Availability: Unix, Windows.

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

Изменено в версии 3.4: В Windows теперь используется та же реализация, что и на всех других платформах.

Изменено в версии 3.6: Принимает path-like object.

os.path.sameopenfile(fp1, fp2)¶

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

Availability: Unix, Windows.

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

Изменено в версии 3.6: Принимает path-like object.

os.path.samestat(stat1, stat2)¶

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

Availability: Unix, Windows.

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

Изменено в версии 3.6: Принимает path-like object.

os.path.split(path)¶

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

Изменено в версии 3.6: Принимает path-like object.

os.path.splitdrive(path)¶

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

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

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

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

Если путь содержит UNC-путь, диск будет содержать имя хоста и ресурс, вплоть до четвертого разделителя:, но не включая его:

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

Изменено в версии 3.6: Принимает path-like object.

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: Принимает path-like object.

os.path.supports_unicode_filenames¶

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