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 для пути возвращает необработанный путь файловой системы в виде объекта 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 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')

Нельзя перейти выше точки привязки или пустого пути:

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

Представляет путь в виде URI file. Если путь не абсолютный, возникает исключение 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.

Разворачивание и разрешение путей

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

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

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

Path.is_mount()

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

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

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.

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

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; шаблоны такие же, как в 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 вызывающему коду каталоги из этого списка уже были обработаны.

По умолчанию ошибки, возникающие в 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()

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

Path.group()

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

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