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

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

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

os.path.isdir(path)

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

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

os.path.islink(path)

Возвращает True, если path ссылается на запись каталога, которая является символической ссылкой. Всегда 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)

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

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

os.path.supports_unicode_filenames

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