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

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

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

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

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

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

Операторы¶Operators

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

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

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

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

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

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

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

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

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

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

PurePath.parts¶

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

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

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

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

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

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

PurePath.parser¶

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

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

PurePath.drive¶

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

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

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

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

PurePath.root¶

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

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

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

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

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

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

Примечание

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

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

PurePath.anchor¶

Объединение диска и корневого каталога:

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

PurePath.parents¶

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

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

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

PurePath.parent¶

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

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

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

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

Примечание

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

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

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

PurePath.name¶

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

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

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

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

PurePath.suffix¶

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

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

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

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

PurePath.suffixes¶

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

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

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

PurePath.stem¶

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

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

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

PurePath.as_posix()¶

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

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

PurePath.is_absolute()¶

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

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

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

PurePath.is_relative_to(other)¶

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

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

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

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

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

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

PurePath.is_reserved()¶

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

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

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

PurePath.joinpath(*pathsegments)¶

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

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

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

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

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

См. также

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

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

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

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

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

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

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

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

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

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

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

PurePath.relative_to(other, walk_up=False)¶

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

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

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

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

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

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

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

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

PurePath.with_name(name)¶

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

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

PurePath.with_stem(stem)¶

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

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

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

PurePath.with_suffix(suffix)¶

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

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

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

PurePath.with_segments(*pathsegments)¶

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

from pathlib import PurePosixPath

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

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

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

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

Разбор и генерация URI¶Parsing and generating URIs

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

classmethod Path.from_uri(uri)¶

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

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

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

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

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

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

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

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

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

Path.as_uri()¶

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

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

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

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

classmethod Path.home()¶

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

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

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

Path.expanduser()¶

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

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

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

classmethod Path.cwd()¶

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

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

Path.absolute()¶

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

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

Path.resolve(strict=False)¶

Make the path absolute, resolving any symlinks. A new path object is returned:

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

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

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

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

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

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

Path.readlink()¶

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

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

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

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

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

Path.stat(*, follow_symlinks=True)¶

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

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

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

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

Path.lstat()¶

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

Path.exists(*, follow_symlinks=True)¶

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

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

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

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

Path.is_file(*, follow_symlinks=True)¶

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

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

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

Path.is_dir(*, follow_symlinks=True)¶

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

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

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

Path.is_symlink()¶

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

Path.is_junction()¶

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

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

Path.is_mount()¶

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

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

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

Path.is_socket()¶

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

Path.is_fifo()¶

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

Path.is_block_device()¶

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

Path.is_char_device()¶

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

Path.samefile(other_path)¶

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

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

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

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

Path.info¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Path.read_bytes()¶

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

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

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

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

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

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

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

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

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

Path.write_bytes(data)¶

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

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

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

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

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

Path.iterdir()¶

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

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

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

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

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

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

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

Примечание

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

См. также

Синтаксис шаблонов документации.

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

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

Примечание

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

См. также

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Примечание

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

Примечание

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

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

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

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

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

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

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

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

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

См. также

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

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

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

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

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

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

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

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

Path.symlink_to(target, target_is_directory=False)¶

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

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

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

Примечание

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

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

Path.hardlink_to(target)¶

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

Примечание

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Path.rename(target)¶

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

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

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

Реализован через os.rename() и даёт те же гарантии.

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

Path.replace(target)¶

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

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

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

Path.move(target)¶

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

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

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

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

Path.move_into(target_dir)¶

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

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

Path.unlink(missing_ok=False)¶

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

Если missing_ok равно false (по умолчанию), FileNotFoundError вызывается, если путь не существует.

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

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

Path.rmdir()¶

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

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

Path.owner(*, follow_symlinks=True)¶

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

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

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

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

Path.group(*, follow_symlinks=True)¶

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

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

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

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

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

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

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

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

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

Path.lchmod(mode)¶

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

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

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

Сноски