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 обрабатывается удалением последнего компонента каталога из созданного пути пользователя, полученного выше.

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

Изменено в версии 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 буква диска не сбрасывается при встрече компонента абсолютного пути (например, 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)

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

Примечание

При возникновении циклов символических ссылок возвращаемый путь будет одним из элементов цикла, но никакой гарантии относительно этого элемента не дается.

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

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

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

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

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