os.path — Общие операции с путями

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

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

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

os.path.abspath(path)

Возвращает нормализованную абсолютную версию пути path. На большинстве платформ это эквивалентно вызову normpath(join(os.getcwd(), path)).

В Windows путь нормализуется операционной системой, поэтому результат может отличаться от normpath(join(os.getcwd(), path)). Путь относительно диска разрешается относительно текущего каталога указанного диска, а буква диска переводится в верхний регистр. Конечные точки и пробелы удаляются. Например:

>>> os.path.abspath('c:spam')
'C:\\Temp\\spam'
>>> os.path.abspath('c:/temp/spam. . .')
'c:\\temp\\spam'

См. также

os.path.join() и os.path.normpath().

Изменено в версии 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(), эта функция возвращает корректный путь.

Добавлено в версии 3.5.

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

Изменено в версии 3.13: Теперь можно передавать любой итерируемый объект, а не только последовательности.

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 указывает на существующий путь, включая неработающие символические ссылки. На платформах, где отсутствует os.lstat(), эквивалентна exists().

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

os.path.expanduser(path)

В Unix и Windows возвращает аргумент, заменяя начальный компонент ~ или ~user домашним каталогом этого пользователя.

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

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

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

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

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

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 — что он начинается с двух обратных косых черт или с буквы диска, двоеточия и обратной косой черты.

См. также

abspath()

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

Изменено в версии 3.13: В Windows возвращает False, если указанный путь начинается ровно с одной обратной косой черты.

os.path.isfile(path)

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

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

os.path.isdir(path, /)

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

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

os.path.isjunction(path)

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

Добавлено в версии 3.12.

os.path.islink(path)

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

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

os.path.ismount(path)

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

Изменено в версии 3.4: Добавлена поддержка обнаружения точек монтирования, не являющихся корнем, в Windows.

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

os.path.isdevdrive(path)

Возвращает True, если путь path находится на диске разработки Windows (Dev Drive). Диск разработки оптимизирован для задач разработчиков и обеспечивает более высокую производительность при чтении и записи файлов. Его рекомендуется использовать для исходного кода, временных каталогов сборки, кэшей пакетов и других операций с интенсивным вводом-выводом.

Для некорректного пути, например пути без распознаваемого диска, может быть возбуждено исключение, однако на платформах, не поддерживающих диски разработки, возвращается False. Информацию о включении и создании дисков разработки см. в документации Windows.

Добавлено в версии 3.12.

Изменено в версии 3.13: Теперь функция доступна на всех платформах и всегда возвращает False на платформах, не поддерживающих диски разработки.

os.path.isreserved(path)

Возвращает True, если path является зарезервированным путём в текущей системе.

В Windows к зарезервированным именам файлов относятся имена, заканчивающиеся пробелом или точкой; содержащие двоеточия (то есть потоки файлов, например «name:stream»), подстановочные символы (то есть '*?"<>'), символ вертикальной черты или управляющие символы ASCII; а также имена устройств DOS, такие как «NUL», «CON», «CONIN$», «CONOUT$», «AUX», «PRN», «COM1» и «LPT1».

Примечание

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

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

Добавлено в версии 3.13.

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

Интеллектуально объединяет один или несколько сегментов пути. Возвращаемое значение — результат соединения path и всех элементов *paths, при котором после каждой непустой части, кроме последней, ставится ровно один разделитель каталогов. То есть результат заканчивается разделителем только в том случае, если последняя часть пуста или заканчивается разделителем.

Если сегмент является абсолютным путём (в Windows для этого требуются и диск, и корень), все предыдущие сегменты игнорируются, а объединение продолжается с абсолютного сегмента. Например, в Linux:

>>> os.path.join('/home/foo', 'bar')
'/home/foo/bar'
>>> os.path.join('/home/foo', '/home/bar')
'/home/bar'

В Windows при встрече сегмента пути с корнем (например, r'\foo') диск не сбрасывается. Если сегмент относится к другому диску или является абсолютным путём, все предыдущие сегменты игнорируются, а диск сбрасывается. Например:

>>> os.path.join('c:\\', 'foo')
'c:\\foo'
>>> os.path.join('c:\\foo', 'd:\\bar')
'd:\\bar'

Обратите внимание: поскольку для каждого диска существует текущий каталог, 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 года; 4.13 Разрешение имён путей, если путь начинается ровно с двух косых черт, первый компонент после начальных символов может интерпретироваться способом, определяемым реализацией, тогда как более двух начальных символов должны обрабатываться как один символ.

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

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

Возвращает канонический путь указанного имени файла, устраняя все встреченные в пути символические ссылки (если операционная система их поддерживает). В Windows эта функция также разрешает имена в стиле MS-DOS (также называемые 8.3), например C:\\PROGRA~1 в C:\\Program Files. В возвращаемом пути используется регистр, указанный операционной системой; он может отличаться от регистра в path, в частности буква диска переводится в верхний регистр.

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

os.path.ALLOW_MISSING

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

Добавлено в версии 3.14.

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

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

По умолчанию start имеет значение os.curdir.

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

os.path.samefile(path1, path2, /)

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

Изменено в версии 3.2: Добавлена поддержка Windows.

Изменено в версии 3.4: В Windows теперь используется та же реализация, что и на всех остальных платформах.

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

os.path.sameopenfile(fp1, fp2)

Возвращает True, если файловые дескрипторы fp1 и fp2 указывают на один и тот же файл.

Изменено в версии 3.2: Добавлена поддержка Windows.

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

os.path.samestat(stat1, stat2, /)

Возвращает True, если кортежи stat stat1 и stat2 относятся к одному и тому же файлу. Эти структуры могли быть возвращены функциями os.fstat(), os.lstat() или os.stat(). Эта функция реализует базовое сравнение, используемое функциями samefile() и sameopenfile().

Изменено в версии 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 (но строки могут различаться). См. также функции join(), 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.splitroot(path, /)

Разбивает путь path на кортеж из 3 элементов (drive, root, tail), где drive — имя устройства или точка монтирования, root — строка разделителей после диска, а tail — всё, что следует за корнем. Любой из этих элементов может быть пустой строкой. Во всех случаях drive + root + tail будет совпадать с path.

В системах POSIX drive всегда пуст. root может быть пустым (если path относительный), состоять из одной прямой косой черты (если path абсолютный) или из двух прямых косых черт (как определено реализацией согласно IEEE Std 1003.1-2017; 4.13 Pathname Resolution). Например:

>>> splitroot('/home/sam')
('', '/', 'home/sam')
>>> splitroot('//home/sam')
('', '//', 'home/sam')
>>> splitroot('///home/sam')
('', '/', '//home/sam')

В Windows drive может быть пустым, именем диска с буквой, сетевым ресурсом UNC или именем устройства. root может быть пустым, прямой или обратной косой чертой. Например:

>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')

Добавлено в версии 3.12.

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 (с учётом ограничений файловой системы).