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

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

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

PurePath.drive

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

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

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

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

PurePath.root

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

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

У сетевых ресурсов UNC всегда есть корень:

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

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

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

Примечание

Это поведение соответствует документу The Open Group Base Specifications Issue 6, пункту 4.11 Разрешение имени пути:

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

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

Изменено в версии 3.13: Имена путей Windows, содержащие двоеточие или заканчивающиеся точкой либо пробелом, считаются зарезервированными. UNC-пути также могут быть зарезервированы.

Устарело с версии 3.13, будет удалено в версии 3.15: Этот метод устарел; для обнаружения зарезервированных путей в Windows используйте os.path.isreserved().

PurePath.joinpath(*pathsegments)

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

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

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

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

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

См. также

Документацию по языку шаблонов.

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

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

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

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

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

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

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

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

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

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

PurePath.relative_to(other, walk_up=False)

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

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

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

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

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

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

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

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

PurePath.with_name(name)

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

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

PurePath.with_stem(stem)

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

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

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

PurePath.with_suffix(suffix)

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

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

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.

Разбор и создание URI

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

classmethod Path.from_uri(uri)

Возвращает новый объект пути, созданный путём разбора URI «file». Например:

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

В Windows из URI можно разбирать пути к устройствам DOS и пути UNC:

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

Поддерживаются несколько вариантов записи:

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

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

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

Path.as_uri()

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

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

По историческим причинам этот метод также доступен для объектов PurePath. Однако использование им os.fsencode() делает его строго нечистым.

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

classmethod Path.home()

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

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

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

Path.expanduser()

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

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

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

classmethod Path.cwd()

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

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

Path.absolute()

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

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

Path.resolve(strict=False)

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

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

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

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

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

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

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

Path.readlink()

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

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

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

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

Проверка типа и состояния файла

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(*, follow_symlinks=True)

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

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

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

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

Path.is_dir(*, follow_symlinks=True)

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

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

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

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

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, newline=None)

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

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

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

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

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

Path.read_bytes()

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

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

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

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

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

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

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

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

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

Path.write_bytes(data)

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

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

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

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

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

Path.iterdir()

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

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

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

Если путь не указывает на каталог или каталог недоступен по другой причине, возникает исключение OSError.

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

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

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

См. также

Документацию по языку шаблонов.

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

По умолчанию, а также если аргумент, передаваемый только по ключевому слову, recurse_symlinks имеет значение False, этот метод переходит по символическим ссылкам, кроме случаев раскрытия подстановочных знаков «**». Задайте для recurse_symlinks значение True, чтобы всегда переходить по символическим ссылкам.

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

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

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

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

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

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

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

См. также

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

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

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

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

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

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

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

Для каждого каталога в дереве, корнем которого является self (включая self, но исключая «.» и «..»), метод возвращает 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 в соответствии с типом их целевых объектов и, следовательно, посещать каталоги, на которые указывают символические ссылки (если это поддерживается).

Примечание

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

Примечание

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

Примечание

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

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

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

Path.hardlink_to(target)

Создаёт для этого пути жёсткую ссылку на тот же файл, на который указывает target.

Примечание

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

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

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

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

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(*, follow_symlinks=True)

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

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

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

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

Path.group(*, follow_symlinks=True)

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

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

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

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

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

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

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

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

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

Path.lchmod(mode)

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

Соответствующие средства

В таблице ниже сопоставлены различные функции os и соответствующие им аналоги в PurePath/Path.

Сноски