pathlib
— Пути к объектно-ориентированной файловой системе¶
Добавлено в версии 3.4.
Исходный код: Lib/pathlib.py
Этот модуль предлагает классы, представляющие пути к файловой системе с семантикой, подходящей для различных операционных систем. Классы путей делятся на pure paths, которые обеспечивают чисто вычислительные операции без ввода-вывода, и concrete paths, которые наследуются от чистых путей, но также обеспечивают операции ввода-вывода.

Если вы никогда раньше не использовали этот модуль или просто не уверены, какой класс подходит для вашей задачи, то, скорее всего, вам нужен Path
. Он создает экземпляр concrete 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'
Чистые пути¶
Объекты 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
.
- 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.
- Path.is_symlink()¶
Верните
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
не будет запущен, если только указанный путь уже не существует в файловой системе и не является каталогом (аналогично команде POSIXmkdir -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.
- 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 указывает на существующий файл или пустой каталог, он будет безоговорочно заменен.
Целевой путь может быть абсолютным или относительным. Относительные пути интерпретируются относительно текущего рабочего каталога, а не каталога объекта 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
.
- Path.rmdir()¶
Удалите этот каталог. Каталог должен быть пустым.
- Path.samefile(other_path)¶
Возвращает, указывает ли этот путь на тот же файл, что и other_path, который может быть либо объектом Path, либо строкой. Семантика аналогична
os.path.samefile()
иos.path.samestat()
.Значение
OSError
может быть вызвано, если по какой-либо причине доступ к любому из файлов невозможен.>>> p = Path('spam') >>> q = Path('eggs') >>> p.samefile(q) False >>> p.samefile('spam') True
Добавлено в версии 3.5.
- Path.symlink_to(target, target_is_directory=False)¶
Сделайте этот путь символической ссылкой, указывающей на цель.
В Windows символическая ссылка представляет либо файл, либо каталог и не преобразуется в целевой объект динамически. Если целевой объект присутствует, тип символической ссылки будет создан соответствующим образом. В противном случае символическая ссылка будет создана как каталог, если значение target_is_directory равно
True
, или как символическая ссылка на файл (по умолчанию). На платформах, отличных от Windows, значение target_is_directory игнорируется.>>> p = Path('mylink') >>> p.symlink_to('setup.py') >>> p.resolve() PosixPath('/home/antoine/pathlib/setup.py') >>> p.stat().st_size 956 >>> p.lstat().st_size 8
Примечание
Порядок аргументов (ссылка, цель) является обратным порядку
os.symlink()
.
- Path.hardlink_to(target)¶
Сделайте этот путь жесткой ссылкой на тот же файл, что и target.
Примечание
Порядок аргументов (ссылка, цель) является обратным порядку
os.link()
.Добавлено в версии 3.10.
- Path.link_to(target)¶
Сделайте target жесткой ссылкой на этот путь.
Предупреждение
Эта функция не делает этот путь жесткой ссылкой на target, несмотря на то, что имена функций и аргументов подразумеваются. Порядок следования аргументов (цель, ссылка) является обратным
Path.symlink_to()
иPath.hardlink_to()
, но совпадает с порядком следованияos.link()
.Добавлено в версии 3.8.
Не рекомендуется, начиная с версии 3.10: Этот метод устарел в пользу
Path.hardlink_to()
, так как порядок аргументовPath.link_to()
не совпадает с порядком аргументовPath.symlink_to()
.
- Path.touch(mode=0o666, exist_ok=True)¶
Создайте файл по указанному пути. Если задан параметр mode, он объединяется со значением process“
umask
для определения режима файла и флагов доступа. Если файл уже существует, функция завершается успешно, если значение exist_ok равно true (и время его изменения обновляется до текущего времени), в противном случае генерируется значениеFileExistsError
.
- Path.unlink(missing_ok=False)¶
Удалите этот файл или символическую ссылку. Если путь указывает на каталог, используйте вместо этого
Path.rmdir()
.Если значение missing_ok равно false (значение по умолчанию), то
FileNotFoundError
вызывается, если путь не существует.Если missing_ok имеет значение true,
FileNotFoundError
исключения будут проигнорированы (аналогично команде POSIXrm -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()
.
Сноски