Безопасная кроссплатформенная работа с путями в Python через pathlib

Чистые пути против конкретных путей: выбор правильного класса

pathlib делит свой API на две группы. PurePath и его подклассы (PurePosixPath, PureWindowsPath) выполняют только строковые вычисления, такие как соединение, разделение и замена суффикса, не производя системных вызовов. Path, PosixPath и WindowsPath наследуются от чистых классов и добавляют методы ввода-вывода, такие как open, read_text и mkdir.

Ключевое понимание для кроссплатформенной работы заключается в том, что любой чистый вариант можно инстанцировать на любой операционной системе. На машине Linux нельзя создать WindowsPath, так как это попыталось бы выполнить специфичный для Windows системный вызов, но PureWindowsPath работает везде. Это позволяет валидировать, нормализовать или преобразовывать UNC-путь Windows в тестовой среде Unix, не касаясь файловой системы.

Согласно документации pathlib, чистые пути полезны, когда нужно манипулировать путями Windows на машине Unix или когда необходимо гарантировать, что код никогда не выполняет операции доступа к ОС. Конкретные пути следует резервировать для момента, когда действительно требуется взаимодействие с файловой системой.

from pathlib import Path, PureWindowsPath, PurePosixPath, UnsupportedOperation, NotImplementedError  # noqa: F401 (illustrative imports only)

Проверка существования и типа без состояний гонки

exists(), is_file() и is_dir() возвращают булевы значения, вызывая stat под капотом. Они удобны для быстрой диагностики, но создают состояние гонки времени проверки до времени использования: другой процесс или поток может удалить или заменить файл между проверкой и последующим открытием. В документации pathlib отмечается, что методы конкретных путей могут вызывать OSError, если системный вызов завершается ошибкой.

Более безопасный шаблон - пытаться выполнить операцию непосредственно внутри блока try/except OSError. Если проверка необходима заранее (например, чтобы решить, создавать или читать), держите окно между проверкой и действием максимально коротким и все равно оборачивайте действие в обработку исключений.

from pathlib import Path

target = Path('output/report.csv')

# Preferred: attempt and handle failure
try:
    content = target.read_text(encoding='utf-8')
except FileNotFoundError:
    print(f'{target} does not exist yet')
except PermissionError:
    print(f'No permission to read {target}')
except OSError as exc:
    print(f'OS error on {target}: {exc}')

Безопасное изменение расширений с помощью with_suffix, with_name и with_stem

with_suffix заменяет существующий суффикс или добавляет новый, если его нет. Передача пустой строки полностью удаляет суффикс. Метод смотрит только на последний сегмент после точки, поэтому для файла archive.tar.gz суффиксом является '.gz', и with_suffix('.bz2') даст archive.tar.bz2, а не archive.bz2.

with_name заменяет весь финальный компонент, включая любой суффикс. with_stem (добавлен в Python 3.9) изменяет только часть перед суффиксом, сохраняя его. Оба метода вызывают ValueError, когда у пути нет компонента имени, например, для корневого диска C:/.

Распространенная ошибка - предполагать, что with_suffix обрабатывает многокомпонентные расширения, такие как .tar.gz, как единое целое. Он этого не делает; для составных расширений нужно использовать with_name или ручную конструкцию основы имени.

from pathlib import PureWindowsPath

p = PureWindowsPath('c:/Downloads/archive.tar.gz')
print(p.with_suffix('.bz2'))   # c:/Downloads/archive.tar.bz2
print(p.with_stem('backup'))   # c:/Downloads/backup.gz
print(p.with_name('new.txt'))  # c:/Downloads/new.txt

Навигация по дереву директорий с помощью iterdir и glob

glob принимает шаблоны в стиле shell; '' означает эту директорию и все поддиректории рекурсивно, а recursive=True является значением по умолчанию, поэтому glob('/*.py') ищет по всему дереву без явного флага. rglob - это сокращение для glob('**/pattern').

Результаты из iterdir и glob возвращаются в произвольном порядке и могут включать скрытые записи (dotfiles на Unix, файлы со скрытым атрибутом на Windows). Если нужен детерминированный порядок, явно сортируйте результаты. Поведение glob при следовании по символьным ссылкам может варьироваться в зависимости от версии Python, поэтому проверяйте поведение согласно документации pathlib для используемой версии, а не предполагайте фиксированное правило.

from pathlib import Path

