os.path – Типовые операции с именами путей¶os.path – Common pathname manipulations

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

Этот модуль реализует несколько полезных функций для работы с именами путей. Для чтения или записи файлов обратитесь к open(), а для доступа к файловой системе – к модулю os. Параметры пути могут быть переданы в виде строк, байт или любого объекта, реализующего протокол os.PathLike.

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

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

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

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

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

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

os.path.islink(path)¶

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

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

os.path.ismount(path)¶

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

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

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

os.path.join(path, *paths)¶

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

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

Примечание

В системах POSIX, в соответствии с IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution, если имя пути начинается ровно с двух косых черт, первый компонент после начальных символов может интерпретироваться способом, определяемым реализацией, хотя более двух начальных символов должны рассматриваться как один символ.

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

os.path.realpath(path, *, strict=False)¶

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

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

Некоторые ошибки, обрабатываемые таким образом, включают «в доступе отказано», «не каталог» или «неверный аргумент внутренней функции». Таким образом, результирующий путь может отсутствовать или быть недоступным, все еще содержать ссылки или циклы, а также проходить через не-каталоги.

Это поведение можно изменить с помощью именованных аргументов:

Если strict равен True, первая ошибка, возникшая при вычислении пути, возбуждается повторно. В частности, FileNotFoundError возбуждается, если path не существует, или другое OSError, если он по другой причине недоступен.

Если strict равен os.path.ALLOW_MISSING, ошибки, отличные от FileNotFoundError, возбуждаются повторно (как и в случае с strict=True). Таким образом, возвращаемый путь не будет содержать символических ссылок, но указанный файл и некоторые из его родительских каталогов могут отсутствовать.

Примечание

Эта функция эмулирует процедуру операционной системы по приведению пути к каноническому виду, которая немного отличается в Windows и UNIX в отношении того, как взаимодействуют ссылки и последующие компоненты пути.

API операционной системы приводят пути к каноническому виду по мере необходимости, так что обычно нет необходимости вызывать эту функцию.

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

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

Изменено в версии 3.10: Добавлен параметр strict.

Изменено в версии 3.10.18: Значение ALLOW_MISSING для параметра строгий было добавлено.

os.path.ALLOW_MISSING¶

Специальное значение, используемое для аргумента strict в realpath().

Новое в версии 3.10.18.

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

Возвращает относительный путь к path либо от текущего каталога, либо от указанного start каталога. Это вычисление пути: файловая система не опрашивается для подтверждения существования или природы path или start. В Windows ValueError возбуждается, когда 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, если кортежи stat 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 будет содержаться имя хоста и общая папка (share), вплоть до четвёртого разделителя, не включая его:

>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")

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

os.path.splitext(path)¶

Разделяет путь path на пару (root, ext), такую что root + ext == path, а расширение ext пусто или начинается с точки и содержит не более одной точки.

Если путь не содержит расширения, ext будет '':

>>> splitext('bar')
('bar', '')

Если путь содержит расширение, то ext будет установлен в это расширение, включая начальную точку. Обратите внимание, что предыдущие точки игнорируются:

>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')

Начальные точки последнего компонента пути считаются частью корня:

>>> splitext('.cshrc')
('.cshrc', '')
>>> splitext('/foo/....jpg')
('/foo/....jpg', '')

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

os.path.supports_unicode_filenames¶

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