pathlib – Объектно-ориентированные пути файловой системы

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

Исходный код: Lib/pathlib/

---

Этот модуль предоставляет классы, представляющие пути файловой системы с семантикой, подходящей для разных операционных систем. Классы путей делятся на чистые пути, которые выполняют чисто вычислительные операции без ввода-вывода, и конкретные пути, которые наследуются от чистых путей, но также предоставляют операции ввода-вывода.

Если вы раньше не использовали этот модуль или не уверены, какой класс подходит для вашей задачи, скорее всего, вам нужен Path. Он создаёт конкретный путь для платформы, на которой выполняется код.

Чистые пути полезны в некоторых особых случаях; например:

1. Если вы хотите манипулировать путями Windows на машине Unix (или наоборот). Вы не можете создать WindowsPath при работе на Unix, но можете создать PureWindowsPath.

2. Вы хотите быть уверены, что ваш код только манипулирует путями, не обращаясь к ОС. В этом случае может быть полезно создать экземпляр одного из чистых классов, поскольку они просто не имеют никаких операций доступа к ОС.

Смотрите также

PEP 428: Модуль pathlib – объектно-ориентированные пути файловой системы.

Смотрите также

Для низкоуровневых манипуляций с путями в виде строк можно также использовать модуль os.path.

Basic useОсновное использование

Импорт главного класса:

>>> from pathlib import Path

Перечисление подкаталогов:

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

Перечисление файлов с исходным кодом Python в этом дереве каталогов:

>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]

Навигация внутри дерева каталогов:

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

Запрос свойств пути:

>>> q.exists()
True
>>> q.is_dir()
False

Открытие файла:

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

ExceptionsИсключения

exception pathlib.UnsupportedOperation¶

Исключение, наследуемое от NotImplementedError, возбуждаемое при вызове неподдерживаемой операции над объектом пути.

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

Pure pathsЧистые пути

Объекты чистых путей предоставляют операции по работе с путями, которые на самом деле не обращаются к файловой системе. Существует три способа доступа к этим классам, которые мы также называем разновидностями:

class pathlib.PurePath(*pathsegments)¶

Обобщённый класс, представляющий разновидность пути системы (его создание возвращает либо PurePosixPath, либо PureWindowsPath):

>>> PurePath('setup.py')      # Работа на Unix-машине
PurePosixPath('setup.py')

Каждый элемент pathsegments может быть либо строкой, представляющей сегмент пути, либо объектом, реализующим интерфейс os.PathLike, метод __fspath__() которого возвращает строку, например, другим объектом пути:

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

Если pathsegments пуст, подразумевается текущий каталог:

>>> PurePath()
PurePosixPath('.')

Если сегмент является абсолютным путём, все предыдущие сегменты игнорируются (как в os.path.join()):

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

В Windows диск не сбрасывается при обнаружении корневого относительного сегмента пути (например, r'\foo'):

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

Лишние косые черты и одиночные точки схлопываются, а двойные точки ('..') и ведущие двойные косые ('//') – нет, поскольку это изменило бы смысл пути по разным причинам (например, символические ссылки, UNC-пути):

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('//foo/bar')
PurePosixPath('//foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

(наивный подход сделал бы PurePosixPath('foo/../bar') эквивалентным PurePosixPath('bar'), что неверно, если foo является символической ссылкой на другой каталог)

Объекты чистых путей реализуют интерфейс os.PathLike, что позволяет использовать их везде, где этот интерфейс принимается.

Изменено в версии 3.6: Добавлена поддержка интерфейса os.PathLike.

class pathlib.PurePosixPath(*pathsegments)¶

Подкласс PurePath, эта разновидность пути представляет пути файловых систем, отличных от Windows:

>>> PurePosixPath('/etc/hosts')
PurePosixPath('/etc/hosts')

pathsegments задаётся аналогично PurePath.

class pathlib.PureWindowsPath(*pathsegments)¶

Подкласс PurePath, эта разновидность пути представляет пути файловой системы Windows, включая UNC-пути:

>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments задаётся аналогично PurePath.

Независимо от используемой системы, можно создавать экземпляры всех этих классов, поскольку они не предоставляют ни одной операции, выполняющей системные вызовы.

General propertiesОбщие свойства

Пути неизменяемы и хешируемы. Пути одной разновидности сравнимы и упорядочиваемы. Эти свойства учитывают семантику приведения к одному регистру, присущую разновидности:

>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True

Пути разных разновидностей сравниваются как неравные и не могут быть упорядочены:

>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

OperatorsОператоры

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

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')
>>> p / '/an_absolute_path'
PurePosixPath('/an_absolute_path')
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

Объект пути можно использовать везде, где принимается объект, реализующий os.PathLike:

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

Строковое представление пути – это сам сырой путь файловой системы (в родной форме, например с обратными слешами в Windows), который можно передать любой функции, принимающей путь к файлу в виде строки:

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

Аналогично, вызов bytes для пути возвращает сырой путь файловой системы в виде объекта bytes, закодированного с помощью os.fsencode():

>>> bytes(p)
b'/etc'

Примечание

Вызов bytes рекомендуется только в Unix. В Windows форма Unicode является каноническим представлением путей файловой системы.

Accessing individual partsДоступ к отдельным частям

Для доступа к отдельным «частям» (компонентам) пути используйте следующее свойство:

PurePath.parts¶

Кортеж, предоставляющий доступ к различным компонентам пути:

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

(обратите внимание: диск и локальный корень сгруппированы в одну часть)

Methods and propertiesМетоды и свойства

Чистые пути предоставляют следующие методы и свойства:

PurePath.parser¶

Реализация модуля os.path, используемая для низкоуровневого разбора и соединения путей: либо posixpath, либо ntpath.

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

PurePath.drive¶

Строка, представляющая букву или имя диска, если они есть:

>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
''
>>> PurePosixPath('/etc').drive
''

UNC-ресурсы также считаются дисками:

>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'

PurePath.root¶

Строка, представляющая (локальный или глобальный) корень, если он есть:

>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
''
>>> PurePosixPath('/etc').root
'/'

UNC-ресурсы всегда имеют корень:

>>> PureWindowsPath('//host/share').root
'\\'

Если путь начинается с более чем двух последовательных слешей, PurePosixPath схлопывает их:

>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'

Примечание

Это поведение соответствует спецификации The Open Group Base Specifications Issue 6, параграфу 4.11 Pathname Resolution:

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

PurePath.anchor¶

Конкатенация диска и корня:

>>> PureWindowsPath('c:/Program Files/').anchor
'c:\\'
>>> PureWindowsPath('c:Program Files/').anchor
'c:'
>>> PurePosixPath('/etc').anchor
'/'
>>> PureWindowsPath('//host/share').anchor
'\\\\host\\share\\'

PurePath.parents¶

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

>>> p = PureWindowsPath('c:/foo/bar/setup.py')
>>> p.parents[0]
PureWindowsPath('c:/foo/bar')
>>> p.parents[1]
PureWindowsPath('c:/foo')
>>> p.parents[2]
PureWindowsPath('c:/')

Изменено в версии 3.10: Последовательность parents теперь поддерживает срезы и отрицательные значения индексов.

PurePath.parent¶

Логический родитель пути:

>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')

Нельзя выйти за пределы anchor или пустого пути:

>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')

Примечание

Это чисто лексическая операция, отсюда следующее поведение:

>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')

Если требуется обойти произвольный путь файловой системы вверх, рекомендуется сначала вызвать Path.resolve(), чтобы разрешить символические ссылки и устранить компоненты "..".

PurePath.name¶

Строка, представляющая конечный компонент пути, исключая диск и корень, если таковые имеются:

>>> PurePosixPath('my/library/setup.py').name
'setup.py'

Имена UNC-дисков не учитываются:

>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
''

PurePath.suffix¶

Последняя часть конечного компонента после последней точки, если таковая имеется:

>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
''

Обычно называется расширением файла.

Изменено в версии 3.14: Одиночная точка (".") считается допустимым суффиксом.

PurePath.suffixes¶

Список суффиксов пути, часто называемых расширениями файлов:

>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]

