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

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

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

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

Операторы

Оператор косой черты помогает создавать дочерние пути, как 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 для пути даёт сам путь к файлу системы в виде объекта байтов, закодированного функцией os.fsencode():

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

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

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

PurePath.parts

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

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

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

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

Методы и свойства

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

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 Разрешение имен путей:

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

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: Последовательность родителей теперь поддерживает срезы и отрицательные индексы.

PurePath.parent

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

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

Вы не можете перейти за пределы якоря или пустого пути:

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

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

>>> 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 в противном случае.

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

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

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

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

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

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

Создайте новый объект пути того же типа, объединив заданные сегменты пути. Этот метод вызывается всякий раз, когда создается производный путь, например, из 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.

Расширение и разрешение путей

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, генерируется исключение 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.

Определение типа и состояния файла

Path.stat(*, follow_symlinks=True)

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

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

Изменено в версии 3.10: Параметр follow_symlinks был добавлен.

Path.lstat()

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

Path.exists(*, follow_symlinks=True)

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

Этот метод обычно следует за символическими ссылками; чтобы проверить, существует ли символическая ссылка, добавьте аргумент follow_symlinks=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, если путь указывает на соединение, и False для любого другого типа файла. В настоящее время только Windows поддерживает соединения.

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

Path.is_mount()

Возвращает True, если путь является точкой монтирования: точкой в файловой системе, где смонтирована другая файловая система. В POSIX функция проверяет, находится ли родитель path (path/..) на другом устройстве, чем path, или указывают ли path/.. и path на один и тот же узел i на одном и том же устройстве — это должно обнаруживать точки монтирования для всех вариантов 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 может быть возбуждено, если к файлу нельзя получить доступ по какой-либо причине.

Чтение и запись файлов

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

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

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

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

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

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

Path.read_bytes()

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

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

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

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

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

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

Path.write_bytes(data)

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

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

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

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

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)

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

>>> 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: Возвращаются только каталоги, если шаблон заканчивается разделителем компонентов пути (sep или altsep).

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

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

Рекурсивный поиск совпадений заданного относительного шаблона. Это аналогично вызову Path.glob() с добавлением «**/» перед шаблоном, где шаблоны такие же, как в 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: Возвращаются только каталоги, если шаблон заканчивается разделителем компонентов пути (sep или altsep).

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

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 имеет значение 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() не позволяет удалить каталог до тех пор, пока он не будет пустым:

# Delete everything reachable from the directory "top".
# CAUTION:  This is dangerous! For example, if top == Path('/'),
# it could delete all of your files.
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.

Создание файлов и каталогов

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.

Переименование и удаление

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

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

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

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