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

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: Этот метод устарел; используйте 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')

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» и представлены в них, соответствуя 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 указывают на один и тот же узел i на одном и том же устройстве — это должно определять точки монтирования для всех вариантов Unix и POSIX. В Windows точка монтирования рассматривается как корень буквы диска (например, c:\), общая папка UNC (например, \\server\share) или каталог смонтированной файловой системы.

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

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

Path.is_socket()

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

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

Path.is_fifo()

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

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

Path.is_block_device()

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

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

Path.is_char_device()

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

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

Path.samefile(other_path)

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

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

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

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

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

Ищет файлы, соответствующие заданному относительному шаблону рекурсивно. Это аналогично вызову Path.glob() с добавленным «**/» перед шаблоном.

См. также

Язык шаблонов и 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, но исключая «.’ и «..’), метод возвращает тройку (dirpath, dirnames, filenames).

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

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

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

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

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

Примечание

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

Примечание

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

Примечание

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

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

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

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

# Delete everything reachable from the directory "top".
# CAUTION:  This is dangerous! For example, if top == Path('/'),
# it could delete all of your files.
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()

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

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

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

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

См. также

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

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

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

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

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

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

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

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

Path.symlink_to(target, target_is_directory=False)

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

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

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

Примечание

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

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

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

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

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

Примечания