Изменено в версии 3.14: Одиночная точка (".") считается допустимым суффиксом.

PurePath.stem¶

Конечный компонент пути без его суффикса:

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

Изменено в версии 3.14: Одиночная точка (".") считается допустимым суффиксом.

PurePath.as_posix()¶

Возвращает строковое представление пути с прямыми слешами (/):

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

PurePath.is_absolute()¶

Возвращает, является ли путь абсолютным. Путь считается абсолютным, если он содержит и корень, и (если это допускает вариант) диск:

>>> PurePosixPath('/a/b').is_absolute()
True
>>> PurePosixPath('a/b').is_absolute()
False

>>> PureWindowsPath('c:/a/b').is_absolute()
True
>>> PureWindowsPath('/a/b').is_absolute()
False
>>> PureWindowsPath('c:').is_absolute()
False
>>> PureWindowsPath('//some/share').is_absolute()
True

PurePath.is_relative_to(other)¶

Возвращает, является ли данный путь относительным по отношению к пути other.

>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False

Этот метод основан на строках; он не обращается к файловой системе и не обрабатывает сегменты ".." особым образом. Следующий код эквивалентен:

>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False

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

Устарело с версии 3.12, удалено в версии 3.14: Передача дополнительных аргументов устарела; если они указаны, они объединяются с other.

PurePath.joinpath(*pathsegments)¶

Вызов этого метода эквивалентен последовательному объединению пути с каждым из заданных pathsegments:

>>> PurePosixPath('/etc').joinpath('passwd')
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
PurePosixPath('/etc/init.d/apache2')
>>> PureWindowsPath('c:').joinpath('/Program Files')
PureWindowsPath('c:/Program Files')

PurePath.full_match(pattern, *, case_sensitive=None)¶

Сопоставляет этот путь с заданным шаблоном в стиле glob. Возвращает True, если сопоставление успешно, и False в противном случае. Например:

>>> PurePath('a/b.py').full_match('a/*.py')
True
>>> PurePath('a/b.py').full_match('*.py')
False
>>> PurePath('/a/b/c.py').full_match('/a/**')
True
>>> PurePath('/a/b/c.py').full_match('**/*.py')
True

Смотрите также

Язык шаблонов: документация.

Как и в других методах, чувствительность к регистру определяется платформой по умолчанию:

>>> PurePosixPath('b.py').full_match('*.PY')
False
>>> PureWindowsPath('b.py').full_match('*.PY')
True

Установите case_sensitive в True или False, чтобы переопределить это поведение.

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

PurePath.match(pattern, *, case_sensitive=None)¶

Сопоставляет этот путь с заданным нерекурсивным шаблоном в стиле glob. Возвращает True, если сопоставление успешно, и False в противном случае.

Этот метод похож на full_match(), но пустые шаблоны не допускаются (вызывается ValueError), рекурсивный шаблон "**" не поддерживается (он работает как нерекурсивный "*"), и если задан относительный шаблон, сопоставление выполняется справа:

>>> PurePath('a/b.py').match('*.py')
True
>>> PurePath('/a/b/c.py').match('b/*.py')
True
>>> PurePath('/a/b/c.py').match('a/*.py')
False

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