data_dir = Path('output')
for p in sorted(data_dir.iterdir()):
    if p.is_file() and p.suffix == '.csv':
        print(p.resolve())

# Recursive search for all Python files
for py in data_dir.rglob('*.py'):
    print(py)

Разрешение путей: absolute, resolve, expanduser и home

absolute() добавляет текущую рабочую директорию без нормализации сегментов '..' или следования по символьным ссылкам. resolve() устраняет компоненты '..' и следует за каждой встреченной символьной ссылкой, возвращая канонический путь. В Python 3.6 был добавлен параметр strict; при strict=True отсутствующий путь или цикл символьных ссылок вызывает OSError, тогда как значение по умолчанию strict=False разрешает путь настолько далеко, насколько возможно, и добавляет остаток.

expanduser() заменяет ведущую тильду или конструкцию тильда-пользователь соответствующей домашней директорией. home() - это метод класса, который напрямую возвращает путь домашней директории текущего пользователя. Оба вызывают RuntimeError, если домашняя директория не может быть определена.

from pathlib import Path

p = Path('docs/../setup.py')
print(p.resolve())          # /home/user/project/setup.py

q = Path('~/notes.txt')
print(q.expanduser())       # /home/user/notes.txt

print(Path.home())          # /home/user

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

Свойство drive возвращает букву диска Windows или строку общего ресурса UNC и всегда пусто на POSIX. root возвращает ведущий слэш или обратный слэш. parts разбивает путь на кортеж компонентов, группируя диск и корень в одну запись на Windows.

PureWindowsPath игнорирует регистр при сравнении равенства и порядка, поэтому PureWindowsPath('FOO') равно PureWindowsPath('foo'). PurePosixPath чувствителен к регистру. Это различие важно при создании множеств или словарей путей, которые должны вести себя согласованно на разных платформах.

from pathlib import PureWindowsPath, PurePosixPath

w = PureWindowsPath('C:/Users/alice/docs')
print(w.parts)   # ('C:\\', 'Users', 'alice', 'docs')
print(w.drive)   # 'c:'
print(w.root)    # '\\'

print(PureWindowsPath('FOO') == PureWindowsPath('foo'))  # True
print(PurePosixPath('FOO') == PurePosixPath('foo'))      # False

Обработка ошибок пути: OSError, UnsupportedOperation и ограничения платформы

Методы конкретных путей, взаимодействующие с файловой системой, вызывают OSError (или подклассы, такие как FileNotFoundError, PermissionError), когда базовый системный вызов завершается неудачей. resolve(strict=True) вызывает OSError для несуществующих путей или циклов символьных ссылок. Начиная с Python 3.13, PosixPath вызывает UnsupportedOperation при инстанцировании на Windows, а WindowsPath вызывает его на не-Windows платформах. Ранее эти случаи вызывали NotImplementedError.

UnsupportedOperation наследуется от NotImplementedError, поэтому перехват NotImplementedError также поймает его, но явная обработка понятнее. При написании кода, который должен работать на обеих платформах, предпочитайте Path вместо PosixPath или WindowsPath, чтобы избежать случайного создания неправильного варианта.

from pathlib import Path

try:
    Path('/nonexistent').resolve(strict=True)
except OSError as exc:
    print(f'Resolution failed: {exc}')

# On Python 3.13+, this raises UnsupportedOperation on Linux:
# from pathlib import WindowsPath
# WindowsPath('C:/')

Интеграция объектов pathlib с функциями модуля os

PurePath реализует os.PathLike начиная с Python 3.6, поэтому любой объект pathlib можно передать напрямую в os.listdir, os.stat, os.remove, os.symlink и аналогичные функции без конвертации. Это позволяет сочетать удобство pathlib с операциями уровня os, для которых нет эквивалента в pathlib.

os.name возвращает 'posix' или 'nt' и является стандартным способом ветвления по платформе, когда pathlib сам по себе не предоставляет достаточно информации, например, при проверке того, требует ли os.symlink повышенных привилегий на Windows или поддерживает ли функция параметр dir_fd.

import os
from pathlib import Path

p = Path('/tmp/example')
# pathlib object works directly with os functions
os.makedirs(p, exist_ok=True)
os.remove(p / 'old.txt')

if os.name == 'nt':
    print('Windows: symlinks need Developer Mode')
else:
    print('Unix: symlinks available without elevation')