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

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

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

Если вы никогда раньше не использовали данный модуль или просто не уверены, какой класс подходит для вашей задачи, 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')      # Запуск на Unix-машине
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 изменение локального корня не отменяет предыдущую настройку диска:

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

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

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

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

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

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

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

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

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

Представить путь как URI file. Вызывается 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_reserved()

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

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

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

PurePath.joinpath(*other)

Вызов этого метода эквивалентен объединению пути с каждым из 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.

Если 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' does not start with '/usr'

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_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() с конструкцией ~):

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

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

Path.stat()

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

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

Path.chmod(mode)

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

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

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

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

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

Path.glob(pattern)

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

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

Шаблон «**» означает «рекурсивно этот каталог и всех подкаталогах». Другими словами, он разрешает рекурсивную подстановку:

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

Примечание

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

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

Path.is_dir()

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

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

Path.is_file()

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

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

Path.is_mount(): Возвращает True, если путь — точка монтирования: точка в файловой системе, где была смонтирована другая файловая система. В POSIX функция проверяет, находится ли родитель path, path/.., на другом устройстве, чем path, или же path/.. и path указывают на один и тот же i-node на одном устройстве — это должно определять точки монтирования для всех вариантов 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, оно объединяется со значением 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()

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

>>> 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.rename(target)

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

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

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

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

Path.replace(target)

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

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

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

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

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)

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

Path.unlink(missing_ok=False)

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

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

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

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

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

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

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)

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

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

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

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

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

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

Примечание

Хотя os.path.relpath() и PurePath.relative_to() имеют несколько перекрывающихся вариантов использования, их семантика достаточно различается, чтобы не считать их эквивалентными.

os и os.path	pathlib
`os.path.abspath()`	`Path.resolve()`
`os.chmod()`	`Path.chmod()`
`os.mkdir()`	`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.link_to()`
`os.symlink()`	`Path.symlink_to()`
`os.stat()`	`Path.stat()`, `Path.owner()`, `Path.group()`
`os.path.isabs()`	`PurePath.is_absolute()`
`os.path.join()`	`PurePath.joinpath()`
`os.path.basename()`	`PurePath.name`
`os.path.dirname()`	`PurePath.parent`
`os.path.samefile()`	`Path.samefile()`
`os.path.splitext()`	`PurePath.suffix`

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

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

Чистые пути

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

Операторы

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

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

Пути

Методы

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

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

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