pathlib — объектно-ориентированные пути файловой системы

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

Исходный код: Lib/pathlib.py

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

Если вы никогда раньше не использовали этот модуль или не уверены, какой класс подходит для вашей задачи, скорее всего, вам нужен Path. Он создаёт экземпляр конкретного пути для платформы, на которой выполняется код.

Чистые пути полезны в некоторых особых случаях; например:

Если вы хотите работать с путями Windows на компьютере с Unix (или наоборот). При работе в Unix нельзя создать экземпляр WindowsPath, но можно создать экземпляр PureWindowsPath.
Если вы хотите убедиться, что код работает только с путями, не обращаясь при этом к ОС. В этом случае может быть полезно создать экземпляр одного из чистых классов, поскольку в них просто нет операций, обращающихся к ОС.

См. также

PEP 428: Модуль pathlib — объектно-ориентированные пути файловой системы.

См. также

Для низкоуровневой обработки путей в строках можно также использовать модуль os.path.

Основы использования

Импорт основного класса:

>>> from pathlib import Path

Получение списка подкаталогов:

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

Получение списка исходных файлов Python в этом дереве каталогов:

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

Перемещение по дереву каталогов:

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

Получение свойств пути:

>>> q.exists()
True
>>> q.is_dir()
False

Открытие файла:

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

Чистые пути

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

class pathlib.PurePath(*pathsegments)

Общий класс, представляющий вариант путей системы (его экземпляр создаёт либо PurePosixPath, либо PureWindowsPath):

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

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

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

Если pathsegments пуст, предполагается текущий каталог:

>>> PurePath()
PurePosixPath('.')

Если сегмент является абсолютным путём, все предыдущие сегменты игнорируются (как в os.path.join()):

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

В Windows диск не сбрасывается при встрече сегмента относительного пути с корнем (например, r'\foo'):

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

