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, выпуск 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
''

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

Изменено в версии 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: Этот метод устарел; для обнаружения зарезервированных путей в 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')

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

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

Изменено в версии 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() делает его строго нечистым.

Подстановка и разрешение путей

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, если путь указывает на существующий файл или каталог. Если путь некорректен, недоступен или отсутствует, возвращается 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, если путь указывает на точку соединения, и 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. Используйте Path.stat(), чтобы различить эти случаи.

Path.is_fifo()

Возвращает True, если путь указывает на FIFO. Если путь некорректен, недоступен или отсутствует либо указывает на объект, не являющийся FIFO, возвращается False. Используйте 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(), а не методы этого атрибута. Сбросить кэш нельзя; вместо этого можно создать новый объект пути с пустым кэшем info с помощью p = Path(p).

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

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

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, чтобы всегда следовать по символическим ссылкам.

Примечание

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

По умолчанию ошибки от 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.copy(target, *, follow_symlinks=True, preserve_metadata=False)

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

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

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

Примечание

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

Добавлено в версии 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()

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

Разрешения и владение

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.

Сноски