11.2. os.path – Общие манипуляции с путями¶os.path – Common pathname manipulations

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

Этот модуль реализует несколько полезных функций для работы с путями. Для чтения или записи файлов см. open(), а для доступа к файловой системе – модуль os. Параметры пути могут передаваться как строки (str) или байты (bytes). Приложениям рекомендуется представлять имена файлов в виде строк (Unicode). К сожалению, некоторые имена файлов в Unix невозможно представить в виде строк, поэтому приложениям, которым требуется поддержка произвольных имён файлов в Unix, следует использовать объекты bytes для представления путей. И наоборот: с помощью объектов bytes нельзя представить все имена файлов в 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 заменён на домашний каталог этого пользователя.

В 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, если путь является существующим обычным файлом. Функция следует символическим ссылкам, поэтому оба значения islink() и isfile() могут быть истинными для одного пути.

os.path.isdir(path)¶

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

os.path.islink(path)¶

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

os.path.ismount(path)¶

Возвращает True, если путь path является точкой монтирования: точкой в файловой системе, куда смонтирована другая файловая система. В POSIX функция проверяет, находится ли родитель path, path/.., на другом устройстве, чем path, или указывают ли path/.. и path на один и тот же индексный дескриптор на том же устройстве – это должно выявлять точки монтирования для всех вариантов 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, если тип пути не 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, если оба указанных пути ссылаются на один и тот же файл или каталог. Это определяется по номеру устройства и номеру индексного дескриптора; возбуждается исключение, если вызов 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 будет содержать имя узла и общую папку (share) до четвёртого разделителя, не включая его. Например, splitdrive("//host/computer/dir") возвращает ("//host/computer", "/dir")

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