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

Общие свойства¶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'

Доступ к отдельным частям¶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.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
''

PurePath.suffixes¶

Список расширений файлов пути:

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

PurePath.stem¶

Последний компонент пути без суффикса:

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

PurePath.as_posix()¶

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

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

PurePath.as_uri()¶

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

>>> p = PurePosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = PureWindowsPath('c:/Windows')
>>> p.as_uri()
'file:///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.is_reserved()¶

С PureWindowsPath возвращает True, если путь считается зарезервированным в Windows, иначе False. С PurePosixPath всегда возвращается False.

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

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

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.match(pattern, *, case_sensitive=None)¶

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

Если pattern является относительным, путь может быть как относительным, так и абсолютным, и сопоставление выполняется с правого конца:

>>> 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

Если pattern является абсолютным, путь должен быть абсолютным, и должен совпадать весь путь:

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

В качестве pattern может выступать другой объект пути; это ускоряет сопоставление одного и того же шаблона с несколькими файлами:

>>> pattern = PurePath('*.py')
>>> PurePath('a/b.py').match(pattern)
True

Примечание

Рекурсивный шаблон «**» не поддерживается этим методом (он работает как нерекурсивный «*»).

Изменено в версии 3.12: Принимает объект, реализующий интерфейс os.PathLike.

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

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

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

Изменено в версии 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')

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.

Расширение и разрешение путей¶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()¶

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

>>> 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, возникает FileNotFoundError. Если strict равен False, путь разрешается настолько, насколько возможно, и остаток добавляется без проверки на существование. Если во время разрешения пути встречается бесконечный цикл, возникает RuntimeError.

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

Path.readlink()¶

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

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

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

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

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, если путь указывает на существующий файл или каталог.

Этот метод обычно следует по симлинкам; чтобы проверить существование симлинка, добавьте аргумент 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()¶

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

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

Path.is_dir()¶

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

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

Path.is_symlink()¶

Возвращает True, если путь указывает на символическую ссылку, иначе False.

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

Path.is_junction()¶

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

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

Path.is_mount()¶

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

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

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

Path.is_socket()¶

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

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

Path.is_fifo()¶

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

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

Path.is_block_device()¶

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

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

Path.is_char_device()¶

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

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

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.

Чтение и запись файлов¶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)¶

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

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

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

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

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)¶

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

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

Шаблоны такие же, как для fnmatch, с добавлением «**», что означает «этот каталог и все подкаталоги, рекурсивно». Иными словами, это включает рекурсивный поиск по шаблону:

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

Этот метод вызывает Path.is_dir() для корневого каталога и распространяет любое возникшее исключение OSError. Последующие исключения OSError при сканировании каталогов подавляются.

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

Примечание

Использование шаблона «**» в больших деревьях каталогов может занять чрезмерно много времени.

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

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

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

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

Рекурсивно ищет по заданному относительному шаблону pattern. Это аналогично вызову Path.glob() с добавлением «**/» перед pattern, где patterns такие же, как для fnmatch:

>>> sorted(Path().rglob("*.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, чтобы переопределить это поведение.

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

Примечание

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

Этот пример показывает количество байтов, используемых всеми файлами в каждом каталоге, игнорируя каталоги __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 равен true (время модификации обновляется до текущего), в противном случае возбуждается 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

Примечание

Порядок аргументов (ссылка, цель) обратный по сравнению с os.symlink().

Path.hardlink_to(target)¶

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

Примечание

Порядок аргументов (ссылка, цель) обратный по сравнению с os.link().

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

Переименование и удаление¶Renaming and deleting

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

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

Path.group()¶

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

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(), но если путь указывает на символьную ссылку, то изменяется режим самой символьной ссылки, а не её цели.