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

Added in version 3.4.

Источник: Lib/pathlib/

---

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

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

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

1. Если вы хотите работать с путями Windows на машине Unix (или наоборот). Вы не можете инстанцировать WindowsPath при работе на Unix, но можете инстанцировать PureWindowsPath.

2. Вы хотите быть уверены, что ваш код только манипулирует путями, не обращаясь к ОС. В этом случае может оказаться полезным инстанцирование одного из чистых классов, поскольку в них просто нет операций доступа к ОС.

См.также

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'

Исключения

exception pathlib.UnsupportedOperation

Исключение, наследующее NotImplementedError, которое возникает при вызове неподдерживаемой операции над объектом path.

Added in version 3.13.

Чистые пути

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

class pathlib.PurePath(*pathsegments)

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

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

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

>>> 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 - это символическая ссылка на другой каталог)

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

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

class pathlib.PurePosixPath(*pathsegments)

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

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

Сегменты пути задаются аналогично PurePath.

class pathlib.PureWindowsPath(*pathsegments)

Являясь подклассом PurePath, этот аромат путей представляет пути файловой системы Windows, включая UNC paths:

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

Сегменты пути задаются аналогично PurePath.

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

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

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

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

Объект path может использоваться везде, где принимается объект, реализующий 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 каноническим представлением путей к файловой системе является форма юникода.

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

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

PurePath.parts

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

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

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

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

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

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

PurePath.parser

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

Added in version 3.13.

PurePath.drive

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

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

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

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

PurePath.root

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

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

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

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

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

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

Примечание

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

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

PurePath.anchor

Конкатенация диска и корня:

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

PurePath.parents

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

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

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

PurePath.parent

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

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

Вы не можете пройти мимо якоря или пустого пути:

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

Примечание

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

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

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

PurePath.name

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

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

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

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

PurePath.suffix

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

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

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

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

PurePath.suffixes

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

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

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

PurePath.stem

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

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

PurePath.as_posix()

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

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

PurePath.is_absolute()

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

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

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

PurePath.is_relative_to(other)

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

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

Added in version 3.9.

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

PurePath.is_reserved()

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

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

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

PurePath.joinpath(*pathsegments)

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

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

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

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

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

См.также

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

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

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

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

Added in version 3.13.

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

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

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

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

Изменено в версии 3.12: Параметр pattern принимает значение path-like object.

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

PurePath.relative_to(other, walk_up=False)

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

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

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

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

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

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

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

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

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

Added in version 3.9.

PurePath.with_suffix(suffix)

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

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

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

PurePath.with_segments(*pathsegments)

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

from pathlib import PurePosixPath

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

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

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

Added in version 3.12.

Бетонные дорожки

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

class pathlib.Path(*pathsegments)

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

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

Сегменты пути задаются аналогично PurePath.

class pathlib.PosixPath(*pathsegments)

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

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

Сегменты пути задаются аналогично PurePath.

Изменено в версии 3.13: Поднимает UnsupportedOperation в Windows. В предыдущих версиях вместо этого поднимался NotImplementedError.

class pathlib.WindowsPath(*pathsegments)

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

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

Сегменты пути задаются аналогично PurePath.

Изменено в версии 3.13: Повышает значение UnsupportedOperation на платформах, отличных от Windows. В предыдущих версиях вместо этого поднимался NotImplementedError.

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

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

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

Конкретные объекты пути могут быть созданы и представлены как URI „file“, соответствующие RFC 8089.

Примечание

URI файлов не переносятся на машины с различными filesystem encodings.

classmethod Path.from_uri(uri)

Возвращает новый объект пути в результате разбора URI „file“. Например:

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

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

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

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

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

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

Added in version 3.13.

Path.as_uri()

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

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

По историческим причинам этот метод также доступен из объектов PurePath. Однако использование os.fsencode() делает его строго нечистым.

Запрос типа и состояния файла

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

Изменено в версии 3.14: Приведенные выше методы теперь возвращают False, а не вызывают любое исключение OSError из операционной системы. В предыдущих версиях некоторые виды исключений OSError вызывались, а другие подавлялись. Новое поведение соответствует os.path.exists(), os.path.isdir() и т. д. Для получения информации о состоянии файла без подавления исключений используйте команду stat().

Path.stat(*, follow_symlinks=True)

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

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

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

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

Path.lstat()

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

Path.exists(*, follow_symlinks=True)

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

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

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

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

Path.is_file(*, follow_symlinks=True)

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

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

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

Path.is_dir(*, follow_symlinks=True)

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

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

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

Path.is_symlink()

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

Path.is_junction()

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

Added in version 3.12.

Path.is_mount()

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

Added in version 3.7.

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

Path.is_socket()

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

Path.is_fifo()

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

Path.is_block_device()

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

Path.is_char_device()

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

Path.samefile(other_path)

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

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

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

Added in version 3.5.

Другие методы

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

classmethod Path.cwd()

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

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

classmethod Path.home()

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

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

Added in version 3.5.

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

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

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

