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

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

Этот модуль реализует некоторые полезные функции для работы с именами путей. Для чтения или записи файлов см. open(), а для доступа к файловой системе см. модуль os. Параметры пути могут быть переданы как строки или байты. Приложениям рекомендуется представлять имена файлов в виде (Unicode) строковых значений. К сожалению, некоторые имена файлов могут быть не представлены в виде строк на Unix, поэтому приложениям, которым нужно поддерживать произвольные имена файлов на Unix, следует использовать объекты байтов для представления имён путей. И наоборот, использование объектов байтов не может представить все имена файлов в Windows (в стандартной кодировке mbcs), поэтому приложения Windows должны использовать строковые объекты для доступа ко всем файлам.

В отличие от оболочки 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: В Windows больше не используется HOME.

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 на одной и той же файловой системе. В 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().

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

os.path.realpath(path)

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

Примечание

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

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

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

Если путь содержит букву диска, 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 пустая или начинается с точки и содержит не более одной точки. Ведущие точки в имени файла игнорируются; splitext('.cshrc') возвращает ('.cshrc', '').

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

os.path.supports_unicode_filenames

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