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

Модуль реализует некоторые полезные функции для имён путей. Для чтения или записи файлов см. open(), а для доступа к файловой системе см. модуль os. Параметры пути могут передаваться в виде строк или байтов. Приложениям рекомендуется представлять имена файлов в виде Юникод строк. К сожалению, некоторые имена файлов не могут быть представлены в виде строк в Unix, поэтому приложения, которым необходимо поддерживать произвольные имена файлов в Unix, должны использовать байтовые объекты для представления имён путей. И наоборот, использование байтовых объектов не может представлять все имена файлов в Windows (в стандартной кодировке mbcs), поэтому приложения Windows должны использовать строковые объекты для доступа ко всем файлам.

В отличие от оболочки Unix, Python не выполняет никаких автоматических расширений пути. Такие функции, как expanduser() и expandvars(), могут вызваться явно, когда приложению требуется расширение пути, подобное оболочке. (См. также модуль glob.)

См.также

Модуль pathlib предлагает высокоуровневые объекты пути.

Примечание

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

Примечание

Поскольку у разных операционных систем разные соглашения об именах путей, в стандартной библиотеке есть несколько версий данного модуля. Модуль os.path всегда является модулем пути, подходящим для операционной системы, в которой работает Python, и, следовательно, может использоваться для локальных путей. Однако вы также можете импортировать и использовать отдельные модули, если хотите управлять путём, который всегда является в одном из различных форматов. У следующих модулей одинаковый интерфейс:

  • posixpath для путей в стиле UNIX
  • ntpath для путей Windows

Изменено в версии 3.8: exists(), lexists(), isdir(), isfile(), islink() и ismount() теперь возвращают False вместо того, чтобы вызывать исключение для путей, содержащих символы или байты, непредставимые на уровне ОС.

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 находится на разных дисках или если 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 на домашний каталог данного user.

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

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

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

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

Изменено в версии 3.8: Больше не использует HOME в Windows.

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

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

os.path.isdir(path)

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

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

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

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

os.path.ismount(path)

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

Добавлено в версии 3.4: Поддержка определения точек монтирования без полномочий root в 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 преобразовать все символы в имени пути в нижний регистр, а также преобразовать косую черту в обратную косую черту. В других операционных системах возвращает путь без изменений.

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

Изменено в версии 3.8: Символические ссылки и переходы теперь разрешены в Windows.

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

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

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

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

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

os.path.samefile(path1, path2)

Возвращает True, если оба аргумента имени пути относятся к одному и тому же файлу или каталогу. Определяется номером устройства и номером i-node и вызывает исключение в случае сбоя вызова 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 точку обмена и относительный путь.

Если путь содержит букву диска, диск будет содержать всё до двоеточия включительно. Например splitdrive("c:/dir") возвращает ("c:", "/dir")

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