`os.path.md`

332 строк · 33.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/os.path.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`os.path`](https://python-all.ru/3.9/library/os.path.html#module-os.path) – Типовые операции с именами путей89**Исходный код:** [Lib/posixpath.py](https://python-all.ru/src/3.9/Lib/posixpath.py) (для POSIX) и [Lib/ntpath.py](https://python-all.ru/src/3.9/Lib/ntpath.py) (для Windows).1011---1213Этот модуль реализует несколько полезных функций для работы с именами путей. Для чтения или записи файлов обратитесь к [`open()`](https://python-all.ru/3.9/library/functions.html#open), а для доступа к файловой системе – к модулю [`os`](https://python-all.ru/3.9/library/os.html#module-os). Параметры пути могут быть переданы в виде строк, байт или любого объекта, реализующего протокол [`os.PathLike`](https://python-all.ru/3.9/library/os.html#os.PathLike).1415В отличие от оболочки Unix, Python не выполняет *автоматического* раскрытия путей. Функции [`expanduser()`](https://python-all.ru/3.9/library/os.path.html#os.path.expanduser) и [`expandvars()`](https://python-all.ru/3.9/library/os.path.html#os.path.expandvars) можно вызывать явно, если приложению требуется раскрытие путей как в оболочке. (См. также модуль [`glob`](https://python-all.ru/3.9/library/glob.html#module-glob).)1617> **См. также**18>19> Модуль [`pathlib`](https://python-all.ru/3.9/library/pathlib.html#module-pathlib) предоставляет высокоуровневые объекты путей.2021> **Примечание**22>23> Все эти функции принимают в качестве параметров только объекты байт или только строки. Если возвращается путь или имя файла, результатом будет объект того же типа.2425> **Примечание**26>27> Поскольку в разных операционных системах разные соглашения об именах путей, в стандартной библиотеке есть несколько версий этого модуля. Модуль [`os.path`](https://python-all.ru/3.9/library/os.path.html#module-os.path) всегда представляет собой модуль путей, подходящий для операционной системы, на которой выполняется Python, и поэтому пригоден для локальных путей. Однако вы также можете импортировать и использовать отдельные модули, если хотите работать с путём, который *всегда* находится в одном из этих форматов. Все они имеют одинаковый интерфейс:28>29> - `posixpath` для путей в стиле UNIX30> - `ntpath` для путей Windows3132Изменено в версии 3.8: [`exists()`](https://python-all.ru/3.9/library/os.path.html#os.path.exists), [`lexists()`](https://python-all.ru/3.9/library/os.path.html#os.path.lexists), [`isdir()`](https://python-all.ru/3.9/library/os.path.html#os.path.isdir), [`isfile()`](https://python-all.ru/3.9/library/os.path.html#os.path.isfile), [`islink()`](https://python-all.ru/3.9/library/os.path.html#os.path.islink) и [`ismount()`](https://python-all.ru/3.9/library/os.path.html#os.path.ismount) теперь возвращают `False` вместо возбуждения исключения для путей, содержащих символы или байты, непредставимые на уровне ОС.3334#### `os.path.abspath(path)`3536Возвращает нормализованную абсолютную версию имени пути *path*. На большинстве платформ это эквивалентно вызову функции [`normpath()`](https://python-all.ru/3.9/library/os.path.html#os.path.normpath) следующим образом: `normpath(join(os.getcwd(), path))`.3738Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).3940#### `os.path.basename(path)`4142Возвращает базовое имя пути *path*. Это второй элемент пары, возвращаемой при передаче *path* функции [`split()`](https://python-all.ru/3.9/library/os.path.html#os.path.split). Обратите внимание, что результат этой функции отличается от программы Unix **basename**; если **basename** для `'/foo/bar/'` возвращает `'bar'`, то функция [`basename()`](https://python-all.ru/3.9/library/os.path.html#os.path.basename) возвращает пустую строку (`''`).4344Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).4546#### `os.path.commonpath(paths)`4748Возвращает самый длинный общий подпуть из каждого пути в последовательности *paths*. Вызывает [`ValueError`](https://python-all.ru/3.9/library/exceptions.html#ValueError), если *paths* содержат как абсолютные, так и относительные пути, если *paths* находятся на разных дисках или если *paths* пуст. В отличие от [`commonprefix()`](https://python-all.ru/3.9/library/os.path.html#os.path.commonprefix), эта функция возвращает корректный путь.4950[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix, Windows.5152Новое в версии 3.5.5354Изменено в версии 3.6: Принимает последовательность [объектов, подобных путям](https://python-all.ru/3.9/glossary.html#term-path-like-object).5556#### `os.path.commonprefix(list)`5758Возвращает самый длинный префикс пути (по одному символу), который является префиксом всех путей в *list*. Если *list* пуст, возвращается пустая строка (`''`).5960> **Примечание**61>62> Эта функция может возвращать некорректные пути, так как она работает по одному символу за раз. Чтобы получить корректный путь, см. [`commonpath()`](https://python-all.ru/3.9/library/os.path.html#os.path.commonpath).63>64> ```python65> >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])66> '/usr/l'67>68> >>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])69> '/usr'70> ```7172Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).7374#### `os.path.dirname(path)`7576Возвращает имя каталога пути *path*. Это первый элемент пары, возвращаемой при передаче *path* функции [`split()`](https://python-all.ru/3.9/library/os.path.html#os.path.split).7778Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).7980#### `os.path.exists(path)`8182Возвращает `True`, если *path* указывает на существующий путь или открытый файловый дескриптор. Возвращает `False` для битых символических ссылок. На некоторых платформах эта функция может вернуть `False`, если нет разрешения на выполнение [`os.stat()`](https://python-all.ru/3.9/library/os.html#os.stat) для запрошенного файла, даже если *path* физически существует.8384Изменено в версии 3.3: *path* теперь может быть целым числом: возвращается `True`, если это открытый файловый дескриптор, и `False` в противном случае.8586Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).8788#### `os.path.lexists(path)`8990Возвращает `True`, если *path* указывает на существующий путь. Возвращает `True` для битых символических ссылок. Эквивалент [`exists()`](https://python-all.ru/3.9/library/os.path.html#os.path.exists) на платформах без [`os.lstat()`](https://python-all.ru/3.9/library/os.html#os.lstat).9192Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).9394#### `os.path.expanduser(path)`9596В Unix и Windows возвращает аргумент, в котором начальный компонент `~` или `~user` заменён на домашний каталог этого *пользователя*.9798В Unix начальный `~` заменяется на значение переменной окружения `HOME`, если она установлена; в противном случае домашний каталог текущего пользователя ищется в базе паролей через встроенный модуль [`pwd`](https://python-all.ru/3.9/library/pwd.html#module-pwd). Начальный `~user` ищется напрямую в базе паролей.99100В Windows используется `USERPROFILE`, если он задан, иначе используется комбинация `HOMEPATH` и `HOMEDRIVE`. Начальный `~user` обрабатывается путём удаления последнего компонента каталога из созданного выше пользовательского пути.101102Если разворачивание не удалось или путь не начинается с тильды, путь возвращается без изменений.103104Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).105106Изменено в версии 3.8: Больше не использует `HOME` в Windows.107108#### `os.path.expandvars(path)`109110Возвращает аргумент с развёрнутыми переменными окружения. Подстроки вида `$name` или `${name}` заменяются значением переменной окружения *name*. Некорректные имена переменных и ссылки на несуществующие переменные остаются без изменений.111112В Windows поддерживаются расширения `%name%` в дополнение к `$name` и `${name}`.113114Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).115116#### `os.path.getatime(path)`117118Возвращает время последнего доступа к *path*. Возвращаемое значение – число с плавающей запятой, представляющее количество секунд с начала эпохи (см. модуль [`time`](https://python-all.ru/3.9/library/time.html#module-time)). Вызывает [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError), если файл не существует или недоступен.119120#### `os.path.getmtime(path)`121122Возвращает время последнего изменения *path*. Возвращаемое значение – число с плавающей запятой, представляющее количество секунд с начала эпохи (см. модуль [`time`](https://python-all.ru/3.9/library/time.html#module-time)). Вызывает [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError), если файл не существует или недоступен.123124Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).125126#### `os.path.getctime(path)`127128Возвращает системное ctime, которое в одних системах (например, Unix) является временем последнего изменения метаданных, а в других (например, Windows) – временем создания для *path*. Возвращаемое значение – число секунд с начала эпохи (см. модуль [`time`](https://python-all.ru/3.9/library/time.html#module-time)). Возбуждает [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError), если файл не существует или недоступен.129130Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).131132#### `os.path.getsize(path)`133134Возвращает размер в байтах *path*. Возбуждает [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError), если файл не существует или недоступен.135136Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).137138#### `os.path.isabs(path)`139140Возвращает `True`, если *path* является абсолютным именем пути. В Unix это означает, что он начинается с косой черты, в Windows – что он начинается с обратной или косой черты после отбрасывания символа диска.141142Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).143144#### `os.path.isfile(path)`145146Возвращает `True`, если *path* является [`existing`](https://python-all.ru/3.9/library/os.path.html#os.path.exists) обычным файлом. Функция следует по символическим ссылкам, поэтому и [`islink()`](https://python-all.ru/3.9/library/os.path.html#os.path.islink), и [`isfile()`](https://python-all.ru/3.9/library/os.path.html#os.path.isfile) могут быть истинны для одного и того же пути.147148Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).149150#### `os.path.isdir(path)`151152Возвращает `True`, если *path* является [`existing`](https://python-all.ru/3.9/library/os.path.html#os.path.exists) каталогом. Функция следует по символическим ссылкам, поэтому и [`islink()`](https://python-all.ru/3.9/library/os.path.html#os.path.islink), и [`isdir()`](https://python-all.ru/3.9/library/os.path.html#os.path.isdir) могут быть истинны для одного и того же пути.153154Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).155156#### `os.path.islink(path)`157158Возвращает `True`, если *path* ссылается на [`existing`](https://python-all.ru/3.9/library/os.path.html#os.path.exists) запись каталога, являющуюся символической ссылкой. Всегда `False`, если символические ссылки не поддерживаются средой выполнения Python.159160Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).161162#### `os.path.ismount(path)`163164Возвращает `True`, если имя пути *path* является *точкой монтирования*: точкой в файловой системе, куда смонтирована другая файловая система. В POSIX функция проверяет, находится ли родительская директория *path*, `path/..`, на другом устройстве, чем *path*, или указывают ли `path/..` и *path* на один и тот же i-node на одном устройстве – это должно обнаруживать точки монтирования для всех вариантов Unix и POSIX. Функция не может надежно обнаруживать bind-монтирования в одной файловой системе. В Windows корень диска (буква диска) и UNC-пути общего доступа всегда являются точками монтирования, а для любого другого пути вызывается `GetVolumePathName`, чтобы проверить, отличается ли он от исходного пути.165166Новое в версии 3.4: Поддержка обнаружения точек монтирования, не являющихся корневыми, в Windows.167168Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).169170#### `os.path.join(path, *paths)`171172Интеллектуально объединяет один или несколько компонентов пути. Возвращаемое значение – это конкатенация *path* и всех элементов *\*paths* с ровно одним разделителем каталогов после каждой непустой части, кроме последней, то есть результат будет заканчиваться разделителем, только если последняя часть пуста. Если компонент является абсолютным путём, все предыдущие компоненты отбрасываются и объединение продолжается с этого абсолютного пути.173174В Windows буква диска не сбрасывается при обнаружении абсолютного компонента пути (например, `r'\foo'`). Если компонент содержит букву диска, все предыдущие компоненты отбрасываются, а буква диска сбрасывается. Обратите внимание, что для каждого диска существует текущий каталог, поэтому `os.path.join("c:", "foo")` представляет собой путь относительно текущего каталога на диске `C:` (`c:foo`), а не `c:\foo`.175176Изменено в версии 3.6: Теперь принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object) для *path* и *paths*.177178#### `os.path.normcase(path)`179180Нормализует регистр имени пути. В Windows преобразует все символы в имени пути в нижний регистр, а также заменяет прямые косые черты на обратные. В других операционных системах возвращает путь без изменений.181182Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).183184#### `os.path.normpath(path)`185186> Нормализует имя пути, удаляя лишние разделители и ссылки на родительский каталог, так что `A//B`, `A/B/`, `A/./B` и `A/foo/../B` все превращаются в `A/B`. Эта строковая операция может изменить значение пути, содержащего символические ссылки. В Windows преобразует прямые косые черты в обратные. Для нормализации регистра используйте [`normcase()`](https://python-all.ru/3.9/library/os.path.html#os.path.normcase).187188> **Примечание**189>190> > В системах POSIX, в соответствии с [IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution](https://python-all.ru/3.9/library/os.path.html), если имя пути начинается ровно с двух косых черт, первый компонент после начальных символов может интерпретироваться способом, определяемым реализацией, хотя более двух начальных символов должны рассматриваться как один символ.191>192> Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).193194#### `os.path.realpath(path, *, strict=False)`195196Возвращает канонический путь указанного имени файла, разрешая все символические ссылки, встречающиеся в пути (если они поддерживаются операционной системой).197198По умолчанию путь вычисляется до первого компонента, который не существует, является циклом символических ссылок или при вычислении которого возникает [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError). Все такие компоненты добавляются без изменений к существующей части пути.199200Некоторые ошибки, обрабатываемые таким образом, включают «в доступе отказано», «не каталог» или «неверный аргумент внутренней функции». Таким образом, результирующий путь может отсутствовать или быть недоступным, все еще содержать ссылки или циклы, а также проходить через не-каталоги.201202Это поведение можно изменить с помощью именованных аргументов:203204Если *strict* равен `True`, первая ошибка, возникшая при вычислении пути, возбуждается повторно. В частности, [`FileNotFoundError`](https://python-all.ru/3.9/library/exceptions.html#FileNotFoundError) возбуждается, если *path* не существует, или другое [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError), если он по другой причине недоступен.205206Если *strict* равен [`os.path.ALLOW_MISSING`](https://python-all.ru/3.9/library/os.path.html#os.path.ALLOW_MISSING), ошибки, отличные от [`FileNotFoundError`](https://python-all.ru/3.9/library/exceptions.html#FileNotFoundError), возбуждаются повторно (как и в случае с `strict=True`). Таким образом, возвращаемый путь не будет содержать символических ссылок, но указанный файл и некоторые из его родительских каталогов могут отсутствовать.207208> **Примечание**209>210> Эта функция эмулирует процедуру операционной системы по приведению пути к каноническому виду, которая немного отличается в Windows и UNIX в отношении того, как взаимодействуют ссылки и последующие компоненты пути.211>212> API операционной системы приводят пути к каноническому виду по мере необходимости, так что обычно нет необходимости вызывать эту функцию.213214Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).215216Изменено в версии 3.8: Символические ссылки и точки соединения теперь разрешаются в Windows.217218Изменено в версии 3.9.23: Добавлен параметр *strict*.219220Изменено в версии 3.9.25 (не выпущена): Добавлено значение [`ALLOW_MISSING`](https://python-all.ru/3.9/library/os.path.html#os.path.ALLOW_MISSING) для параметра *strict* .221222#### `os.path.ALLOW_MISSING`223224Специальное значение, используемое для аргумента *strict* в [`realpath()`](https://python-all.ru/3.9/library/os.path.html#os.path.realpath).225226Новое в версии 3.9.25 (не выпущена).227228#### `os.path.relpath(path, start=os.curdir)`229230Возвращает относительный путь к *path* либо от текущего каталога, либо от указанного *start* каталога. Это вычисление пути: файловая система не опрашивается для подтверждения существования или природы *path* или *start*. В Windows [`ValueError`](https://python-all.ru/3.9/library/exceptions.html#ValueError) возбуждается, когда *path* и *start* находятся на разных дисках.231232*start* по умолчанию равен [`os.curdir`](https://python-all.ru/3.9/library/os.html#os.curdir).233234[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix, Windows.235236Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).237238#### `os.path.samefile(path1, path2)`239240Возвращает `True`, если оба указанных пути ссылаются на один и тот же файл или каталог. Это определяется по номеру устройства и номеру индексного дескриптора; возбуждается исключение, если вызов [`os.stat()`](https://python-all.ru/3.9/library/os.html#os.stat) для любого из путей завершается ошибкой.241242[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix, Windows.243244Изменено в версии 3.2: Добавлена поддержка Windows.245246Изменено в версии 3.4: Теперь в Windows используется та же реализация, что и на всех остальных платформах.247248Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).249250#### `os.path.sameopenfile(fp1, fp2)`251252Возвращает `True`, если файловые дескрипторы *fp1* и *fp2* ссылаются на один и тот же файл.253254[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix, Windows.255256Изменено в версии 3.2: Добавлена поддержка Windows.257258Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).259260#### `os.path.samestat(stat1, stat2)`261262Возвращает `True`, если кортежи stat *stat1* и *stat2* ссылаются на один и тот же файл. Эти структуры могли быть возвращены [`os.fstat()`](https://python-all.ru/3.9/library/os.html#os.fstat), [`os.lstat()`](https://python-all.ru/3.9/library/os.html#os.lstat) или [`os.stat()`](https://python-all.ru/3.9/library/os.html#os.stat). Эта функция реализует сравнение, лежащее в основе [`samefile()`](https://python-all.ru/3.9/library/os.path.html#os.path.samefile) и [`sameopenfile()`](https://python-all.ru/3.9/library/os.path.html#os.path.sameopenfile).263264[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix, Windows.265266Изменено в версии 3.4: Добавлена поддержка Windows.267268Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).269270#### `os.path.split(path)`271272Разделяет имя пути *path* на пару, `(head, tail)` где *tail* – это последний компонент имени пути, а *head* – все, что ему предшествует. Часть *tail* никогда не содержит косую черту; если *path* заканчивается косой чертой, *tail* будет пуст. Если в *path* нет косой черты, *head* будет пуст. Если *path* пуст, то и *head*, и *tail* пусты. Замыкающие косые черты удаляются из *head*, если только он не является корнем (только одна или несколько косых черт). Во всех случаях `join(head, tail)` возвращает путь к тому же расположению, что и *path* (хотя строки могут различаться). Также см. функции [`dirname()`](https://python-all.ru/3.9/library/os.path.html#os.path.dirname) и [`basename()`](https://python-all.ru/3.9/library/os.path.html#os.path.basename).273274Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).275276#### `os.path.splitdrive(path)`277278Разделяет путь *path* на пару `(drive, tail)`, где *drive* – либо точка монтирования, либо пустая строка. В системах, не использующих спецификации дисков, *drive* всегда будет пустой строкой. В любом случае `drive + tail` будет тем же, что и *path*.279280В Windows разделяет путь на диск/UNC-ресурс и относительный путь.281282Если путь содержит букву диска, drive будет содержать всё вплоть до двоеточия включительно:283284```python285>>> splitdrive("c:/dir")286("c:", "/dir")287```288289Если путь содержит UNC-путь, то в drive будет содержаться имя хоста и общая папка (share), вплоть до четвёртого разделителя, не включая его:290291```python292>>> splitdrive("//host/computer/dir")293("//host/computer", "/dir")294```295296Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).297298#### `os.path.splitext(path)`299300Разделяет путь *path* на пару `(root, ext)`, такую что `root + ext == path`, а расширение *ext* пусто или начинается с точки и содержит не более одной точки.301302Если путь не содержит расширения, *ext* будет `''`:303304```python305>>> splitext('bar')306('bar', '')307```308309Если путь содержит расширение, то *ext* будет установлен в это расширение, включая начальную точку. Обратите внимание, что предыдущие точки игнорируются:310311```python312>>> splitext('foo.bar.exe')313('foo.bar', '.exe')314>>> splitext('/foo/bar.exe')315('/foo/bar', '.exe')316```317318Начальные точки последнего компонента пути считаются частью корня:319320```python321>>> splitext('.cshrc')322('.cshrc', '')323>>> splitext('/foo/....jpg')324('/foo/....jpg', '')325```326327Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object).328329#### `os.path.supports_unicode_filenames`330331`True`, если произвольные строки Unicode могут использоваться в качестве имён файлов (с учётом ограничений, накладываемых файловой системой).332