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

Исходный код: Lib/genericpath.py, 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 находятся на разных дисках или если paths пусто. В отличие от commonprefix(), это возвращает действительный путь.

Добавлен в версии 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 ссылается на существующий путь, включая сломанные символические ссылки. Эквивалентно exists() на платформах, не имеющих os.lstat().

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

os.path.expanduser(path)

В Unix и Windows возвращает аргумент, в котором начальный компонент ~ или ~user заменен домашним каталогом пользователя 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.isjunction(path)

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

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

os.path.islink(path)

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

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

os.path.ismount(path)

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

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

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

os.path.isdevdrive(path)

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

Может генерировать ошибку для недопустимого пути, например, без распознаваемой буквы диска, но возвращает False на платформах, не поддерживающих диски разработчика. См. документацию Windows для получения информации по включению и созданию дисков разработчика.

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

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

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.

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

os.path.samefile(path1, path2)

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

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

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

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

os.path.sameopenfile(fp1, fp2)

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

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

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

os.path.samestat(stat1, stat2)

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

Изменено в версии 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 разделяет путь на диск/сетевую папку и относительный путь.

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

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

Если путь содержит UNC-путь, drive будет содержать имя хоста и общую папку:

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

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

os.path.splitroot(path)

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

В системах POSIX drive всегда пуста. root может быть пустым (если path относительный), одиночной косой чертой (если path абсолютный) или двумя косыми чертами (в зависимости от реализации, как определено в IEEE Std 1003.1-2017; 4.13 Pathname Resolution.) Например:

>>> splitroot('/home/sam')
('', '/', 'home/sam')
>>> splitroot('//home/sam')
('', '//', 'home/sam')
>>> splitroot('///home/sam')
('', '/', '//home/sam')

В Windows drive может быть пустой, именем буквы диска, UNC-объёмом или именем устройства. root может быть пустым, косой или обратной косой чертой. Например:

>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')

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

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