Изменено в версии 3.12: Был добавлен параметр case_sensitive.

PurePath.relative_to(other, walk_up=False)¶

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

>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/')
PurePosixPath('etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other is absolute.

Если walk_up равен false (по умолчанию), путь должен начинаться с other. Если аргумент равен true, для формирования относительного пути могут добавляться записи ... Во всех остальных случаях, например если пути ссылаются на разные диски, возбуждается ValueError:

>>> p.relative_to('/usr', walk_up=True)
PurePosixPath('../etc/passwd')
>>> p.relative_to('foo', walk_up=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not on the same drive as 'foo' OR one path is relative and the other is absolute.

Предупреждение

Эта функция является частью PurePath и работает со строками. Она не проверяет и не обращается к базовой файловой структуре. Это может повлиять на параметр walk_up, так как предполагается, что в пути нет символических ссылок; при необходимости сначала вызовите resolve() для разрешения символических ссылок.

Изменено в версии 3.12: Добавлен параметр walk_up (старое поведение соответствует walk_up=False).

Устарело с версии 3.12, удалено в версии 3.14: Передача дополнительных позиционных аргументов устарела; если они переданы, они объединяются с other.

PurePath.with_name(name)¶

Возвращает новый путь с изменённым name. Если исходный путь не имеет имени, возбуждается ValueError:

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

PurePath.with_stem(stem)¶

Возвращает новый путь с изменённым stem. Если исходный путь не имеет имени, возбуждается ValueError:

>>> p = PureWindowsPath('c:/Downloads/draft.txt')
>>> p.with_stem('final')
PureWindowsPath('c:/Downloads/final.txt')
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_stem('lib')
PureWindowsPath('c:/Downloads/lib.gz')
>>> p = PureWindowsPath('c:/')
>>> p.with_stem('')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

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

PurePath.with_suffix(suffix)¶

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

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
>>> p = PureWindowsPath('README.txt')
>>> p.with_suffix('')
PureWindowsPath('README')

Изменено в версии 3.14: Одиночная точка («.») считается допустимым суффиксом. В предыдущих версиях при передаче одиночной точки возбуждалось ValueError.

PurePath.with_segments(*pathsegments)¶

Создаёт новый объект пути того же типа, объединяя заданные pathsegments. Этот метод вызывается каждый раз, когда создаётся производный путь, например из parent и relative_to(). Подклассы могут переопределить этот метод для передачи информации производным путям, например:

from pathlib import PurePosixPath

class MyPath(PurePosixPath):
    def __init__(self, *pathsegments, session_id):
        super().__init__(*pathsegments)
        self.session_id = session_id

    def with_segments(self, *pathsegments):
        return type(self)(*pathsegments, session_id=self.session_id)

etc = MyPath('/etc', session_id=42)
hosts = etc / 'hosts'
print(hosts.session_id)  # 42

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

Concrete pathsКонкретные пути

Конкретные пути являются подклассами классов чистых путей. В дополнение к операциям, предоставляемым последними, они также предоставляют методы для выполнения системных вызовов над объектами путей. Существует три способа создания конкретных путей:

class pathlib.Path(*pathsegments)¶

Подкласс PurePath, этот класс представляет конкретные пути в стиле путей системы (при создании экземпляра создаётся либо PosixPath, либо WindowsPath):

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments задаётся аналогично PurePath.

class pathlib.PosixPath(*pathsegments)¶

Подкласс Path и PurePosixPath, этот класс представляет конкретные пути файловой системы, отличной от Windows:

>>> PosixPath('/etc/hosts')
PosixPath('/etc/hosts')

pathsegments задаётся аналогично PurePath.

Изменено в версии 3.13: Возбуждает UnsupportedOperation в Windows. В предыдущих версиях вместо этого возбуждалось NotImplementedError.

class pathlib.WindowsPath(*pathsegments)¶

Подкласс Path и PureWindowsPath, этот класс представляет конкретные пути файловой системы Windows:

>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')

pathsegments задаётся аналогично PurePath.

Изменено в версии 3.13: Возбуждает UnsupportedOperation на платформах, отличных от Windows. В предыдущих версиях вместо этого возбуждалось NotImplementedError.

Вы можете создавать экземпляры только того стиля класса, который соответствует вашей системе (разрешение системных вызовов для несовместимых стилей путей может привести к ошибкам или сбоям в вашем приложении):

>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system

Некоторые методы конкретных путей могут возбуждать OSError, если системный вызов завершается ошибкой (например, потому что путь не существует).

Parsing and generating URIsРазбор и создание URI

Объекты конкретных путей могут быть созданы из URI типа 'file', соответствующих RFC 8089, и представлены в виде таких URI.

Примечание

URI файлов не переносимы между машинами с разными кодировками файловой системы.

classmethod Path.from_uri(uri)¶

Возвращает новый объект пути, полученный разбором URI ‘file’. Например:

>>> p = Path.from_uri('file:///etc/hosts')
PosixPath('/etc/hosts')

В Windows пути DOS-устройств и UNC могут быть извлечены из URI:

>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file://server/share')
WindowsPath('//server/share')

Поддерживается несколько вариантов формы:

>>> p = Path.from_uri('file:////server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file://///server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file:c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file:/c|/windows')
WindowsPath('c:/windows')

ValueError возбуждается, если URI не начинается с file:, или разобранный путь не является абсолютным.

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

Изменено в версии 3.14: Если полномочия (authority) URL совпадают с локальным именем хоста, они отбрасываются. В противном случае, если полномочия не пусты и не равны localhost, то в Windows возвращается UNC-путь (как раньше), а на других платформах возбуждается ValueError.

Path.as_uri()¶

Представляет путь в виде URI ‘file’. ValueError возбуждается, если путь не является абсолютным.

>>> p = PosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = WindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

Устарело с версии 3.14, будет удалено в версии 3.19: Вызов этого метода из PurePath, а не из Path возможен, но устарел. Использование методом os.fsencode() делает его строго нечистым.

Expanding and resolving pathsРаскрытие и разрешение путей

classmethod Path.home()¶

Возвращает новый объект пути, представляющий домашний каталог пользователя (как возвращается os.path.expanduser() с конструкцией ~). Если домашний каталог не может быть определён, возбуждается RuntimeError.

>>> Path.home()
PosixPath('/home/antoine')

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

Path.expanduser()¶

Возвращает новый путь с раскрытыми конструкциями ~ и ~user, как возвращается os.path.expanduser(). Если домашний каталог не может быть определён, возбуждается RuntimeError.

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')

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

classmethod Path.cwd()¶

Возвращает новый объект пути, представляющий текущий каталог (как возвращается os.getcwd()):

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')

Path.absolute()¶

Делает путь абсолютным без нормализации или разрешения симлинков. Возвращает новый объект пути:

>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')

Path.resolve(strict=False)¶

Делает путь абсолютным, разрешая все симлинки. Возвращается новый объект пути:

>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')

Компоненты “..” также устраняются (это единственный метод, который это делает):

>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')

Если путь не существует или обнаружен цикл симлинков, и strict равен True, возбуждается OSError. Если strict равен False, путь разрешается насколько это возможно, и любой остаток добавляется без проверки его существования.

Изменено в версии 3.6: Добавлен параметр strict (поведение до версии 3.6 было строгим).

Изменено в версии 3.13: Циклы симлинков обрабатываются как другие ошибки: OSError возбуждается в строгом режиме, и никакого исключения не возбуждается в нестрогом режиме. В предыдущих версиях RuntimeError возбуждалось независимо от значения strict.

Path.readlink()¶

Возвращает путь, на который указывает символическая ссылка (как возвращается os.readlink()):

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')

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

Изменено в версии 3.13: Возбуждает UnsupportedOperation, если os.readlink() недоступно. В предыдущих версиях возбуждалось NotImplementedError.

Querying file type and statusЗапрос типа и состояния файла

Изменено в версии 3.8: exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() теперь возвращают False вместо возбуждения исключения для путей, содержащих символы, непредставимые на уровне ОС.

Изменено в версии 3.14: Указанные выше методы теперь возвращают False вместо возбуждения любого OSError исключения от операционной системы. В предыдущих версиях некоторые виды OSError исключений возбуждались, а другие подавлялись. Новое поведение согласовано с os.path.exists(), os.path.isdir() и т.д. Используйте stat() для получения состояния файла без подавления исключений.

Path.stat(*, follow_symlinks=True)¶

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

Этот метод обычно следует символьным ссылкам; чтобы выполнить stat для символьной ссылки, добавьте аргумент follow_symlinks=False или используйте lstat().

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554

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

Path.lstat()¶

Как Path.stat(), но если путь указывает на символьную ссылку, возвращает информацию о самой символьной ссылке, а не о её цели.

Path.exists(*, follow_symlinks=True)¶

Возвращает True, если путь указывает на существующий файл или каталог. False возвращается, если путь недействителен, недоступен или отсутствует. Используйте Path.stat(), чтобы различать эти случаи.

Этот метод обычно следует символьным ссылкам; чтобы проверить существование символьной ссылки, добавьте аргумент follow_symlinks=False.

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

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

Path.is_file(*, follow_symlinks=True)¶

Возвращает True, если путь указывает на обычный файл. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от обычного файла. Используйте Path.stat(), чтобы различать эти случаи.

Этот метод обычно следует символьным ссылкам; чтобы исключить символьные ссылки, добавьте аргумент follow_symlinks=False.

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

Path.is_dir(*, follow_symlinks=True)¶

Возвращает True, если путь указывает на каталог. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от каталога. Используйте Path.stat(), чтобы различать эти случаи.

Этот метод обычно следует символьным ссылкам; чтобы исключить символьные ссылки на каталоги, добавьте аргумент follow_symlinks=False.

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

Path.is_symlink()¶

Возвращает True, если путь указывает на символьную ссылку, даже если эта ссылка повреждена. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от символьной ссылки. Используйте Path.stat(), чтобы различать эти случаи.

Path.is_junction()¶

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

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

Path.is_mount()¶

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

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

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

Path.is_socket()¶

Возвращает True, если путь указывает на сокет Unix. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от сокета Unix. Используйте Path.stat(), чтобы различать эти случаи.

Path.is_fifo()¶

Возвращает True, если путь указывает на FIFO. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от FIFO. Используйте Path.stat(), чтобы различать эти случаи.

Path.is_block_device()¶

Возвращает True, если путь указывает на блочное устройство. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от блочного устройства. Используйте Path.stat(), чтобы различать эти случаи.

Path.is_char_device()¶

Возвращает True, если путь указывает на символьное устройство. False возвращается, если путь недействителен, недоступен или отсутствует, либо если он указывает на что-то, отличное от символьного устройства. Используйте Path.stat(), чтобы различать эти случаи.

Path.samefile(other_path)¶

Возвращает, указывает ли этот путь на тот же файл, что и other_path, который может быть как объектом Path, так и строкой. Семантика аналогична os.path.samefile() и os.path.samestat().

Исключение OSError может быть возбуждено, если какой-либо из файлов недоступен по какой-либо причине.

>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True

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

Path.info¶

Объект PathInfo, поддерживающий запрос информации о типе файла. Этот объект предоставляет методы, которые кэшируют свои результаты, что может помочь уменьшить количество системных вызовов, необходимых при переключении по типу файла. Например:

>>> p = Path('src')
>>> if p.info.is_symlink():
...     print('symlink')
... elif p.info.is_dir():
...     print('directory')
... elif p.info.exists():
...     print('something else')
... else:
...     print('not found')
...
directory

Если путь был сгенерирован из Path.iterdir(), то этот атрибут инициализируется некоторой информацией о типе файла, полученной при сканировании родительского каталога. Простое обращение к Path.info не выполняет никаких запросов к файловой системе.

Чтобы получить актуальную информацию, лучше вызывать Path.is_dir(), is_file() и is_symlink(), а не методы этого атрибута. Сбросить кэш невозможно; вместо этого можно создать новый объект пути с пустым кэшем информации с помощью p = Path(p).

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

Reading and writing filesЧтение и запись файлов

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)¶

Открывает файл, на который указывает путь, как встроенная функция open():

>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'

Path.read_text(encoding=None, errors=None, newline=None)¶

Возвращает декодированное содержимое файла, на который указывает путь, в виде строки:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

Файл открывается, а затем закрывается. Необязательные параметры имеют то же значение, что и в open().

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

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

Path.read_bytes()¶

Возвращает двоичное содержимое файла, на который указывает путь, в виде объекта bytes:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

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

Path.write_text(data, encoding=None, errors=None, newline=None)¶

Открывает файл, на который указывает путь, в текстовом режиме, записывает в него data и закрывает файл:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

Существующий файл с таким же именем перезаписывается. Необязательные параметры имеют то же значение, что и в open().

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

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

Path.write_bytes(data)¶

Открывает файл, на который указывает путь, в двоичном режиме, записывает в него data и закрывает файл:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

Существующий файл с таким же именем перезаписывается.

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

Reading directoriesЧтение каталогов

Path.iterdir()¶

Когда путь указывает на каталог, возвращает объекты пути содержимого каталога:

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

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

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

Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)¶

