> **Источник:** https://python-all.ru/3.14/library/pathlib.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

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

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

**Исходный код:** [Lib/pathlib/](https://python-all.ru/src/3.14/Lib/pathlib)

---

Этот модуль предоставляет классы, представляющие пути файловой системы с семантикой, подходящей для разных операционных систем. Классы путей делятся на [чистые пути](https://python-all.ru/3.14/library/pathlib.html#pure-paths), которые выполняют только вычислительные операции без ввода-вывода, и [конкретные пути](https://python-all.ru/3.14/library/pathlib.html#concrete-paths), которые наследуют чистые пути, но также предоставляют операции ввода-вывода.

![Диаграмма наследования, показывающая классы, доступные в pathlib. Самый базовый класс – PurePath, у которого есть три непосредственных подкласса: PurePosixPath, PureWindowsPath и Path. Кроме этих четырёх классов, есть два класса, использующих множественное наследование: PosixPath наследует от PurePosixPath и Path, а WindowsPath наследует от PureWindowsPath и Path.](https://python-all.ru/3.14/_images/pathlib-inheritance.png)

Если вы никогда не пользовались этим модулем раньше или просто не уверены, какой класс подходит для вашей задачи, скорее всего, вам нужен [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path). Он создаёт экземпляр [конкретного пути](https://python-all.ru/3.14/library/pathlib.html#concrete-paths) для платформы, на которой выполняется код.

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

1. Если требуется манипулировать путями Windows на машине Unix (или наоборот). При работе на Unix нельзя создать экземпляр [`WindowsPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.WindowsPath), но можно создать [`PureWindowsPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PureWindowsPath).
2. Если нужно, чтобы код только манипулировал путями без фактического обращения к ОС. В таком случае может быть полезно создать экземпляр одного из чистых классов, поскольку они просто не имеют операций доступа к ОС.

> **См. также**
>
> [**PEP 428**](https://python-all.ru/3.14/library/pathlib.html): модуль pathlib – объектно-ориентированные пути файловой системы.

> **См. также**
>
> Для низкоуровневых манипуляций с путями в виде строк можно также использовать модуль [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path).

## Основное использование

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

```python
>>> from pathlib import Path
```

Список подкаталогов:

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

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

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

Навигация по дереву каталогов:

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

Запрос свойств пути:

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

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

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

## Исключения

#### `exception pathlib.UnsupportedOperation`

Исключение, наследующее [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError), которое возбуждается при вызове неподдерживаемой операции над объектом пути.

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

## Чистые пути

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

#### `class pathlib.PurePath(*pathsegments)`

Общий класс, представляющий разновидность пути системы (при создании экземпляра создаётся либо [`PurePosixPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePosixPath), либо [`PureWindowsPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PureWindowsPath)):

```python
>>> PurePath('setup.py')      # Запуск на Unix-машине
PurePosixPath('setup.py')
```

Каждый элемент *pathsegments* может быть либо строкой, представляющей сегмент пути, либо объектом, реализующим интерфейс [`os.PathLike`](https://python-all.ru/3.14/library/os.html#os.PathLike), где метод [`__fspath__()`](https://python-all.ru/3.14/library/os.html#os.PathLike.__fspath__) возвращает строку, например, другой объект пути:

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

Когда *pathsegments* пуст, подразумевается текущий каталог:

```python
>>> PurePath()
PurePosixPath('.')
```

Если сегмент является абсолютным путём, все предыдущие сегменты игнорируются (как [`os.path.join()`](https://python-all.ru/3.14/library/os.path.html#os.path.join)):

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

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

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

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

```python
>>> 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`](https://python-all.ru/3.14/library/os.html#os.PathLike), что позволяет использовать их везде, где этот интерфейс принимается.

Изменено в версии 3.6: Добавлена поддержка интерфейса [`os.PathLike`](https://python-all.ru/3.14/library/os.html#os.PathLike).

#### `class pathlib.PurePosixPath(*pathsegments)`

Подкласс [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath), эта разновидность путей представляет пути файловой системы, отличные от Windows:

```python
>>> PurePosixPath('/etc/hosts')
PurePosixPath('/etc/hosts')
```

Параметр *pathsegments* задаётся так же, как [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath).

#### `class pathlib.PureWindowsPath(*pathsegments)`

Подкласс [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath), эта разновидность путей представляет пути файловой системы Windows, включая [UNC-пути](https://python-all.ru/3.14/library/pathlib.html):

```python
>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')
```

Параметр *pathsegments* задаётся так же, как [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath).

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

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

Пути неизменяемы и [хэшируемые](https://python-all.ru/3.14/glossary.html#term-hashable). Пути одной разновидности сравнимы и упорядочиваемы. Эти свойства учитывают семантику приведения регистра данной разновидности:

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

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

```python
>>> 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()`](https://python-all.ru/3.14/library/os.path.html#os.path.join). Если аргумент является абсолютным путём, предыдущий путь игнорируется. В Windows диск не сбрасывается, если аргумент является относительным путём с корнем (например, `r'\foo'`):

```python
>>> 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`](https://python-all.ru/3.14/library/os.html#os.PathLike):

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

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

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

Аналогично, вызов [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) для пути возвращает сырой путь файловой системы в виде объекта bytes, закодированный с помощью [`os.fsencode()`](https://python-all.ru/3.14/library/os.html#os.fsencode):

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

> **Примечание**
>
> Вызов [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) рекомендуется только в Unix. В Windows форма Unicode является каноническим представлением путей файловой системы.

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

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

#### `PurePath.parts`

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

```python
>>> 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`](https://python-all.ru/3.14/library/os.path.html#module-os.path), используемая для низкоуровневого разбора и объединения путей: либо `posixpath`, либо `ntpath`.

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

#### `PurePath.drive`

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

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

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

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

#### `PurePath.root`

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

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

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

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

Если путь начинается с более чем двух последовательных слешей, [`PurePosixPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePosixPath) схлопывает их:

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

> **Примечание**
>
> Это поведение соответствует *The Open Group Base Specifications Issue 6*, пункту [4.11 Pathname Resolution](https://python-all.ru/3.14/library/pathlib.html):
>
> *«Имя пути, начинающееся с двух последовательных слешей, может интерпретироваться способом, определяемым реализацией, хотя более двух начальных слешей должны рассматриваться как один слеш.»*

#### `PurePath.anchor`

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

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

#### `PurePath.parents`

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

```python
>>> 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 теперь поддерживает [срезы](https://python-all.ru/3.14/glossary.html#term-slice) и отрицательные значения индексов.

#### `PurePath.parent`

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

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

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

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

> **Примечание**
>
> Это чисто лексическая операция, поэтому поведение следующее:
>
> ```python
> >>> p = PurePosixPath('foo/..')
> >>> p.parent
> PurePosixPath('foo')
> ```
>
> Если нужно подняться вверх по произвольному пути файловой системы, рекомендуется сначала вызвать [`Path.resolve()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.resolve), чтобы разрешить символические ссылки и убрать компоненты `".."`.

#### `PurePath.name`

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

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

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

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

#### `PurePath.suffix`

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

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

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

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

#### `PurePath.suffixes`

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

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

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

#### `PurePath.stem`

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

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

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

#### `PurePath.as_posix()`

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

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

#### `PurePath.is_absolute()`

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

```python
>>> 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*.

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

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

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

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

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

#### `PurePath.is_reserved()`

С [`PureWindowsPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PureWindowsPath) возвращает `True`, если путь считается зарезервированным в Windows, иначе `False`. С [`PurePosixPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePosixPath) всегда возвращается `False`.

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

Устарело с версии 3.13, будет удалено в версии 3.15: Этот метод устарел; используйте [`os.path.isreserved()`](https://python-all.ru/3.14/library/os.path.html#os.path.isreserved) для обнаружения зарезервированных путей в Windows.

#### `PurePath.joinpath(*pathsegments)`

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

```python
>>> 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`. Например:

```python
>>> 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
```

> **См. также**
>
> [Синтаксис шаблонов](https://python-all.ru/3.14/library/pathlib.html#pathlib-pattern-language) документации.

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

```python
>>> 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()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.full_match), но пустые шаблоны не допускаются (вызывается [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError)), рекурсивный шаблон «`**`» не поддерживается (он работает как нерекурсивный «`*`»), и если задан относительный шаблон, сравнение выполняется справа:

```python
>>> 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* теперь принимает [объект, подобный пути](https://python-all.ru/3.14/glossary.html#term-path-like-object).

Изменено в версии 3.12: Добавлен параметр *case\_sensitive*.

#### `PurePath.relative_to(other, walk_up=False)`

Вычисляет версию этого пути, относительную пути, представленному *other*. Если это невозможно, вызывается [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError):

```python
>>> 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`](https://python-all.ru/3.14/library/exceptions.html#ValueError):

```python
>>> 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`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath) и работает со строками. Она не проверяет и не обращается к нижележащей файловой структуре. Это может повлиять на опцию *walk\_up*, так как предполагается, что в пути нет символических ссылок; при необходимости сначала вызовите [`resolve()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.resolve) для разрешения символьных ссылок.

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

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

#### `PurePath.with_name(name)`

Возвращает новый путь с изменённым [`name`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.name). Если у исходного пути нет имени, вызывается ValueError:

```python
>>> 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`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.stem). Если у исходного пути нет имени, вызывается ValueError:

```python
>>> 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`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.suffix). Если у исходного пути нет суффикса, вместо него добавляется новый *suffix*. Если *suffix* – пустая строка, исходный суффикс удаляется:

```python
>>> 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`](https://python-all.ru/3.14/library/exceptions.html#ValueError).

#### `PurePath.with_segments(*pathsegments)`

Создаёт новый объект пути того же типа, объединяя указанные *pathsegments*. Этот метод вызывается при создании производного пути, например из [`parent`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.parent) и [`relative_to()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.relative_to). Подклассы могут переопределять этот метод для передачи информации производным путям, например:

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

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

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

#### `class pathlib.Path(*pathsegments)`

Подкласс [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath); этот класс представляет конкретные пути, соответствующие flavour данной файловой системы (при создании экземпляра создаётся либо [`PosixPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PosixPath), либо [`WindowsPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.WindowsPath)):

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

Параметр *pathsegments* задаётся так же, как [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath).

#### `class pathlib.PosixPath(*pathsegments)`

Подкласс [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path) и [`PurePosixPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePosixPath); этот класс представляет конкретные пути для файловых систем, отличных от Windows:

```python
>>> PosixPath('/etc/hosts')
PosixPath('/etc/hosts')
```

Параметр *pathsegments* задаётся так же, как [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath).

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation) в Windows. В предыдущих версиях вместо него возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

#### `class pathlib.WindowsPath(*pathsegments)`

Подкласс [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path) и [`PureWindowsPath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PureWindowsPath); этот класс представляет конкретные пути файловой системы Windows:

```python
>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')
```

Параметр *pathsegments* задаётся так же, как [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath).

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation) на платформах, отличных от Windows. В предыдущих версиях вместо него возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

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

```python
>>> 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__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system
```

Некоторые методы конкретных путей могут возбуждать [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError), если системный вызов завершается ошибкой (например, потому что путь не существует).

### Разбор и генерация URI

Объекты конкретных путей можно создавать из URI вида «file» и представлять в виде URI, соответствующих [**RFC 8089**](https://python-all.ru/3.14/library/pathlib.html).

> **Примечание**
>
> URI файлов не переносимы между машинами с разными [кодировками файловой системы](https://python-all.ru/3.14/library/os.html#filesystem-encoding).

#### `classmethod Path.from_uri(uri)`

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

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

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

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

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

```python
>>> 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`](https://python-all.ru/3.14/library/exceptions.html#ValueError) возбуждается, если URI не начинается с `file:`, или извлечённый путь не является абсолютным.

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

Изменено в версии 3.14: Authority URL отбрасывается, если оно совпадает с локальным именем хоста. В противном случае, если authority не пусто и не равно `localhost`, то в Windows возвращается UNC-путь (как и раньше), а на других платформах возбуждается [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError).

#### `Path.as_uri()`

Представляет путь в виде URI «file». [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError) возбуждается, если путь не является абсолютным.

```pycon
>>> 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`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath), а не из [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path) возможен, но не рекомендуется. Использование [`os.fsencode()`](https://python-all.ru/3.14/library/os.html#os.fsencode) в этом методе делает его строго нечистым.

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

#### `classmethod Path.home()`

Возвращает новый объект пути, представляющий домашний каталог пользователя (как возвращается [`os.path.expanduser()`](https://python-all.ru/3.14/library/os.path.html#os.path.expanduser) с конструкцией `~`). Если домашний каталог не может быть определён, возбуждается [`RuntimeError`](https://python-all.ru/3.14/library/exceptions.html#RuntimeError).

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

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

#### `Path.expanduser()`

Возвращает новый путь с развёрнутыми конструкциями `~` и `~user`, как возвращается [`os.path.expanduser()`](https://python-all.ru/3.14/library/os.path.html#os.path.expanduser). Если домашний каталог не может быть определён, возбуждается [`RuntimeError`](https://python-all.ru/3.14/library/exceptions.html#RuntimeError).

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

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

#### `classmethod Path.cwd()`

Возвращает новый объект пути, представляющий текущий каталог (как возвращается [`os.getcwd()`](https://python-all.ru/3.14/library/os.html#os.getcwd)):

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

#### `Path.absolute()`

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

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

#### `Path.resolve(strict=False)`

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

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

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

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

Если путь не существует или обнаружен зацикленный симлинк, а *strict* равен `True`, возбуждается [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError). Если *strict* равен `False`, путь разрешается насколько возможно, а остаток добавляется без проверки его существования.

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

Изменено в версии 3.13: Зацикленные симлинки обрабатываются как другие ошибки: в строгом режиме возбуждается [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError), а в нестрогом – исключение не возбуждается. В предыдущих версиях [`RuntimeError`](https://python-all.ru/3.14/library/exceptions.html#RuntimeError) возбуждалось независимо от значения *strict*.

#### `Path.readlink()`

Возвращает путь, на который указывает симлинк (как возвращается [`os.readlink()`](https://python-all.ru/3.14/library/os.html#os.readlink)):

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

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

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation), если [`os.readlink()`](https://python-all.ru/3.14/library/os.html#os.readlink) недоступен. В предыдущих версиях возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

### Запрос типа файла и статуса

Изменено в версии 3.8: Методы [`exists()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.exists), [`is_dir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_dir), [`is_file()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_file), [`is_mount()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_mount), [`is_symlink()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_symlink), [`is_block_device()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_block_device), [`is_char_device()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_char_device), [`is_fifo()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_fifo), [`is_socket()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_socket) теперь возвращают `False` вместо возбуждения исключения для путей, содержащих символы, непредставимые на уровне ОС.

Изменено в версии 3.14: Методы, перечисленные выше, теперь возвращают `False` вместо возбуждения любого исключения [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError) от операционной системы. В предыдущих версиях некоторые виды исключений `OSError` возбуждались, а другие подавлялись. Новое поведение согласовано с [`os.path.exists()`](https://python-all.ru/3.14/library/os.path.html#os.path.exists), [`os.path.isdir()`](https://python-all.ru/3.14/library/os.path.html#os.path.isdir) и т. д. Используйте [`stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat) для получения статуса файла без подавления исключений.

#### `Path.stat(*, follow_symlinks=True)`

Возвращает объект [`os.stat_result`](https://python-all.ru/3.14/library/os.html#os.stat_result), содержащий информацию об этом пути, как [`os.stat()`](https://python-all.ru/3.14/library/os.html#os.stat). Результат запрашивается при каждом вызове этого метода.

Этот метод обычно следует по симлинкам; чтобы выполнить stat для самого симлинка, добавьте аргумент `follow_symlinks=False`, или используйте [`lstat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.lstat).

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

Изменено в версии 3.10: Добавлен параметр *follow\_symlinks*.

#### `Path.lstat()`

Как [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat), но если путь указывает на симлинк, возвращает информацию о симлинке, а не о его цели.

#### `Path.exists(*, follow_symlinks=True)`

Возвращает `True`, если путь указывает на существующий файл или каталог. `False` возвращается, если путь недействителен, недоступен или отсутствует. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat) для различения этих случаев.

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

```python
>>> 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()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat) для различения этих случаев.

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

Изменено в версии 3.13: Добавлен параметр *follow\_symlinks*.

#### `Path.is_dir(*, follow_symlinks=True)`

Возвращает `True`, если путь указывает на каталог. `False` возвращается, если путь недействителен, недоступен или отсутствует, или если он указывает на что-то, отличное от каталога. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat) для различения этих случаев.

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

Изменено в версии 3.13: Добавлен параметр *follow\_symlinks*.

#### `Path.is_symlink()`

Возвращает `True`, если путь указывает на символическую ссылку, даже если эта ссылка недействительна. `False` возвращается, если путь недопустим, недоступен или отсутствует, или указывает на что-то, отличное от символической ссылки. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat), чтобы различать эти случаи.

#### `Path.is_junction()`

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

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

#### `Path.is_mount()`

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

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

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

#### `Path.is_socket()`

Возвращает `True`, если путь указывает на сокет Unix. `False` будет возвращен, если путь недопустим, недоступен или отсутствует, или указывает на что-то отличное от сокета Unix. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat), чтобы различать эти случаи.

#### `Path.is_fifo()`

Возвращает `True`, если путь указывает на FIFO. `False` будет возвращен, если путь недопустим, недоступен или отсутствует, или указывает на что-то отличное от FIFO. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat), чтобы различать эти случаи.

#### `Path.is_block_device()`

Возвращает `True`, если путь указывает на блочное устройство. `False` будет возвращен, если путь недопустим, недоступен или отсутствует, или указывает на что-то отличное от блочного устройства. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat), чтобы различать эти случаи.

#### `Path.is_char_device()`

Возвращает `True`, если путь указывает на символьное устройство. `False` будет возвращен, если путь недопустим, недоступен или отсутствует, или указывает на что-то отличное от символьного устройства. Используйте [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat), чтобы различать эти случаи.

#### `Path.samefile(other_path)`

Возвращает, указывает ли этот путь на тот же файл, что и *other\_path*, который может быть как объектом Path, так и строкой. Семантика аналогична [`os.path.samefile()`](https://python-all.ru/3.14/library/os.path.html#os.path.samefile) и [`os.path.samestat()`](https://python-all.ru/3.14/library/os.path.html#os.path.samestat).

Исключение [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError) может быть возбуждено, если какой-либо из файлов недоступен по какой-либо причине.

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

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

#### `Path.info`

Объект [`PathInfo`](https://python-all.ru/3.14/library/pathlib.html#pathlib.types.PathInfo), поддерживающий запрос информации о типе файла. Объект предоставляет методы, которые кэшируют свои результаты, что может помочь уменьшить количество системных вызовов, необходимых при переключении по типу файла. Например:

```python
>>> 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()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.iterdir), то этот атрибут инициализируется некоторой информацией о типе файла, полученной при сканировании родительского каталога. Простое обращение к `Path.info` не выполняет никаких запросов к файловой системе.

Для получения актуальной информации лучше вызывать [`Path.is_dir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_dir), [`is_file()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_file) и [`is_symlink()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_symlink), а не методы этого атрибута. Сбросить кэш невозможно; вместо этого можно создать новый объект пути с пустым кэшем информации с помощью `p = Path(p)`.

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

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

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

Открывает файл, на который указывает путь, как это делает встроенная функция [`open()`](https://python-all.ru/3.14/library/functions.html#open) :

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

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

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

Файл открывается, а затем закрывается. Необязательные параметры имеют тот же смысл, что и в [`open()`](https://python-all.ru/3.14/library/functions.html#open).

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

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

#### `Path.read_bytes()`

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

```python
>>> 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* и закрывает файл:

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

Существующий файл с таким же именем перезаписывается. Необязательные параметры имеют тот же смысл, что и в [`open()`](https://python-all.ru/3.14/library/functions.html#open).

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

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

#### `Path.write_bytes(data)`

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

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

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

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

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

#### `Path.iterdir()`

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

```python
>>> 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`](https://python-all.ru/3.14/library/exceptions.html#OSError).

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

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

```python
>>> 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')]
```

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

> **См. также**
>
> [Синтаксис шаблонов](https://python-all.ru/3.14/library/pathlib.html#pathlib-pattern-language) документации.

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

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

> **Примечание**
>
> Все исключения [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError), возникающие при сканировании файловой системы, подавляются. Включая [`PermissionError`](https://python-all.ru/3.14/library/exceptions.html#PermissionError) при доступе к каталогам без права на чтение.

Возбуждает [событие аудита](https://python-all.ru/3.14/library/sys.html#auditing) `pathlib.Path.glob` с аргументами `self`, `pattern`.

Изменено в версии 3.12: Добавлен параметр *case\_sensitive*.

Изменено в версии 3.13: Добавлен параметр *recurse\_symlinks*.

Изменено в версии 3.13: Параметр *pattern* теперь принимает [объект, подобный пути](https://python-all.ru/3.14/glossary.html#term-path-like-object).

Изменено в версии 3.13: Любые исключения [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError), возникающие при сканировании файловой системы, подавляются. В предыдущих версиях такие исключения подавлялись во многих, но не во всех случаях.

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

Выполняет рекурсивный поиск по заданному относительному *pattern*. Это аналогично вызову [`Path.glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob) с добавлением «`**/`» перед *pattern*.

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

> **Примечание**
>
> Все исключения [`OSError`](https://python-all.ru/3.14/library/exceptions.html#OSError), возникающие при сканировании файловой системы, подавляются. Включая [`PermissionError`](https://python-all.ru/3.14/library/exceptions.html#PermissionError) при доступе к каталогам без права на чтение.

> **См. также**
>
> [Синтаксис шаблонов](https://python-all.ru/3.14/library/pathlib.html#pathlib-pattern-language) и документация [`Path.glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob).

Возбуждает [событие аудита](https://python-all.ru/3.14/library/sys.html#auditing) `pathlib.Path.rglob` с аргументами `self`, `pattern`.

Изменено в версии 3.12: Добавлен параметр *case\_sensitive*.

Изменено в версии 3.13: Добавлен параметр *recurse\_symlinks*.

Изменено в версии 3.13: Параметр *pattern* теперь принимает [объект, подобный пути](https://python-all.ru/3.14/glossary.html#term-path-like-object).

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

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

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

*dirpath* – это [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path) к текущему обходимому каталогу, *dirnames* – список строк с именами подкаталогов в *dirpath* (исключая `'.'` и `'..'`), а *filenames* – список строк с именами файлов (не каталогов) в *dirpath*. Чтобы получить полный путь (начинающийся с *self*) к файлу или каталогу в *dirpath*, используйте `dirpath / name`. Отсортированы ли списки, зависит от файловой системы.

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

Когда *top\_down* равен true, вызывающий код может изменить список *dirnames* на месте (например, с помощью [`del`](https://python-all.ru/3.14/reference/simple_stmts.html#del) или присваивания среза), и `Path.walk()` будет рекурсивно обходить только те подкаталоги, чьи имена остались в *dirnames*. Это можно использовать для обрезки поиска, наложения определённого порядка обхода или даже для информирования `Path.walk()` о каталогах, которые вызывающий код создаёт или переименовывает до того, как возобновит `Path.walk()` снова. Изменение *dirnames*, когда *top\_down* равен false, не влияет на поведение `Path.walk()`, поскольку каталоги в *dirnames* уже были сгенерированы к моменту, когда *dirnames* передаётся вызывающему коду.

По умолчанию ошибки [`os.scandir()`](https://python-all.ru/3.14/library/os.html#os.scandir) игнорируются. Если указан необязательный аргумент *on\_error*, это должен быть вызываемый объект; он будет вызван с одним аргументом – экземпляром [`OSError`](https://python-all.ru/3.14/library/exceptions.html#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()`](https://python-all.ru/3.14/library/os.html#os.walk), `Path.walk()` перечисляет символические ссылки на каталоги в *filenames*, если *follow\_symlinks* равно false.

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

```python
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()`](https://python-all.ru/3.14/library/shutil.html#shutil.rmtree). Обход дерева снизу вверх необходим, поскольку [`rmdir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rmdir) не позволяет удалить каталог, пока он не пуст:

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

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

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

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

Создаёт файл по указанному пути. Если задан *mode*, он комбинируется со значением `umask` процесса для определения режима файла и флагов доступа. Если файл уже существует, функция завершается успешно, когда *exist\_ok* равен true (время модификации обновляется до текущего), в противном случае возбуждается [`FileExistsError`](https://python-all.ru/3.14/library/exceptions.html#FileExistsError).

> **См. также**
>
> Методы [`open()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.open), [`write_text()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.write_text) и [`write_bytes()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.write_bytes) часто используются для создания файлов.

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

Создаёт новый каталог по указанному пути. Если задан *mode*, он комбинируется со значением `umask` процесса для определения режима файла и флагов доступа. Если путь уже существует, возбуждается [`FileExistsError`](https://python-all.ru/3.14/library/exceptions.html#FileExistsError).

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

Если *parents* равен false (по умолчанию), отсутствие родительского каталога вызывает [`FileNotFoundError`](https://python-all.ru/3.14/library/exceptions.html#FileNotFoundError).

Если *exist\_ok* равен false (по умолчанию), [`FileExistsError`](https://python-all.ru/3.14/library/exceptions.html#FileExistsError) возбуждается, если целевой каталог уже существует.

Если *exist\_ok* равен true, [`FileExistsError`](https://python-all.ru/3.14/library/exceptions.html#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* игнорируется.

```python
>>> 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()`](https://python-all.ru/3.14/library/os.html#os.symlink).

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation), если [`os.symlink()`](https://python-all.ru/3.14/library/os.html#os.symlink) недоступен. В предыдущих версиях возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

#### `Path.hardlink_to(target)`

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

> **Примечание**
>
> Порядок аргументов (ссылка, цель) обратный по сравнению с [`os.link()`](https://python-all.ru/3.14/library/os.html#os.link).

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

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation), если [`os.link()`](https://python-all.ru/3.14/library/os.html#os.link) недоступен. В предыдущих версиях возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

### Копирование, перемещение и удаление

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

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

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

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

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

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

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

Копирует этот файл или дерево каталогов в указанный *target\_dir*, который должен быть существующим каталогом. Остальные аргументы обрабатываются так же, как и в [`Path.copy()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.copy). Возвращает новый экземпляр `Path`, указывающий на копию.

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

#### `Path.rename(target)`

Переименовывает этот файл или каталог в указанный *target* и возвращает новый экземпляр `Path`, указывающий на *target*. В Unix, если *target* существует и является файлом, он будет молча заменён, если у пользователя есть разрешение. В Windows, если *target* существует, будет вызвано [`FileExistsError`](https://python-all.ru/3.14/library/exceptions.html#FileExistsError). *target* может быть строкой или другим объектом пути.

```python
>>> 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()`](https://python-all.ru/3.14/library/os.html#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`](https://python-all.ru/3.14/library/exceptions.html#OSError).

Если оба пути находятся в одной файловой системе, перемещение выполняется с помощью [`os.replace()`](https://python-all.ru/3.14/library/os.html#os.replace). В противном случае этот путь копируется (с сохранением метаданных и символических ссылок), а затем удаляется.

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

#### `Path.move_into(target_dir)`

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

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

#### `Path.unlink(missing_ok=False)`

Удаляет этот файл или символическую ссылку. Если путь указывает на каталог, используйте [`Path.rmdir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rmdir).

Если *missing\_ok* равно false (по умолчанию), [`FileNotFoundError`](https://python-all.ru/3.14/library/exceptions.html#FileNotFoundError) вызывается, если путь не существует.

Если *missing\_ok* равно true, исключения [`FileNotFoundError`](https://python-all.ru/3.14/library/exceptions.html#FileNotFoundError) будут игнорироваться (аналогично поведению команды POSIX `rm -f`).

Изменено в версии 3.8: Добавлен параметр *missing\_ok*.

#### `Path.rmdir()`

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

### Права доступа и владение

#### `Path.owner(*, follow_symlinks=True)`

Возвращает имя пользователя, владеющего файлом. [`KeyError`](https://python-all.ru/3.14/library/exceptions.html#KeyError) вызывается, если идентификатор пользователя (UID) файла не найден в системной базе данных.

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

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation), если модуль [`pwd`](https://python-all.ru/3.14/library/pwd.html#module-pwd) недоступен. В более ранних версиях возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

Изменено в версии 3.13: Добавлен параметр *follow\_symlinks*.

#### `Path.group(*, follow_symlinks=True)`

Возвращает имя группы, владеющей файлом. [`KeyError`](https://python-all.ru/3.14/library/exceptions.html#KeyError) возбуждается, если идентификатор группы (GID) файла не найден в системной базе данных.

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

Изменено в версии 3.13: Возбуждает [`UnsupportedOperation`](https://python-all.ru/3.14/library/pathlib.html#pathlib.UnsupportedOperation), если модуль [`grp`](https://python-all.ru/3.14/library/grp.html#module-grp) недоступен. В более ранних версиях возбуждалось [`NotImplementedError`](https://python-all.ru/3.14/library/exceptions.html#NotImplementedError).

Изменено в версии 3.13: Добавлен параметр *follow\_symlinks*.

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

Изменяет режим и права доступа к файлу, как [`os.chmod()`](https://python-all.ru/3.14/library/os.html#os.chmod).

Этот метод обычно переходит по символьным ссылкам. Некоторые варианты Unix поддерживают изменение прав доступа на самой символьной ссылке; на таких платформах можно добавить аргумент `follow_symlinks=False` или использовать [`lchmod()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.lchmod).

```python
>>> 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()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.chmod), но если путь указывает на символьную ссылку, то изменяется режим самой символьной ссылки, а не её цели.

## Язык шаблонов

В шаблонах для [`full_match()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.full_match), [`glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob) и [`rglob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rglob) поддерживаются следующие подстановочные знаки:

**`**` (весь сегмент)**

Соответствует любому количеству сегментов файлов или каталогов, включая ноль.

**`*` (весь сегмент)**

Соответствует одному сегменту файла или каталога.

**`*` (часть сегмента)**

Соответствует любому количеству символов, не являющихся разделителями, включая ноль.

**`?`**

Соответствует одному символу, не являющемуся разделителем.

**`[seq]`**

Соответствует одному символу из *seq*, где *seq* – это последовательность символов. Поддерживаются диапазонные выражения; например, `[a-z]` соответствует любой строчной букве ASCII. Можно комбинировать несколько диапазонов: `[a-zA-Z0-9_]` соответствует любой букве ASCII, цифре или знаку подчеркивания.

**`[!seq]`**

Соответствует одному символу, не входящему в *seq*, где правила для *seq* такие же, как выше.

Для точного совпадения заключите метасимволы в скобки. Например, `"[?]"` соответствует символу `"?"`.

Подстановочный знак «`**`» включает рекурсивный поиск по шаблону. Несколько примеров:

| Шаблон | Значение |
| --- | --- |
| “`**/*`” | Любой путь, содержащий хотя бы один сегмент. |
| “`**/*.py`” | Любой путь, последний сегмент которого заканчивается на «`.py`». |
| “`assets/**`” | Любой путь, начинающийся с «`assets/`». |
| “`assets/**/*`” | Любой путь, начинающийся с «`assets/`», за исключением самого «`assets/`». |

> **Примечание**
>
> Поиск по шаблону с использованием подстановочного знака «`**`» проходит по каждому каталогу в дереве. Большие деревья каталогов могут требовать много времени на поиск.

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

В [`Path.glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob) и [`rglob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rglob) к шаблону может быть добавлена конечная косая черта для соответствия только каталогам.

Изменено в версии 3.11: Поиск по шаблону, оканчивающемуся на разделитель компонентов пути ([`sep`](https://python-all.ru/3.14/library/os.html#os.sep) или [`altsep`](https://python-all.ru/3.14/library/os.html#os.altsep)), возвращает только каталоги.

## Сравнение с модулем [`glob`](https://python-all.ru/3.14/library/glob.html#module-glob)

Шаблоны, принимаемые [`Path.glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob) и [`Path.rglob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rglob), и генерируемые ими результаты немного отличаются от результатов модуля [`glob`](https://python-all.ru/3.14/library/glob.html#module-glob):

1. Файлы, начинающиеся с точки, не являются особыми в pathlib. Это аналогично передаче `include_hidden=True` в [`glob.glob()`](https://python-all.ru/3.14/library/glob.html#glob.glob).
2. Компоненты шаблона «`**`» в pathlib всегда рекурсивны. Это аналогично передаче `recursive=True` в [`glob.glob()`](https://python-all.ru/3.14/library/glob.html#glob.glob).
3. Компоненты шаблона «`**`» по умолчанию не переходят по символическим ссылкам в pathlib. Это поведение не имеет аналога в [`glob.glob()`](https://python-all.ru/3.14/library/glob.html#glob.glob), но можно передать `recurse_symlinks=True` в [`Path.glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob) для совместимого поведения.
4. Как и все объекты [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath) и [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path), значения, возвращаемые из [`Path.glob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.glob) и [`Path.rglob()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rglob), не содержат завершающих слешей.
5. Значения, возвращаемые методами pathlib `path.glob()` и `path.rglob()`, включают *путь* в качестве префикса, в отличие от результатов `glob.glob(root_dir=path)`.
6. Значения, возвращаемые методами pathlib `path.glob()` и `path.rglob()`, могут включать сам *путь*, например, при поиске по шаблону «`**`», тогда как результаты `glob.glob(root_dir=path)` никогда не включают пустую строку, которая соответствовала бы *пути*.

## Сравнение с модулями [`os`](https://python-all.ru/3.14/library/os.html#module-os) и [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path)

pathlib реализует операции с путями, используя объекты [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath) и [`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path), и поэтому считается *объектно-ориентированным*. С другой стороны, модули [`os`](https://python-all.ru/3.14/library/os.html#module-os) и [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path) предоставляют функции, работающие с низкоуровневыми объектами `str` и `bytes`, что является более *процедурным* подходом. Некоторые пользователи считают объектно-ориентированный стиль более читаемым.

Многие функции в [`os`](https://python-all.ru/3.14/library/os.html#module-os) и [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path) поддерживают пути `bytes` и [пути, относительные относительно дескрипторов каталогов](https://python-all.ru/3.14/library/os.html#dir-fd). Эти возможности недоступны в pathlib.

Типы `str` и `bytes`, а также части модулей [`os`](https://python-all.ru/3.14/library/os.html#module-os) и [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path), написаны на C и очень быстры. pathlib написан на чистом Python и обычно работает медленнее, но редко настолько, чтобы это было существенно.

Нормализация путей в pathlib немного более строгая и последовательная, чем в [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path). Например, тогда как [`os.path.abspath()`](https://python-all.ru/3.14/library/os.path.html#os.path.abspath) удаляет сегменты «`..`» из пути, что может изменить его значение при наличии символических ссылок, [`Path.absolute()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.absolute) сохраняет эти сегменты для большей безопасности.

Нормализация путей в pathlib может сделать её непригодной для некоторых приложений:

1. pathlib нормализует `Path("my_folder/")` в `Path("my_folder")`, что меняет значение пути при передаче в различные API операционной системы и командной строки. В частности, отсутствие завершающего разделителя может позволить разрешить путь как файл или каталог, а не только как каталог.
2. pathlib нормализует `Path("./my_program")` в `Path("my_program")`, что меняет значение пути при использовании в качестве пути поиска исполняемых файлов, например в оболочке или при порождении дочернего процесса. В частности, отсутствие разделителя в пути может заставить искать его в `PATH` вместо текущего каталога.

Вследствие этих различий pathlib не является прямой заменой для [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path).

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

Ниже представлена таблица, сопоставляющая различные функции [`os`](https://python-all.ru/3.14/library/os.html#module-os) с их эквивалентами в [`PurePath`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath)/[`Path`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path).

| [`os`](https://python-all.ru/3.14/library/os.html#module-os) и [`os.path`](https://python-all.ru/3.14/library/os.path.html#module-os.path) | `pathlib` |
| --- | --- |
| [`os.path.dirname()`](https://python-all.ru/3.14/library/os.path.html#os.path.dirname) | [`PurePath.parent`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.parent) |
| [`os.path.basename()`](https://python-all.ru/3.14/library/os.path.html#os.path.basename) | [`PurePath.name`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.name) |
| [`os.path.splitext()`](https://python-all.ru/3.14/library/os.path.html#os.path.splitext) | [`PurePath.stem`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.stem), [`PurePath.suffix`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.suffix) |
| [`os.path.join()`](https://python-all.ru/3.14/library/os.path.html#os.path.join) | [`PurePath.joinpath()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.joinpath) |
| [`os.path.isabs()`](https://python-all.ru/3.14/library/os.path.html#os.path.isabs) | [`PurePath.is_absolute()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.is_absolute) |
| [`os.path.relpath()`](https://python-all.ru/3.14/library/os.path.html#os.path.relpath) | [`PurePath.relative_to()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.relative_to) [\[1\]](https://python-all.ru/3.14/library/pathlib.html#id7) |
| [`os.path.expanduser()`](https://python-all.ru/3.14/library/os.path.html#os.path.expanduser) | [`Path.expanduser()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.expanduser) [\[2\]](https://python-all.ru/3.14/library/pathlib.html#id8) |
| [`os.path.realpath()`](https://python-all.ru/3.14/library/os.path.html#os.path.realpath) | [`Path.resolve()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.resolve) |
| [`os.path.abspath()`](https://python-all.ru/3.14/library/os.path.html#os.path.abspath) | [`Path.absolute()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.absolute) [\[3\]](https://python-all.ru/3.14/library/pathlib.html#id9) |
| [`os.path.exists()`](https://python-all.ru/3.14/library/os.path.html#os.path.exists) | [`Path.exists()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.exists) |
| [`os.path.isfile()`](https://python-all.ru/3.14/library/os.path.html#os.path.isfile) | [`Path.is_file()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_file) |
| [`os.path.isdir()`](https://python-all.ru/3.14/library/os.path.html#os.path.isdir) | [`Path.is_dir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_dir) |
| [`os.path.islink()`](https://python-all.ru/3.14/library/os.path.html#os.path.islink) | [`Path.is_symlink()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_symlink) |
| [`os.path.isjunction()`](https://python-all.ru/3.14/library/os.path.html#os.path.isjunction) | [`Path.is_junction()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_junction) |
| [`os.path.ismount()`](https://python-all.ru/3.14/library/os.path.html#os.path.ismount) | [`Path.is_mount()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.is_mount) |
| [`os.path.samefile()`](https://python-all.ru/3.14/library/os.path.html#os.path.samefile) | [`Path.samefile()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.samefile) |
| [`os.getcwd()`](https://python-all.ru/3.14/library/os.html#os.getcwd) | [`Path.cwd()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.cwd) |
| [`os.stat()`](https://python-all.ru/3.14/library/os.html#os.stat) | [`Path.stat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.stat) |
| [`os.lstat()`](https://python-all.ru/3.14/library/os.html#os.lstat) | [`Path.lstat()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.lstat) |
| [`os.listdir()`](https://python-all.ru/3.14/library/os.html#os.listdir) | [`Path.iterdir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.iterdir) |
| [`os.walk()`](https://python-all.ru/3.14/library/os.html#os.walk) | [`Path.walk()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.walk) [\[4\]](https://python-all.ru/3.14/library/pathlib.html#id10) |
| [`os.mkdir()`](https://python-all.ru/3.14/library/os.html#os.mkdir), [`os.makedirs()`](https://python-all.ru/3.14/library/os.html#os.makedirs) | [`Path.mkdir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.mkdir) |
| [`os.link()`](https://python-all.ru/3.14/library/os.html#os.link) | [`Path.hardlink_to()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.hardlink_to) |
| [`os.symlink()`](https://python-all.ru/3.14/library/os.html#os.symlink) | [`Path.symlink_to()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.symlink_to) |
| [`os.readlink()`](https://python-all.ru/3.14/library/os.html#os.readlink) | [`Path.readlink()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.readlink) |
| [`os.rename()`](https://python-all.ru/3.14/library/os.html#os.rename) | [`Path.rename()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rename) |
| [`os.replace()`](https://python-all.ru/3.14/library/os.html#os.replace) | [`Path.replace()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.replace) |
| [`os.remove()`](https://python-all.ru/3.14/library/os.html#os.remove), [`os.unlink()`](https://python-all.ru/3.14/library/os.html#os.unlink) | [`Path.unlink()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.unlink) |
| [`os.rmdir()`](https://python-all.ru/3.14/library/os.html#os.rmdir) | [`Path.rmdir()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.rmdir) |
| [`os.chmod()`](https://python-all.ru/3.14/library/os.html#os.chmod) | [`Path.chmod()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.chmod) |
| [`os.lchmod()`](https://python-all.ru/3.14/library/os.html#os.lchmod) | [`Path.lchmod()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.lchmod) |

Сноски

\[[1](https://python-all.ru/3.14/library/pathlib.html#id3)\]

[`os.path.relpath()`](https://python-all.ru/3.14/library/os.path.html#os.path.relpath) вызывает [`abspath()`](https://python-all.ru/3.14/library/os.path.html#os.path.abspath), чтобы сделать пути абсолютными и удалить части «`..`», тогда как [`PurePath.relative_to()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.PurePath.relative_to) является лексической операцией, которая возбуждает [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError), когда якоря входных путей различаются (например, если один путь абсолютный, а другой относительный).

\[[2](https://python-all.ru/3.14/library/pathlib.html#id4)\]

[`os.path.expanduser()`](https://python-all.ru/3.14/library/os.path.html#os.path.expanduser) возвращает путь без изменений, если домашний каталог не может быть определён, тогда как [`Path.expanduser()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.expanduser) возбуждает [`RuntimeError`](https://python-all.ru/3.14/library/exceptions.html#RuntimeError).

\[[3](https://python-all.ru/3.14/library/pathlib.html#id5)\]

[`os.path.abspath()`](https://python-all.ru/3.14/library/os.path.html#os.path.abspath) удаляет компоненты «`..`» без разрешения символических ссылок, что может изменить значение пути, тогда как [`Path.absolute()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.absolute) оставляет любые компоненты «`..`» в пути.

\[[4](https://python-all.ru/3.14/library/pathlib.html#id6)\]

[`os.walk()`](https://python-all.ru/3.14/library/os.html#os.walk) всегда следует символьным ссылкам при разбиении путей на *имена каталогов* и *имена файлов*, тогда как [`Path.walk()`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.walk) классифицирует все символьные ссылки как *имена файлов*, когда *follow\_symlinks* равен false (по умолчанию).

## Протоколы

Модуль `pathlib.types` предоставляет типы для статической проверки типов.

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

#### `class pathlib.types.PathInfo`

[`typing.Protocol`](https://python-all.ru/3.14/library/typing.html#typing.Protocol), описывающий атрибут [`Path.info`](https://python-all.ru/3.14/library/pathlib.html#pathlib.Path.info). Реализации могут возвращать кэшированные результаты из своих методов.

#### `exists(*, follow_symlinks=True)`

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

Если *follow\_symlinks* равен `False`, возвращает `True` для символьных ссылок без проверки существования их целей.

#### `is_dir(*, follow_symlinks=True)`

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

Если *follow\_symlinks* равен `False`, возвращает `True` только если путь является каталогом (без перехода по символьным ссылкам); возвращает `False`, если путь является любым другим типом файла, или если он не существует.

#### `is_file(*, follow_symlinks=True)`

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

Если *follow\_symlinks* равно `False`, возвращает `True` только если путь является файлом (без перехода по символическим ссылкам); возвращает `False`, если путь является каталогом или другим не-файлом, или если он не существует.

#### `is_symlink()`

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