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

os.path.basename(path)¶

Возвращает базовое имя pathname путь. Это второй элемент пары, возвращаемый при передаче пути функции 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)¶

Возвращает префикс самого длинного пути (берется посимвольно), который является префиксом всех путей в list. Если 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)¶

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

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

os.path.exists(path)¶

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

Изменено в версии 3.3: путь теперь может быть целым числом: 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)¶

Возвращает системное время, которое в некоторых системах (например, Unix) является временем последнего изменения метаданных, а в других (например, Windows) - временем создания path. Возвращаемое значение - это число, указывающее количество секунд, прошедших с момента создания (см. модуль 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. Он не может надежно определить, подключается ли bind к одной и той же файловой системе. В Windows буква диска root и общий UNC всегда являются точками подключения, и для любого другого пути вызывается GetVolumePathName, чтобы проверить, отличается ли он от входного пути.

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

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

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

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

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

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

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 is 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. Это вычисление пути: доступ к файловой системе не осуществляется для подтверждения существования или природы path или start. В Windows значение ValueError возникает, когда path и start находятся на разных дисках.

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

Availability: Unix, Windows.

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

os.path.samefile(path1, path2)¶

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