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

os.path.basename(path)

Возвращает имя базового файла имени пути path. Это второй элемент пары, возвращаемой при передаче path функции split(). Обратите внимание, что результат этой функции отличается от программы Unix basename; где basename для '/foo/bar/' возвращает 'bar', функция basename() возвращает пустую строку ('').

os.path.commonpath(paths)

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

Доступность: Unix, Windows

Введено в версии 3.5.

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'

os.path.dirname(path)

Возвращает имя каталога имени пути path. Это первый элемент пары, возвращаемой при передаче path функции split().

os.path.exists(path)

Возвращает True если path ссылается на существующий путь или открытый дескриптор файла. Возвращает False для прерванных символических ссылок. На некоторых платформах эта функция может возвращать False если разрешение на выполнение os.stat() для запрошенного файла не предоставлено, даже если path физически существует.

Изменено в версии 3.3: path теперь может быть целым числом: True возвращается, если это открытый дескриптор файла, False в противном случае.

os.path.lexists(path)

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

os.path.expanduser(path)

В Unix и Windows возвращает аргумент с начальным компонентом ~ или ~user , заменённый домашним каталогом пользователя user.

В Unix начальное ~ заменяется переменной окружения HOME, если она задана; в противном случае домашний каталог текущего пользователя находится в каталоге паролей через встроенный модуль pwd. Начальное ~user ищется непосредственно в каталоге паролей.

В Windows, HOME и USERPROFILE будут использоваться, если заданы, в противном случае будет использоваться комбинация HOMEPATH и HOMEDRIVE. Начальное ~user обрабатывается удалением последнего компонента каталога из созданного выше пути пользователя.

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

os.path.expandvars(path)

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

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

os.path.getatime(path)

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

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

os.path.getmtime(path)

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

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

os.path.getctime(path)

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

os.path.getsize(path)

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

os.path.isabs(path)

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

os.path.isfile(path)

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

os.path.isdir(path)

Возвращает True если path - это существующий каталог. Это следует за символическими ссылками, поэтому как islink(), так и isdir() могут быть истинными для одного и того же пути.

os.path.islink(path)

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

os.path.ismount(path)

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

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

os.path.join(path, *paths)

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

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

os.path.normcase(path)

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

os.path.normpath(path)

Нормализует имя пути, сворачивая избыточные разделители и ссылки на верхние уровни, так что A//B, A/B/, A/./B и A/foo/../B все становятся A/B. Эта обработка строк может изменить значение пути, содержащего символические ссылки. В Windows она преобразует прямые слеши в обратные. Для нормализации регистра используйте normcase().

os.path.realpath(path)

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

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

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

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

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

os.path.samefile(path1, path2)

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

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

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

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

os.path.sameopenfile(fp1, fp2)

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

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

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

os.path.samestat(stat1, stat2)

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

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

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

os.path.split(path)

Разделяет имя пути path на пару (head, tail), где tail - последняя компонента имени пути, а head - все, что идет перед ней. Часть tail никогда не будет содержать слеш; если path оканчивается на слеш, tail будет пустым. Если в path нет слеша, head будет пустым. Если path пустое, то head и tail тоже пустые. Конечные слеши удаляются из head, если это не корень (только один или несколько слешей). Во всех случаях join(head, tail) возвращает путь к тому же расположению, что и path (но строки могут отличаться). Также обратите внимание на функции dirname() и basename().

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

os.path.splitext(path)

Разделяет имя пути path на пару (root, ext), такую, что root + ext == path, и ext пустая или начинается с точки и содержит не более одной точки. Ведущие точки в имени файла игнорируются; splitext('.cshrc') возвращает ('.cshrc', '').

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