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

Новое в версии 3.4.

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

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

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

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

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

См. также

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

См. также

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

Базовое использование

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

>>> from pathlib import Path

Вывод подкаталогов:

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

Вывод файлов Python в этом дереве каталогов:

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

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

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

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

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

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

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

Чистые пути

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

class pathlib.PurePath(*pathsegments)

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

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

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

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

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

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

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

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

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

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

Избыточные косые черты и одиночные точки сворачиваются, но двойные точки ('..') и ведущие двойные косые черты ('//') не сворачиваются, так как это изменит значение пути по разным причинам (например, символические ссылки, пути UNC):

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

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

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

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

class pathlib.PurePosixPath(*pathsegments)

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

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

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

class pathlib.PureWindowsPath(*pathsegments)

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

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

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

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

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

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

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

Пути разных типов неравны и не могут быть упорядочены:

>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

Операторы

Оператор с косой чертой помогает создать дочерние пути, подобно os.path.join(). Если аргумент — абсолютный путь, предыдущий путь игнорируется. В Windows диск не сбрасывается, когда аргумент — относительный путь с корнем (например, r'\foo'):

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')
>>> p / '/an_absolute_path'
PurePosixPath('/an_absolute_path')
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

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

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

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

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

Аналогично, вызов bytes для пути возвращает путь к файлу системы как объект байтов, закодированный с помощью 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.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 Issue 6, пункт 4.11 Разрешение имен путей:

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

PurePath.anchor

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

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

PurePath.parents

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

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

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

PurePath.parent

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

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

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

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

Примечание

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

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

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

PurePath.name

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

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

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

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

PurePath.suffix

Расширение файла конечного компонента, если таковое имеется:

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

PurePath.suffixes

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

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

PurePath.stem

Конечный компонент пути без расширения:

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

PurePath.as_posix()

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

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

PurePath.as_uri()

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

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

PurePath.is_absolute()

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

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

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

PurePath.is_relative_to(*other)

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

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

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

PurePath.is_reserved()

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

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

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

PurePath.joinpath(*other)

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

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

PurePath.match(pattern)

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

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

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

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

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

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

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

PurePath.relative_to(*other)

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

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

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

PurePath.with_name(name)

Возвращает новый путь с изменённым name. Если у исходного пути нет имени, генерируется ValueError:

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

PurePath.with_stem(stem)

Возвращает новый путь с изменённым stem. Если у исходного пути нет имени, генерируется ValueError:

>>> p = PureWindowsPath('c:/Downloads/draft.txt')
>>> p.with_stem('final')
PureWindowsPath('c:/Downloads/final.txt')
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_stem('lib')
PureWindowsPath('c:/Downloads/lib.gz')
>>> p = PureWindowsPath('c:/')
>>> p.with_stem('')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

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

PurePath.with_suffix(suffix)

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

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

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

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

class pathlib.Path(*pathsegments)

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

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

pathsegments указывается аналогично PurePath.

class pathlib.PosixPath(*pathsegments)

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

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

pathsegments указывается аналогично PurePath.

class pathlib.WindowsPath(*pathsegments)

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

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

pathsegments указывается аналогично PurePath.

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

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

Методы

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

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

classmethod Path.cwd()

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

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

classmethod Path.home()

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

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

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

Path.stat(*, follow_symlinks=True)

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

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

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

Изменено в версии 3.10: Параметр follow_symlinks был добавлен.

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

Изменить режим и разрешения файла, как os.chmod().

Этот метод обычно следует за символическими ссылками. Некоторые варианты Unix поддерживают изменение разрешений на самой символической ссылке; в этих платформах вы можете добавить аргумент follow_symlinks=False, или использовать lchmod().

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

Изменено в версии 3.10: Параметр follow_symlinks был добавлен.

Path.exists()

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

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

Примечание

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

Path.expanduser()

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

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

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

Path.glob(pattern)

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

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

Шаблоны такие же, как и для fnmatch, с добавлением “**”, что означает «эта директория и все поддиректории рекурсивно». Другими словами, это позволяет рекурсивный поиск:

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

Примечание

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

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

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

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

Path.is_dir()

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

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

Path.is_file()

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

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

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

Path.is_symlink()

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

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

Path.is_socket()

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

Path.is_fifo()

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

Path.is_block_device()

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

Path.is_char_device()

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

Path.iterdir()

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

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

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

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

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

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

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

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

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

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

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

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

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

Открывает файл по указанному пути, подобно встроенной функции open():

>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'

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

Path.read_bytes()

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

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

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

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

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

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

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

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

Path.readlink()

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

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

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

Path.rename(target)

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

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

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

Реализуется с помощью os.rename() и обеспечивает те же гарантии.

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

Path.replace(target)

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

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

Path.absolute()

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

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

Path.resolve(strict=False)

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

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

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

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

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

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

Path.rglob(pattern)

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

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

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

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

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

Path.samefile(other_path)

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

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

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

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

Path.symlink_to(target, target_is_directory=False)

Преобразует этот путь в символическую ссылку на target. В Windows, target_is_directory должно быть True (по умолчанию False) если целевой объект ссылки является каталогом. В POSIX значение target_is_directory игнорируется.

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

Примечание

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

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

Примечание

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

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

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

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

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

Новое в версии 3.8.

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

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

Path.unlink(missing_ok=False)

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

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

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

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

Path.write_bytes(data)

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

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

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

Новое в версии 3.5.

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

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

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

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

Новое в версии 3.5.

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

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

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

Примечание

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

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

Примечания

1: os.path.abspath() нормализует полученный путь, что может изменить его значение при наличии символических ссылок, в то время как Path.absolute() этого не делает.
2: PurePath.relative_to() требует, чтобы self был подпутем аргумента, но os.path.relpath() этого не делает.