Выполняет glob-поиск по заданному относительному шаблону pattern в каталоге, представленном этим путем, возвращая все соответствующие файлы (любого типа):

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]
>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

Примечание

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

Смотрите также

Язык шаблонов документация.

По умолчанию (или когда именованный аргумент case_sensitive установлен в None) этот метод сопоставляет пути, используя правила регистра, зависящие от платформы: как правило, с учётом регистра на POSIX и без учёта регистра на Windows. Установите case_sensitive в True или False, чтобы изменить это поведение.

По умолчанию (или когда именованный аргумент recurse_symlinks установлен в False) этот метод переходит по символьным ссылкам, за исключением случаев раскрытия шаблонов “**”. Установите recurse_symlinks в True, чтобы всегда переходить по символьным ссылкам.

Примечание

Любые исключения OSError, возникающие при сканировании файловой системы, подавляются. Это включает PermissionError при доступе к каталогам без прав на чтение.

Вызывает аудируемое событие pathlib.Path.glob с аргументами self, pattern.

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

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

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

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

Path.rglob(pattern, *, case_sensitive=None, recurse_symlinks=False)¶

Рекурсивно применяет шаблон к указанному относительному pattern. Это аналогично вызову Path.glob() с добавлением “**/” перед pattern.

Примечание

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

