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

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

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

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

См.также

Модуль pathlib предлагает высокоуровневые объекты пути.

Примечание

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

Примечание

Поскольку в разных операционных системах используются разные соглашения об именах путей, в стандартной библиотеке существует несколько версий этого модуля. Модуль os.path всегда является модулем пути, подходящим для операционной системы, на которой работает Python, и поэтому используется для локальных путей. Однако вы также можете импортировать и использовать отдельные модули, если хотите работать с путями, которые всегда находятся в одном из различных форматов. Все они имеют одинаковый интерфейс:

  • posixpath для путей в стиле UNIX

  • ntpath для путей Windows

Изменено в версии 3.8: exists(), lexists(), isdir(), isfile(), islink() и ismount() теперь возвращают False вместо того, чтобы вызывать исключение для путей, содержащих символы или байты, непредставимые на уровне ОС.

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(), возвращается корректный путь.

Added in version 3.5.

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

Изменено в версии 3.13: Теперь можно передавать любые итерируемые переменные, а не только последовательности.

os.path.commonprefix(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)

Возвращает имя каталога, содержащего имя пути 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 ссылается на существующий путь, включая неработающие символические ссылки. Эквивалентно 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: В Windows больше не используется HOME.

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) - временем создания path. Возвращаемое значение - число, показывающее количество секунд, прошедших с момента эпохи (см. модуль time). Вызывает OSError, если файл не существует или недоступен.

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

os.path.getsize(path)

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

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

os.path.isabs(path)

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

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

Изменено в версии 3.13: В Windows возвращает False, если заданный путь начинается ровно с одного (обратного) слеша.

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.isjunction(path)

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

Added in version 3.12.

Возвращает 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.isdevdrive(path)

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

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

Added in version 3.12.

Изменено в версии 3.13: Функция теперь доступна на всех платформах, и всегда будет возвращать False на тех, где нет поддержки Dev Drives.

os.path.isreserved(path)

Возвращает True, если path является зарезервированным именем пути в текущей системе.

В Windows к зарезервированным именам файлов относятся те, которые заканчиваются пробелом или точкой; те, которые содержат двоеточия (например, файловые потоки типа «имя:поток»), символы подстановки (например, '*?"<>'), трубы или управляющие символы ASCII; а также имена устройств DOS, такие как «NUL», «CON», «CONIN$», «CONOUT$», «AUX», «PRN», «COM1» и «LPT1».

Примечание

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

Availability: Windows.

Added in version 3.13.

os.path.join(path, *paths)

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

В 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)

Возвращает канонический путь к указанному имени файла, устраняя все встречающиеся в пути символические ссылки (если они поддерживаются операционной системой). В Windows эта функция также разрешает имена в стиле MS-DOS (также называемые 8.3), такие как C:\\PROGRA~1 в C:\\Program Files.

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

Значение start по умолчанию равно os.curdir.

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

os.path.samefile(path1, path2)

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

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

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

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

os.path.sameopenfile(fp1, fp2)

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

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

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

os.path.samestat(stat1, stat2)

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

Изменено в версии 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.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 или именем устройства. Корень* может быть пустым, прямым или обратным слешем. Например:

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

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

os.path.supports_unicode_filenames

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