Лишние косые черты и одиночные точки сворачиваются, но двойные точки ('..') и начальные двойные косые черты ('//') сохраняются, поскольку их устранение изменило бы смысл пути по разным причинам (например, из-за символических ссылок или UNC-путей):

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('//foo/bar')
PurePosixPath('//foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

(наивный подход сделал бы PurePosixPath('foo/../bar') эквивалентным PurePosixPath('bar'), что неверно, если foo является символической ссылкой на другой каталог)

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

Изменено в версии 3.6: Добавлена поддержка интерфейса os.PathLike.

class pathlib.PurePosixPath(*pathsegments)

Этот вариант пути является подклассом PurePath и представляет пути файловой системы, отличные от путей Windows:

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

pathsegments задаётся аналогично PurePath.

class pathlib.PureWindowsPath(*pathsegments)

Этот вариант пути является подклассом PurePath и представляет пути файловой системы Windows, включая UNC-пути:

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments задаётся аналогично PurePath.

Независимо от используемой системы, можно создать экземпляры всех этих классов, поскольку они не выполняют никаких системных вызовов.

Общие свойства

Пути неизменяемы и хешируемы. Пути одного варианта можно сравнивать и упорядочивать. При этом учитывается семантика приведения регистра, характерная для данного варианта:

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

Примечание

Вызов bytes рекомендуется только в Unix. В Windows каноническим представлением путей файловой системы является форма Unicode.

Доступ к отдельным компонентам

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

PurePath.parts

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

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

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

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

Методы и свойства

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

PurePath.drive

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

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

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

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

PurePath.root

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

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

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

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

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

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

Примечание

Такое поведение соответствует Основным спецификациям The Open Group, выпуск 6, пункту 4.11 Разрешение имён путей:

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

PurePath.anchor

Объединение диска и корня:

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

PurePath.parents

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

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

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

PurePath.parent

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

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

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

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

Примечание

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

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

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

PurePath.name

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

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

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

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

PurePath.suffix

Расширение файла в последнем компоненте пути, если оно есть:

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

PurePath.suffixes

Список расширений файлов пути:

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

PurePath.stem

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

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

PurePath.as_posix()

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

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

PurePath.as_uri()

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

>>> p = PurePosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = PureWindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

PurePath.is_absolute()

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

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

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

PurePath.is_relative_to(*other)

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

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

Если передано несколько аргументов, они объединяются.

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

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

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

PurePath.is_reserved()

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

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

Вызовы файловой системы для зарезервированных путей могут завершаться непонятными ошибками или приводить к непредусмотренным последствиям.

PurePath.joinpath(*other)

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

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

PurePath.match(pattern)

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

Если pattern является относительным, путь может быть как относительным, так и абсолютным, а сопоставление выполняется справа налево:

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

Если pattern является абсолютным, путь также должен быть абсолютным, и ему должен соответствовать весь путь:

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

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

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

PurePath.relative_to(*other)

Вычисляет представление этого пути относительно пути, заданного в 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 694, in relative_to
    .format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other absolute.

Если передано несколько аргументов, они объединяются.

ПРИМЕЧАНИЕ: Эта функция относится к PurePath и работает со строками. Она не проверяет файловую структуру и не обращается к ней.

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

Конкретные пути

Конкретные пути — это подклассы классов чистых путей. Помимо операций, предоставляемых последними, они также предоставляют методы для выполнения системных вызовов над объектами путей. Создать экземпляр конкретного пути можно тремя способами:

class pathlib.Path(*pathsegments)

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

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments задаются так же, как и для PurePath.

class pathlib.PosixPath(*pathsegments)

Подкласс Path и PurePosixPath, этот класс представляет конкретные пути файловой системы, не относящиеся к Windows:

>>> PosixPath('/etc')
PosixPath('/etc')

pathsegments задаются так же, как и для PurePath.

class pathlib.WindowsPath(*pathsegments)

Подкласс Path и PureWindowsPath, этот класс представляет конкретные пути файловой системы Windows:

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

pathsegments задаются так же, как и для PurePath.

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

>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

Методы

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

Изменено в версии 3.8: exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() теперь возвращают False вместо вызова исключения для путей, содержащих символы, которые невозможно представить на уровне ОС.

classmethod Path.cwd()

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

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

classmethod Path.home()

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

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

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

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

Определяет, указывает ли путь на существующий файл или каталог:

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

Примечание

Если путь указывает на символическую ссылку, exists() возвращает результат проверки того, указывает ли символическая ссылка на существующий файл или каталог.

Path.expanduser()

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

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

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

Path.glob(pattern)

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

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

Шаблоны совпадают с шаблонами fnmatch, с добавлением «**», означающего «этот каталог и все его подкаталоги рекурсивно». Иными словами, он включает рекурсивный поиск по шаблону:

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

Примечание

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

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

Изменено в версии 3.11: Возвращает только каталоги, если pattern заканчивается разделителем компонентов пути (sep или altsep).

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

Path.is_dir()

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

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

Path.is_file()

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

Path.is_mount(): Возвращает True, если путь является точкой монтирования: точкой в файловой системе, где смонтирована другая файловая система. В POSIX функция проверяет, находится ли родительский каталог path, path/.., на устройстве, отличном от устройства path, либо указывают ли path/.. и path на один и тот же индексный дескриптор на одном устройстве. Эта проверка должна обнаруживать точки монтирования во всех вариантах Unix и POSIX. В Windows не реализовано.

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

Path.is_symlink()

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

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

Path.is_socket()

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

Path.is_fifo()

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

Path.is_block_device()

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

Path.is_char_device()

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

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

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

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

Path.lstat(): Подобно Path.stat(), но если путь указывает на символическую ссылку, возвращает информацию о самой ссылке, а не о ее целевом объекте.

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

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.read_text(encoding=None, errors=None)

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

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

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

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

Path.readlink()

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

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

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

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

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

Path.absolute()

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

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

Path.resolve(strict=False)

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

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

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

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

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

Добавлено в версии 3.6: Аргумент strict (до версии 3.6 поведение было строгим).

Path.rglob(pattern)

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

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

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

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

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.symlink_to(target, target_is_directory=False)

Создает для этого пути символическую ссылку, указывающую на target.

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

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

Примечание

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

Path.hardlink_to(target): Создает для этого пути жесткую ссылку на тот же файл, что и target.

Примечание

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

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

Path.link_to(target): Создает для target жесткую ссылку на этот путь.

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

Эта функция не создает для этого пути жесткую ссылку на target, несмотря на то, что подразумевают имена функции и аргументов. Порядок аргументов (цель, ссылка) обратен порядку аргументов в Path.symlink_to() и Path.hardlink_to(), но совпадает с порядком аргументов в os.link().

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

Устарело начиная с версии 3.10: Этот метод устарел; вместо него следует использовать Path.hardlink_to(), поскольку порядок аргументов Path.link_to() не совпадает с порядком аргументов Path.symlink_to().

Path.touch(mode=0o666, exist_ok=True): Создает файл по указанному пути. Если задан параметр mode, он объединяется со значением umask процесса для определения режима доступа к файлу и флагов доступа. Если файл уже существует, функция выполняется успешно, когда exist_ok имеет значение true (время изменения файла при этом обновляется до текущего); в противном случае вызывается исключение FileExistsError.

Path.unlink(missing_ok=False)

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

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

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

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

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

Соответствие инструментам модуля os

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

Примечание

Не все приведённые ниже пары функций/методов эквивалентны. Некоторые из них, несмотря на частичное совпадение вариантов использования, имеют разную семантику. К ним относятся os.path.abspath() и Path.absolute(), os.path.relpath() и PurePath.relative_to().

`os` и `os.path`	`pathlib`
`os.path.abspath()`	`Path.absolute()` [1]
`os.path.realpath()`	`Path.resolve()`
`os.chmod()`	`Path.chmod()`
`os.mkdir()`	`Path.mkdir()`
`os.makedirs()`	`Path.mkdir()`
`os.rename()`	`Path.rename()`
`os.replace()`	`Path.replace()`
`os.rmdir()`	`Path.rmdir()`
`os.remove()`, `os.unlink()`	`Path.unlink()`
`os.getcwd()`	`Path.cwd()`
`os.path.exists()`	`Path.exists()`
`os.path.expanduser()`	`Path.expanduser()` и `Path.home()`
`os.listdir()`	`Path.iterdir()`
`os.path.isdir()`	`Path.is_dir()`
`os.path.isfile()`	`Path.is_file()`
`os.path.islink()`	`Path.is_symlink()`
`os.link()`	`Path.hardlink_to()`
`os.symlink()`	`Path.symlink_to()`
`os.readlink()`	`Path.readlink()`
`os.path.relpath()`	`PurePath.relative_to()` [2]
`os.stat()`	`Path.stat()`, `Path.owner()`, `Path.group()`
`os.path.isabs()`	`PurePath.is_absolute()`
`os.path.join()`	`PurePath.joinpath()`
`os.path.basename()`	`PurePath.name`
`os.path.dirname()`	`PurePath.parent`
`os.path.samefile()`	`Path.samefile()`
`os.path.splitext()`	`PurePath.stem` и `PurePath.suffix`

pathlib — объектно-ориентированные пути файловой системы

Основы использования

Чистые пути

Общие свойства

Операторы

Доступ к отдельным компонентам

Методы и свойства

Конкретные пути

Методы

Соответствие инструментам модуля os

Сноски