Примечание

Любые исключения OSError, возникающие при сканировании файловой системы, подавляются. Это включает PermissionError при доступе к каталогам без прав на чтение.

Смотрите также

Язык шаблонов и документация Path.glob().

Вызывает аудируемое событие pathlib.Path.rglob с аргументами self, pattern.

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

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

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

Path.walk(top_down=True, on_error=None, follow_symlinks=False)¶

Формирует имена файлов в дереве каталогов, обходя дерево либо сверху вниз, либо снизу вверх.

Для каждого каталога в дереве каталогов с корнем self (включая self, но исключая ‘.’ и ‘..’) метод возвращает кортеж из трёх элементов: (dirpath, dirnames, filenames).

dirpath – это Path к текущему обходимому каталогу, dirnames – список строк с именами подкаталогов в dirpath (исключая '.' и '..'), а filenames – список строк с именами некаталожных файлов в dirpath. Чтобы получить полный путь (начинающийся с self) к файлу или каталогу в dirpath, выполните dirpath / name. Отсортированы ли списки, зависит от файловой системы.

Если необязательный аргумент top_down равен истине (значение по умолчанию), то тройка для каталога формируется до троек для любых его подкаталогов (каталоги обходятся сверху вниз). Если top_down равен лжи, тройка для каталога формируется после троек для всех его подкаталогов (каталоги обходятся снизу вверх). Независимо от значения top_down, список подкаталогов извлекается до того, как будут обойдены тройки для каталога и его подкаталогов.

Когда top_down равен истине, вызывающий код может изменить список dirnames на месте (например, используя del или присваивание среза), и Path.walk() будет рекурсивно обходить только те подкаталоги, чьи имена остались в dirnames. Это можно использовать для обрезки поиска, навязывания определённого порядка обхода или даже для информирования Path.walk() о каталогах, которые вызывающий код создаёт или переименовывает до того, как он снова возобновит Path.walk(). Изменение dirnames, когда top_down равен лжи, не влияет на поведение Path.walk(), так как каталоги в dirnames уже были сгенерированы к моменту, когда dirnames передаётся вызывающему коду.

По умолчанию ошибки от os.scandir() игнорируются. Если указан необязательный аргумент on_error, он должен быть вызываемым объектом; он будет вызван с одним аргументом – экземпляром OSError. Вызываемый объект может обработать ошибку, чтобы продолжить обход, или повторно возбудить её, чтобы остановить обход. Обратите внимание, что имя файла доступно как атрибут filename объекта исключения.

