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

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

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


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

../../_images/pathlib-inheritance.png

Если вы никогда раньше не использовали этот модуль или просто не уверены, какой класс подходит для вашей задачи, то, скорее всего, вам нужен 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'

Чистые пути

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

class pathlib.PurePath(*pathsegments)

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

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

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

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

Объекты Pure path реализуют интерфейс 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 paths:

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

pathsegments указывается аналогично 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 для path выдает исходный путь к файловой системе в виде объекта bytes, закодированного как os.fsencode():

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

Примечание

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

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

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

PurePath.parts

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

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

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

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

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

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

PurePath.drive

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

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

Общие ресурсы UNC также считаются накопителями:

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

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

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

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

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

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

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

Примечание

Такое поведение соответствует Стандарту Open Group Base Specifications, выпуск 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
''
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

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

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

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

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

PurePath.is_reserved()

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

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

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

PurePath.joinpath(*other)

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

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

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

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

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

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

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

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

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

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

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

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

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

PurePath.with_name(name)

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

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

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

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

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

PurePath.with_suffix(suffix)

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

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

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

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

class pathlib.Path(*pathsegments)

Подкласс PurePath, этот класс представляет конкретные пути системного типа path (при его создании создается либо 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()

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

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

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

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

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

Path.stat(*, follow_symlinks=True)

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

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

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

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

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

Измените режим работы с файлами и права доступа, например, os.chmod().

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

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

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

Path.exists()

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

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

Примечание

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

Path.expanduser()

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

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

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

Path.glob(pattern)

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

>>> 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: Возвращает только каталоги, если pattern заканчивается разделителем компонентов имени пути (sep или altsep).

Path.group()

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

Path.is_dir()

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

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

Path.is_file()

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

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

Path.is_mount()

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

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

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

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

Path.is_socket()

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

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

Path.is_fifo()

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

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

Path.is_block_device()

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

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

Path.is_char_device()

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

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

Path.iterdir()

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

>>> 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 для этого файла.

Path.lchmod(mode)

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

Path.lstat()

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

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

Создайте новый каталог по этому заданному пути. Если задан параметр mode, он объединяется со значением process“ 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 вызывается, если uid файла не найден в системной базе данных.

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.

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

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

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

Path.absolute()

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

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

Сделайте путь абсолютным, разрешив все символические ссылки. Будет возвращен новый объект path:

>>> 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() с добавлением «**/» перед заданным относительным шаблоном **:

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

Возвращает, указывает ли этот путь на тот же файл, что и 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.

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

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

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

Примечание

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

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

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

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

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

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

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

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

Создайте файл по указанному пути. Если задан параметр mode, он объединяется со значением process“ umask для определения режима файла и флагов доступа. Если файл уже существует, функция завершается успешно, если значение exist_ok равно true (и время его изменения обновляется до текущего времени), в противном случае генерируется значение FileExistsError.

Удалите этот файл или символическую ссылку. Если путь указывает на каталог, используйте вместо этого 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'

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

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

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

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

Соответствие инструментам в модуле 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

Сноски

Вернуться на верх