Added in version 3.5.

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

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

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

См.также

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

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

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

Поднимает auditing event pathlib.Path.glob с аргументами self, pattern.

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

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

Изменено в версии 3.13: Параметр pattern принимает значение path-like object.

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

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

Рекурсивно собирает заданный относительный шаблон. Это похоже на вызов Path.glob() с добавлением «**/» перед шаблоном.

См.также

Документация Язык шаблонов и Path.glob().

Поднимает auditing event pathlib.Path.rglob с аргументами self, pattern.

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

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

Изменено в версии 3.13: Параметр pattern принимает значение path-like object.

Path.group(*, follow_symlinks=True)

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

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

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

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

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.walk(top_down=True, on_error=None, follow_symlinks=False)

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

Для каждого каталога в дереве каталогов, корнем которого является self (включая self, но исключая „.“ и „.“), метод выдает 3-кортеж (dirpath, dirnames, filenames).

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

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

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

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

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

Примечание

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

Примечание

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

Примечание

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

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

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

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

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

Added in version 3.12.

Path.lchmod(mode)

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

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(*, follow_symlinks=True)

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

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

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

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

Path.read_bytes()

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

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

Added in version 3.5.

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

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

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

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

Added in version 3.5.

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

Path.readlink()

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

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

Added in version 3.9.

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

Path.rename(target)

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

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

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

Он реализуется в терминах os.rename() и дает те же гарантии.

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

Path.replace(target)

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

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

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

Path.absolute()

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

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

Path.resolve(strict=False)

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

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

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

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

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

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

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

Path.rmdir()

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

Path.symlink_to(target, target_is_directory=False)

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

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

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

Примечание

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

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

Path.hardlink_to(target)

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

Примечание

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

Added in version 3.10.

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

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

Создает файл по заданному пути. Если задан mode, он комбинируется со значением umask процесса для определения режима файла и флагов доступа. Если файл уже существует, функция работает успешно, если exist_ok истинна (и время модификации обновляется до текущего времени), в противном случае выдается значение 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)

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

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

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

Added in version 3.5.

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

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

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

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

Added in version 3.5.

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

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

В шаблонах для full_match(), glob() и rglob() поддерживаются следующие подстановочные знаки:

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

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

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

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

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

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

?

Сопоставляет один символ без разделителя.

[seq]

Совпадает с одним символом в seq.

[!seq]

Сопоставляет один символ, не входящий в seq.

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

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

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

Примечание

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

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

В Path.glob() и rglob() к шаблону может быть добавлена косая черта, чтобы соответствовать только каталогам.

Изменено в версии 3.11: Охват шаблоном, который заканчивается разделителем компонентов имени пути (sep или altsep), возвращает только каталоги.

Сравнение с модулем glob

Шаблоны, принимаемые и генерируемые модулями Path.glob() и Path.rglob(), несколько отличаются от тех, которые генерируются модулем glob:

1. Файлы, начинающиеся с точки, не являются специальными в pathlib. Это все равно что передать include_hidden=True в glob.glob().

2. Компоненты шаблона «**» всегда рекурсивны в pathlib. Это все равно что передать recursive=True в glob.glob().

3. Компоненты шаблона «**» по умолчанию не следуют за симлинками в pathlib. Это поведение не имеет эквивалента в glob.glob(), но вы можете передать recurse_symlinks=True в Path.glob() для совместимого поведения.

4. Как и все объекты PurePath и Path, значения, возвращаемые из Path.glob() и Path.rglob(), не содержат косых черт.

5. Значения, возвращаемые функциями pathlib path.glob() и path.rglob(), включают path в качестве префикса, в отличие от результатов glob.glob(root_dir=path).

6. Значения, возвращаемые функциями pathlib path.glob() и path.rglob(), могут включать сам path, например, при сглаживании «**», тогда как результаты glob.glob(root_dir=path) никогда не включают пустую строку, которая соответствовала бы path.

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

pathlib реализует операции с путями, используя объекты PurePath и Path, и поэтому считается, что он объектно-ориентирован. С другой стороны, модули os и os.path предоставляют функции, работающие с низкоуровневыми объектами str и bytes, что является более процедурным подходом. Некоторые пользователи считают объектно-ориентированный стиль более удобным для чтения.

Многие функции в os и os.path поддерживают пути bytes и paths relative to directory descriptors. Эти функции недоступны в pathlib.

Типы str и bytes в Python, а также части модулей os и os.path написаны на C и очень быстры. pathlib написан на чистом Python и часто работает медленнее, но редко настолько медленно, чтобы это имело значение.

Нормализация путей в pathlib немного более последовательна, чем в os.path. Например, если os.path.abspath() удаляет из пути сегменты «..», которые могут изменить его смысл, если в нем задействованы симлинки, то Path.absolute() сохраняет эти сегменты для большей безопасности.

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

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

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

Вследствие этих различий pathlib не является универсальной заменой os.path.

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

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

os и os.path	pathlib
os.path.abspath()	Path.absolute()
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.walk()	Path.walk()
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()
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