По умолчанию Path.walk() не переходит по символьным ссылкам, а добавляет их в список filenames. Установите follow_symlinks в истину, чтобы разрешать символьные ссылки и помещать их в dirnames и filenames в соответствии с их целями и, следовательно, обходить каталоги, на которые указывают символьные ссылки (где это поддерживается).

Примечание

Имейте в виду, что установка follow_symlinks в истину может привести к бесконечной рекурсии, если ссылка указывает на родительский каталог самой себя. Path.walk() не отслеживает уже посещённые каталоги.

Примечание

Path.walk() предполагает, что каталоги, которые он обходит, не изменяются во время выполнения. Например, если каталог из dirnames был заменён символьной ссылкой и follow_symlinks равен лжи, Path.walk() всё равно попытается спуститься в него. Чтобы предотвратить такое поведение, удалите соответствующие каталоги из dirnames.

Примечание

В отличие от os.walk(), Path.walk() перечисляет символьные ссылки на каталоги в filenames, если follow_symlinks равен лжи.

Этот пример показывает количество байтов, используемое всеми файлами в каждом каталоге, игнорируя каталоги __pycache__:

from pathlib import Path
for root, dirs, files in Path("cpython/Lib/concurrent").walk(on_error=print):
  print(
      root,
      "consumes",
      sum((root / file).stat().st_size for file in files),
      "bytes in",
      len(files),
      "non-directory files"
  )
  if '__pycache__' in dirs:
        dirs.remove('__pycache__')

Следующий пример – простая реализация shutil.rmtree(). Обход дерева снизу вверх обязателен, так как rmdir() не позволяет удалить каталог, пока он не пуст:

# Удалить всё, доступное из каталога "top".
# ВНИМАНИЕ: Это опасно! Например, если top == Path('/'),
# это может удалить все ваши файлы.
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()

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

Creating files and directoriesСоздание файлов и каталогов

Path.touch(mode=0o666, exist_ok=True)¶

Создаёт файл по указанному пути. Если задан mode, он комбинируется со значением umask процесса для определения режима файла и флагов доступа. Если файл уже существует, функция завершается успешно, когда exist_ok равен истине (время модификации обновляется до текущего), в противном случае возбуждается FileExistsError.

Смотрите также

Методы open(), write_text() и write_bytes() часто используются для создания файлов.

Path.mkdir(mode=0o777, parents=False, exist_ok=False)¶

Создаёт новый каталог по указанному пути. Если задан mode, он объединяется со значением umask процесса, чтобы определить режим файла и флаги доступа. Если путь уже существует, возбуждается FileExistsError.

Если parents равен true, все недостающие родительские каталоги этого пути создаются по мере необходимости; они создаются с правами по умолчанию без учёта mode (по аналогии с командой POSIX mkdir -p).

Если parents равен false (по умолчанию), отсутствующий родительский каталог вызывает FileNotFoundError.

Если exist_ok равен false (по умолчанию), FileExistsError возбуждается, если целевой каталог уже существует.

Если exist_ok равен true, FileExistsError не возбуждается, если только указанный путь уже существует в файловой системе и не является каталогом (аналогично поведению команды POSIX mkdir -p).

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

Path.symlink_to(target, target_is_directory=False)¶

Делает этот путь символической ссылкой, указывающей на target.

В Windows символическая ссылка представляет собой файл или каталог и не изменяется динамически под объект. Если целевой объект существует, тип ссылки создаётся соответствующим. В противном случае ссылка создаётся как каталог, если target_is_directory равен true, или как файловая ссылка (по умолчанию) в противном случае. На платформах, отличных от Windows, target_is_directory игнорируется.

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
>>> p.stat().st_size
956
>>> p.lstat().st_size
8

Примечание

Порядок аргументов (link, target) противоположен порядку в os.symlink().

Изменено в версии 3.13: Возбуждает UnsupportedOperation, если os.symlink() недоступен. В предыдущих версиях возбуждался NotImplementedError.

Path.hardlink_to(target)¶

Делает этот путь жёсткой ссылкой на тот же файл, что и target.

Примечание

Порядок аргументов (link, target) противоположен порядку в os.link().

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

Изменено в версии 3.13: Возбуждает UnsupportedOperation, если os.link() недоступен. В предыдущих версиях возбуждался NotImplementedError.

Copying, moving and deletingКопирование, перемещение и удаление

Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)¶

Копирует этот файл или дерево каталогов в указанный target и возвращает новый экземпляр Path, указывающий на target.

Если источник – файл, целевой объект будет заменён, если он является существующим файлом. Если источник – символическая ссылка и follow_symlinks равен true (по умолчанию), копируется цель ссылки. В противном случае ссылка воссоздаётся в месте назначения.

Если preserve_metadata равен false (по умолчанию), гарантированно копируются только структуры каталогов и данные файлов. Установите preserve_metadata в true, чтобы обеспечить копирование прав доступа к файлам и каталогам, флагов, времени последнего доступа и изменения, а также расширенных атрибутов (там, где это поддерживается). Этот аргумент не влияет на копирование файлов в Windows (где метаданные всегда сохраняются).

Примечание

Там, где это поддерживается операционной системой и файловой системой, этот метод выполняет облегчённое копирование, при котором блоки данных копируются только при их изменении. Это известно как копирование при записи (copy-on-write).

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

Path.copy_into(target_dir, *, follow_symlinks=True, preserve_metadata=False)¶

Копирует этот файл или дерево каталогов в указанный target_dir, который должен быть существующим каталогом. Остальные аргументы обрабатываются так же, как и в Path.copy(). Возвращает новый экземпляр Path, указывающий на копию.

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

