Описанные ниже свойства и методы позволяют легко манипулировать с путями файловой системы без осуществления системных вызовов. Другими словами, при помощи этого класса можно проводить операции с путями, которых нет в файловой системе.
Данные методы принадлежат экземпляру, созданному из класса PurePath()
, стандартного модуля pathlib
.
Примечание: Все приведенные ниже операции поддерживаются классом pathlib.Path()
, т.к. он является подклассом pathlib.PurePath()
.
'/'
.PurePath.parts
:Свойство PurePath.parts
возвращает кортеж, дающее доступ к отдельным частям/компонентам пути. Полученный кортеж представляет собой последовательность сегментов пути, проанализированных на основе значения разделителя пути.
Обратите внимание, как диск и локальный корень перегруппированы в одну часть.
>>> import pathlib >>> p = pathlib.PurePath('/usr/bin/python3') >>> p.parts # ('/', 'usr', 'bin', 'python3') >>> p = pathlib.PurePath('c:/Program Files/PSF') >>> p.parts # ('c:\\', 'Program Files', 'PSF')
PurePath.drive
:Свойство PurePath.drive
возвращает строку, представляющую букву или имя диска, если есть:
>>> import pathlib >>> pathlib.PurePath('c:/Program Files/').drive # 'c:' >>> pathlib.PurePath('/Program Files/').drive # '' >>> pathlib.PurePath('/etc').drive # ''
Расширения UNC также считаются дисками:
>>> import pathlib >>> pathlib.PurePath('//host/share/foo.txt').drive # '\\\\host\\share'
PurePath.root
:Свойство PurePath.root
возвращает строку, представляющую локальный или глобальный корень, если есть:
>>> import pathlib >>> pathlib.PurePath('c:/Program Files/').root # '\\' >>> pathlib.PurePath('c:Program Files/').root # '' >>> pathlib.PurePath('/etc').root # '/'
У UNC расширения тоже всегда есть корень:
>>> import pathlib >>> pathlib.PurePath('//host/share').root # '\\'
PurePath.anchor
:Свойство PurePath.anchor
возвращает строку, представляющую конкатенацию диска и корня:
>>> import pathlib >>> pathlib.PurePath('c:/Program Files/').anchor # 'c:\\' >>> pathlib.PurePath('c:Program Files/').anchor # 'c:' >>> pathlib.PurePath('/etc').anchor # '/' >>> pathlib.PurePath('//host/share').anchor # '\\\\host\\share\\'
PurePath.parents
:Свойство PurePath.parents
представляет собой неизменную последовательность, обеспечивающую доступ к логическим предкам пути:
Изменено в Python 3.10: PurePath.parents
теперь поддерживает срезы и отрицательные значения индекса.
>>> import pathlib >>> p = pathlib.PurePath('c:/foo/bar/setup.py') >>> p.parents[0] # PureWindowsPath('c:/foo/bar') >>> p.parents[1] # PureWindowsPath('c:/foo') >>> p.parents[2] # PureWindowsPath('c:/') # Двигаемся вверх по директории >>> for up in p.parents: ... print(up) ... # c:\foo\bar # c:\foo # c:\
PurePath.parent
:Свойство PurePath.parent
возвращает строку, представляющую логический родительский путь:
>>> import pathlib >>> p = pathlib.PurePath('/a/b/c/d') >>> p.parent # PurePosixPath('/a/b/c')
Свойство не позволяет пройти мимо корневой директории или пустого пути:
>>> import pathlib >>> p = pathlib.PurePath('/') >>> p.parent # PurePosixPath('/') >>> p = pathlib.PurePath('.') >>> p.parent # PurePosixPath('.')
Заметка. Это чисто лексическая операция, отсюда и следующее поведение:
>>> import pathlib >>> p = pathlib.PurePath('foo/..') >>> p.parent # PurePosixPath('foo')
Если необходимо вычислить произвольный путь файловой системы вверх, рекомендуется сначала вызвать Path.resolve()
, чтобы разрешить символические ссылки и исключить компоненты '..'
.
PurePath.name
:Свойство PurePath.name
возвращает строку, представляющую конечный компонент пути, исключая диск и корень, если есть. Другими словами это имя файла или название последней директории в пути.
>>> import pathlib >>> pathlib.PurePath('my/library/setup.py').name # 'setup.py'
Имена дисков UNC не учитываются:
>>> import pathlib >>> pathlib.PurePath('//some/share/setup.py').name # 'setup.py' >>> pathlib.PurePath('//some/share').name # ''
PurePath.suffix
:Свойство PurePath.suffix
возвращает строку, представляющую расширение файла, если есть:
>>> import pathlib >>> pathlib.PurePath('my/library/setup.py').suffix # '.py' >>> pathlib.PurePath('my/library.tar.gz').suffix # '.gz' >>> pathlib.PurePath('my/library').suffix # ''
PurePath.suffixes
:Свойство PurePath.suffixes
возвращает список, представляющий расширения файла, если есть:
>>> import pathlib >>> pathlib.PurePath('my/library.tar.gar').suffixes # ['.tar', '.gar'] >>> pathlib.PurePath('my/library.tar.gz').suffixes # ['.tar', '.gz'] >>> pathlib.PurePath('my/library').suffixes # []
PurePath.stem
:Свойство PurePath.stem
возвращает строку, представляющую последний компонент пути без суффикса:
>>> import pathlib >>> pathlib.PurePath('my/library.tar.gz').stem # 'library.tar' >>> pathlib.PurePath('my/library.tar').stem # 'library' >>> pathlib.PurePath('my/library').stem # 'library'
PurePath.as_posix()
:Метод PurePath.as_posix()
возвращает строковое представление пути с косыми чертами '/'
:
>>> import pathlib >>> p = pathlib.PurePath('c:\\windows') >>> str(p) # 'c:\\windows' >>> p.as_posix() # 'c:/windows'
PurePath.as_uri()
:Метод PurePath.as_uri()
возвращает строку, представляющую путь как file URI. если путь не абсолютен, то поднимается исключение ValueError
.
>>> import pathlib >>> p = PurePath('/etc/passwd') >>> p.as_uri() # 'file:///etc/passwd' >>> p = PurePath('c:/Windows') >>> p.as_uri() # 'file:///c:/Windows'
PurePath.is_absolute()
:Метод PurePath.is_absolute()
проверяет, является ли путь абсолютным или нет. Возвращает True
, если путь считается абсолютным. Путь считается абсолютным, если он имеет как корень так и диск, если это позволяет файловая система:
>>> import pathlib >>> pathlib.PurePath('/a/b').is_absolute() # True >>> pathlib.PurePath('a/b').is_absolute() # False >>> pathlib.PurePath('c:/a/b').is_absolute() # True >>> pathlib.PurePath('/a/b').is_absolute() # False >>> pathlib.PurePath('c:').is_absolute() # False >>> pathlib.PurePath('//some/share').is_absolute() # True
PurePath.is_relative_to(*other)
:Новое в версии Python 3.9.
Метод PurePath.is_relative_to()
возвращает значение True
, если путь PurePath
является относительным пути other
.
>>> from pathlib import PurePath >>> p = PurePath('/etc/passwd') >>> p.is_relative_to('/etc') # True >>> p.is_relative_to('/usr') # False
Передача дополнительных позиционных аргументов устарела c версии Python 3.12, будет удалено в Python 3.14. Если все-же они предоставлены, то они соединяются с
other
.
PurePath.is_reserved()
:Метод PurePath.is_reserved()
c pathlib.PureWindowsPath
возвращает True
, если путь считается зарезервированным под Windows и False
противном случае. С pathlib.PurePosixPath
, всегда возвращает False
.
>>> import pathlib >>> pathlib.PurePath('nul').is_reserved() # True >>> pathlib.PurePath('nul').is_reserved() # False
Вызовы файловой системы на зарезервированных путях под Windows могут таинственно завершаться сбоем или иметь непредвиденные последствия.
PurePath.joinpath(*other)
:Метод PurePath.joinpath()
объединяет исходный путь с каждым из аргументов other
по очереди:
>>> import pathlib >>> pathlib.PurePath('/etc').joinpath('passwd') # PurePosixPath('/etc/passwd') >>> pathlib.PurePath('/etc').joinpath(PurePosixPath('passwd')) # PurePosixPath('/etc/passwd') >>> pathlib.PurePath('/etc').joinpath('init.d', 'apache2') # PurePosixPath('/etc/init.d/apache2') >>> pathlib.PurePath('c:').joinpath('/Program Files') # PureWindowsPath('c:/Program Files')
PurePath.match(pattern, *, case_sensitive=None)
:Изменено в версии Python 3.12: Добавлен аргумент
case_sensitivity
.
Метод PurePath.match()
сравнивает исходный путь с предоставленным шаблоном pattern
в стиле модуля glob
. Метод PurePath.match
вернет True
если сопоставление прошло успешно и False
в противном случае.
Если шаблон pattern
является относительным по отношению к сравниваемому пути. Сравниваемый путь может быть как относительным так и абсолютным, а сопоставление выполняется справа:
>>> import pathlib >>> pathlib.PurePath('a/b.py').match('*.py') # True >>> pathlib.PurePath('/a/b/c.py').match('b/*.py') # True >>> pathlib.PurePath('/a/b/c.py').match('a/*.py') # False
Если шаблон pattern
является абсолютным, то и путь должен быть абсолютным и весь путь должен совпадать:
>>> import pathlib >>> pathlib.PurePath('/a.py').match('/*.py') # True >>> pathlib.PurePath('a/b.py').match('/*.py') # False
Шаблон pattern
может быть другим объектом пути; это ускоряет сопоставление одного и того же шаблона с несколькими файлами:
>>> pattern = PurePath('*.py') >>> PurePath('a/b.py').match(pattern) # True
Как и в других методах, чувствительность к регистру соответствует настройкам платформы по умолчанию:
>>> PurePosixPath('b.py').match('*.PY') # False >>> PureWindowsPath('b.py').match('*.PY') # True
Аргумент case_sensitivity
(добавлен в Python 3.12) отвечает за чувствительность к регистру при сравнении. Для переопределения поведения принимает значение True
или False
.
PurePath.relative_to(*other, walk_up=False)
:Метод PurePath.relative_to()
вычисляет версию исходного пути относительно переданного в качестве аргумента пути other
. Если это невозможно, то поднимается исключение ValueError
:
>>> import pathlib >>> p = pathlib.PurePath('/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'
Если аргумент walk_up
(добавлен в Python 3.12) имеет значение False
(по умолчанию), то путь должен начинаться с other
. Если аргумент имеет значение True
, то можно добавлять записи ..
для формирования относительного пути. Во всех остальных случаях, например, когда пути ссылаются на разные диски, возникает ValueError
:
>>> p.relative_to('/usr', walk_up=True) # PurePosixPath('../etc/passwd') >>> p.relative_to('foo', walk_up=True) # Traceback (most recent call last): # File "<stdin>", line 1, in <module> # File "pathlib.py", line 941, in relative_to # raise ValueError(error_message.format(str(self), str(formatted))) # ValueError: '/etc/passwd' is not on the same drive as 'foo' # OR one path is relative and the other is absolute.
Предупреждение. Функция является частью
PurePath
и работает со строками. Она не проверяет и не получает доступ к файловой структуре. Это может повлиять на аргументwalk_up
, поскольку он предполагает, что в пути нет символических ссылок. То есть, если необходимо разрешить символические ссылки, то сначала нужно вызвать методPath.resolve()
.Изменено в версии Python 3.12: добавлен аргумент
walk_up
(старое поведение такое же, какwalk_up=False
).Передача дополнительных позиционных аргументов устарела c версии Python 3.12, будет удалено в Python 3.14. Если все-же они предоставлены, то они соединяются с
other
.
PurePath.with_name(name)
:Метод PurePath.with_name()
возвращает новый объект пути с измененным name
. Если исходный путь не имеет имени name
, вызывается исключение ValueError
:
>>> import pathlib >>> p = pathlib.PurePath('c:/Downloads/pathlib.tar.gz') >>> p.with_name('setup.py') # PureWindowsPath('c:/Downloads/setup.py') >>> p = pathlib.PurePath('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)
:Новое в версии Python 3.9.
Метод PurePath.with_stem()
возвращает новый путь с измененной основой stem
. Если исходный путь PurePath
не имеет имени, то вызывается 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
Новое в версии Python 3.9.
PurePath.with_suffix(suffix)
:Метод PurePath.with_suffix()
возвращает новый объект пути с измененным suffix
. Если исходный путь не имеет расширения suffix
, то к окончанию пути тупо добавляется переданный suffix
.
Если суффикс suffix=''
- является пустой строкой, исходный суффикс удаляется:
>>> import pathlib >>> p = pathlib.PurePath('c:/Downloads/pathlib.tar.gz') >>> p.with_suffix('.bz2') # PureWindowsPath('c:/Downloads/pathlib.tar.bz2') >>> p = pathlib.PurePath('README') >>> p.with_suffix('.txt') # PureWindowsPath('README.txt') >>> p = pathlib.PurePath('README.txt') >>> p.with_suffix('') # PureWindowsPath('README')
PurePath.with_segments(*pathsegments)
:Новое в версии Python 3.12.
Метод PurePath.with_segments()
создает новый объект пути того же типа, объединив заданные сегменты пути *pathsegments
.
Этот метод вызывается всякий раз, когда создается производный путь, например, от PurePath.parent
и PurePath.relative_to()
.
Подклассы могут переопределить этот метод для передачи информации в производные пути, например:
from pathlib import PurePosixPath class MyPath(PurePosixPath): def __init__(self, *pathsegments, session_id): super().__init__(*pathsegments) self.session_id = session_id def with_segments(self, *pathsegments): return type(self)(*pathsegments, session_id=self.session_id) etc = MyPath('/etc', session_id=42) hosts = etc / 'hosts' print(hosts.session_id) # 42