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

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

Этот модуль реализует некоторые полезные функции для работы с именами путей. Для чтения или записи файлов см. 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 HOME и USERPROFILE будут использоваться, если они установлены, в противном случае будет использоваться комбинация HOMEPATH и HOMEDRIVE. Начальный ~user обрабатывается удалением последнего компонента каталога из созданного пути пользователя, полученного выше.

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

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

os.path.expandvars(path)

Возвращает аргумент с расширенными переменными окружения. Подстроки вида $name или ${name} заменяются значением переменной окружения name. Неправильные имена переменных и ссылки на несуществующие переменные остаются без изменений.

В Windows дополнительно поддерживаются расширения %name%, $name и ${name}.

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

os.path.getatime(path)

Возвращает время последнего доступа к path. Возвращаемое значение — число, представляющее количество секунд, прошедших с эпохи (см. модуль time). Если файл не существует или недоступен, генерируется исключение OSError.

Если os.stat_float_times() возвращает True, результат будет числом с плавающей запятой.

os.path.getmtime(path)

Возвращает время последнего изменения path. Возвращаемое значение — число, представляющее количество секунд, прошедших с эпохи (см. модуль time). Если файл не существует или недоступен, генерируется исключение OSError.

Если os.stat_float_times() возвращает True, результат будет числом с плавающей запятой.

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

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

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

os.path.join(path, *paths)

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

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

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

os.path.normcase(path)

Нормализация регистра имени пути. В Unix и Mac OS X этот метод возвращает путь без изменений; в файловых системах, нечувствительных к регистру, он преобразует путь в нижний регистр. В Windows он также преобразует косые черты в обратные. Генерирует исключение TypeError, если тип path не является str или bytes (прямо или косвенно через интерфейс os.PathLike).

Изменено в версии 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: Принимает объект-путь.

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

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

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

os.path.splitunc(path)

Устарело начиная с версии 3.1: Используйте splitdrive вместо этого.

Разделяет путь path на пару (unc, rest), где unc — это UNC-точка монтирования (например, r'\\host\mount'), если она есть, а rest — остальная часть пути (например, r'\path\file.ext'). Для путей, содержащих буквы дисков, unc всегда будет пустой строкой.

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

os.path.supports_unicode_filenames

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