Path.rename(target)¶

Переименовывает этот файл или каталог в указанный target и возвращает новый экземпляр Path, указывающий на target. В Unix, если target существует и является файлом, он будет заменён без предупреждения, если у пользователя есть разрешение. В Windows, если target существует, возбуждается FileExistsError. target может быть строкой или другим объектом пути:

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'

Целевой путь может быть абсолютным или относительным. Относительные пути интерпретируются относительно текущего рабочего каталога, а не каталога объекта Path.

Он реализован с помощью os.rename() и даёт те же гарантии.

Изменено в версии 3.8: Добавлено возвращаемое значение – новый экземпляр Path.

Path.replace(target)¶

Переименовывает этот файл или каталог в указанный target и возвращает новый экземпляр Path, указывающий на target. Если target указывает на существующий файл или пустой каталог, он будет безусловно заменён.

Целевой путь может быть абсолютным или относительным. Относительные пути интерпретируются относительно текущего рабочего каталога, а не каталога объекта Path.

Изменено в версии 3.8: Добавлено возвращаемое значение – возвращается новый экземпляр Path.

Path.move(target)¶

Перемещает этот файл или дерево каталогов в указанный target и возвращает новый экземпляр Path, указывающий на target.

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

Если оба пути находятся в одной файловой системе, перемещение выполняется с помощью os.replace(). В противном случае этот путь копируется (с сохранением метаданных и символических ссылок), а затем удаляется.

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

Path.move_into(target_dir)¶

Перемещает этот файл или дерево каталогов в указанный target_dir, который должен быть существующим каталогом. Возвращает новый экземпляр Path, указывающий на перемещённый путь.

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

Path.unlink(missing_ok=False)¶

Удаляет этот файл или символическую ссылку. Если путь указывает на каталог, используйте Path.rmdir().

Если missing_ok равен False (по умолчанию), возбуждается исключение FileNotFoundError, если путь не существует.

Если missing_ok равен True, исключения FileNotFoundError игнорируются (аналогично поведению команды POSIX rm -f).

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

Path.rmdir()¶

Удаляет этот каталог. Каталог должен быть пустым.

Permissions and ownershipПрава доступа и владение

Path.owner(*, follow_symlinks=True)¶

Возвращает имя пользователя-владельца файла. Исключение KeyError возбуждается, если идентификатор пользователя (UID) файла не найден в системной базе данных.

Этот метод обычно следует символическим ссылкам; чтобы получить владельца самой ссылки, добавьте аргумент follow_symlinks=False.

Изменено в версии 3.13: Возбуждает UnsupportedOperation, если модуль pwd недоступен. В более ранних версиях возбуждалось NotImplementedError.

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

Path.group(*, follow_symlinks=True)¶

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

Этот метод обычно следует символическим ссылкам; чтобы получить группу символической ссылки, добавьте аргумент follow_symlinks=False.

Изменено в версии 3.13: Возбуждает UnsupportedOperation, если модуль grp недоступен. В более ранних версиях возбуждалось NotImplementedError.

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

Path.chmod(mode, *, follow_symlinks=True)¶

Изменяет режим и права доступа к файлу, как os.chmod().

Этот метод обычно следует символическим ссылкам. Некоторые варианты Unix поддерживают изменение прав доступа на самой символической ссылке; на таких платформах можно добавить аргумент follow_symlinks=False или использовать lchmod().

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

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

Path.lchmod(mode)¶

Как Path.chmod(), но если путь указывает на символическую ссылку, изменяется режим символической ссылки, а не её цели.

Pattern languageЯзык шаблонов

В шаблонах для full_match(), glob() и rglob() поддерживаются следующие подстановочные символы:

** (весь сегмент)

Соответствует любому количеству сегментов файла или каталога, включая ноль.

* (весь сегмент)

Соответствует одному сегменту файла или каталога.

* (часть сегмента)

Соответствует любому количеству символов, не являющихся разделителями, включая ноль.

?

Соответствует одному символу, не являющемуся разделителем.

[seq]

Соответствует одному символу из seq, где seq – последовательность символов. Поддерживаются диапазонные выражения; например, [a-z] соответствует любой строчной букве ASCII. Можно комбинировать несколько диапазонов: [a-zA-Z0-9_] соответствует любой букве ASCII, цифре или знаку подчёркивания.

[!seq]

Соответствует одному символу, не входящему в seq, где seq подчиняется тем же правилам, что и выше.

Для точного совпадения заключайте метасимволы в квадратные скобки. Например, "[?]" соответствует символу "?".

Подстановочный символ «**» включает рекурсивный поиск по шаблону. Несколько примеров:

Шаблон	Значение
“**/*”	Любой путь, содержащий хотя бы один сегмент.
“**/*.py”	Любой путь, последний сегмент которого оканчивается на «.py».
“assets/**”	Любой путь, начинающийся с «assets/».
“assets/**/*”	Любой путь, начинающийся с «assets/», за исключением самого «assets/».

Примечание

Поиск с подстановочным символом «**» обходит каждый каталог в дереве. Большие деревья каталогов могут искаться долго.

Изменено в версии 3.13: Поиск по шаблону, оканчивающемуся на «**», возвращает как файлы, так и каталоги. В предыдущих версиях возвращались только каталоги.

В Path.glob() и rglob() к шаблону можно добавить завершающий слеш, чтобы искать только каталоги.

Изменено в версии 3.11: Поиск по шаблону, оканчивающемуся на разделитель компонентов пути (sep или altsep), возвращает только каталоги.

Сравнение с модулем glob

Шаблоны, принимаемые Path.glob() и Path.rglob(), и возвращаемые ими результаты несколько отличаются от тех, что даёт модуль glob:

