11.1. os.path – Распространённые манипуляции с путями¶os.path – Common pathname manipulations

Этот модуль реализует несколько полезных функций для работы с путями. Для чтения и записи файлов см. 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.commonprefix(list)¶

Возвращает самый длинный общий префикс путей (посимвольно), который является префиксом всех путей в list. Если list пуст, возвращает пустую строку (''). Обратите внимание: результат может быть некорректным путём, поскольку сравнение выполняется посимвольно.

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 заменяется на домашний каталог этого пользователя.

В 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. Возвращаемое значение – число giving the number of seconds since the epoch (см. модуль 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, если символические ссылки не поддерживаются.

os.path.ismount(path)¶

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

os.path.join(path1[, path2[, ...]])¶

Умно объединяет один или несколько компонентов пути. Если какой-либо компонент является абсолютным путём, все предыдущие компоненты (в Windows, включая предыдущую букву диска, если она была) отбрасываются, и объединение продолжается. Возвращаемое значение – это конкатенация path1 и, опционально, path2 и т.д., с ровно одним разделителем каталогов (os.sep) после каждой непустой части, кроме последней. (Это означает, что пустая последняя часть приведёт к пути, оканчивающемуся разделителем.) Обратите внимание, что в Windows, так как для каждого диска существует текущий каталог, 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=None)¶

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

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

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

os.path.samefile(path1, path2)¶

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

В Windows два файла считаются одинаковыми, если они разрешаются в одно и то же конечное имя пути с помощью вызова Windows API GetFinalPathNameByHandle. Эта функция выбрасывает исключение, если не удаётся получить дескриптор ни для одного из файлов.

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

Изменено в версии 3.2: Добавлена поддержка 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.

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