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

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

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

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

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

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

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

Методы

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

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)

Производит поиск по шаблону 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-узел на одном и том же устройстве — это должно определять точки монтирования для всех вариантов 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()

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

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

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

Path.lchmod(mode)

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

Path.lstat()

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

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

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

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

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

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

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

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

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

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

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

Path.owner()

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

Path.read_bytes()

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

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

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

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

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

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

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

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

Path.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 было strict).

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

Создать жёсткую ссылку на этот путь из target.

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

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

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

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

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

Path.unlink(missing_ok=False)

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

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

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

Path.write_bytes(data)

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

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

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

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

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

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

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

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

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