1. Файлы, начинающиеся с точки, не являются особыми в pathlib. Это аналогично передаче include_hidden=True в glob.glob().

2. Компоненты шаблона «**» всегда рекурсивны в pathlib. Это аналогично передаче recursive=True в glob.glob().

3. Компоненты шаблона «**» по умолчанию не переходят по символическим ссылкам в pathlib. У такого поведения нет аналога в glob.glob(), но для совместимости можно передать recurse_symlinks=True в Path.glob().

4. Как и все объекты PurePath и Path, значения, возвращаемые Path.glob() и Path.rglob(), не содержат завершающих слешей.

5. Значения, возвращаемые path.glob() и path.rglob() из pathlib, содержат путь в качестве префикса, в отличие от результатов glob.glob(root_dir=path).

6. Значения, возвращаемые path.glob() и path.rglob() из pathlib, могут включать сам путь, например при поиске «**», тогда как результаты glob.glob(root_dir=path) никогда не содержат пустую строку, которая соответствовала бы пути.

Сравнение с модулями os и os.path

pathlib реализует операции с путями с помощью объектов PurePath и Path, поэтому его называют объектно-ориентированным. С другой стороны, модули os и os.path предоставляют функции, работающие с низкоуровневыми объектами str и bytes, что является более процедурным подходом. Некоторые пользователи считают объектно-ориентированный стиль более читаемым.

Многие функции в os и os.path поддерживают bytes пути и пути, относительные к дескрипторам каталогов. Эти возможности недоступны в pathlib.

Типы str и bytes в Python, а также части модулей os и os.path написаны на C и очень быстры. pathlib написан на чистом Python и часто медленнее, но редко настолько, чтобы это имело значение.

Нормализация путей в pathlib более строгая и последовательная, чем в os.path. Например, тогда как os.path.abspath() удаляет из пути сегменты «..», что может изменить его значение при наличии символических ссылок, Path.absolute() сохраняет эти сегменты для большей безопасности.

Нормализация путей в pathlib может сделать его непригодным для некоторых применений:

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

2. pathlib нормализует Path("./my_program") в Path("my_program"), что изменяет значение пути при использовании в качестве пути поиска исполняемых файлов, например в оболочке или при запуске дочернего процесса. В частности, отсутствие разделителя в пути может привести к его поиску в PATH, а не в текущем каталоге.

Вследствие этих различий pathlib не является прямой заменой для os.path.

Corresponding toolsСоответствующие инструменты

Ниже приведена таблица, сопоставляющая различные функции os с их эквивалентами в PurePath/Path.

os и os.path	pathlib
os.path.dirname()	PurePath.parent
os.path.basename()	PurePath.name
os.path.splitext()	PurePath.stem, PurePath.suffix
os.path.join()	PurePath.joinpath()
os.path.isabs()	PurePath.is_absolute()
os.path.relpath()	PurePath.relative_to() [1]
os.path.expanduser()	Path.expanduser() [2]
os.path.realpath()	Path.resolve()
os.path.abspath()	Path.absolute() [3]
os.path.exists()	Path.exists()
os.path.isfile()	Path.is_file()
os.path.isdir()	Path.is_dir()
os.path.islink()	Path.is_symlink()
os.path.isjunction()	Path.is_junction()
os.path.ismount()	Path.is_mount()
os.path.samefile()	Path.samefile()
os.getcwd()	Path.cwd()
os.stat()	Path.stat()
os.lstat()	Path.lstat()
os.listdir()	Path.iterdir()
os.walk()	Path.walk() [4]
os.mkdir(), os.makedirs()	Path.mkdir()
os.link()	Path.hardlink_to()
os.symlink()	Path.symlink_to()
os.readlink()	Path.readlink()
os.rename()	Path.rename()
os.replace()	Path.replace()
os.remove(), os.unlink()	Path.unlink()
os.rmdir()	Path.rmdir()
os.chmod()	Path.chmod()
os.lchmod()	Path.lchmod()

Сноски

[1]

os.path.relpath() вызывает abspath() для преобразования путей в абсолютные и удаления частей «..», тогда как PurePath.relative_to() является лексической операцией, которая вызывает ValueError, если якоря (anchors) входных путей различаются (например, если один путь абсолютный, а другой относительный).

[2]

os.path.expanduser() возвращает путь без изменений, если домашний каталог не может быть определён, тогда как Path.expanduser() вызывает RuntimeError.

[3]

os.path.abspath() удаляет компоненты «..» без разрешения символических ссылок, что может изменить значение пути, тогда как Path.absolute() оставляет любые компоненты «..» в пути.

[4]

os.walk() всегда переходит по символическим ссылкам при категоризации путей на имена каталогов и имена файлов, тогда как Path.walk() категоризует все символические ссылки как имена файлов, когда follow_symlinks имеет значение false (по умолчанию).

ProtocolsПротоколы

Модуль pathlib.types предоставляет типы для статической проверки типов.

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

class pathlib.types.PathInfo¶

typing.Protocol, описывающий атрибут Path.info. Реализации могут возвращать кэшированные результаты своих методов.

exists(*, follow_symlinks=True)¶

Возвращает True, если путь существует как файл, каталог или любой другой тип файла; возвращает False, если путь не существует.

Если follow_symlinks равен False, возвращает True для символических ссылок без проверки существования их целей.

is_dir(*, follow_symlinks=True)¶

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

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

is_file(*, follow_symlinks=True)¶

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

Если follow_symlinks равен False, возвращает True только если путь является файлом (без перехода по символическим ссылкам); возвращает False, если путь является каталогом или другим не-файлом, или если он не существует.

is_symlink()¶

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