کتابخانه pathlib در پایتون — راهنمای جامع

pathlib یکی از کتابخانه‌های استاندارد پایتون است که از نسخه 3.4 معرفی شد و به شکل شی‌گرا با مسیرهای فایل و دایرکتوری‌ها کار می‌کند. این ماژول خوانایی کد را بالا می‌برد و جایگزین روش‌های قدیمی مبتنی بر os.path می‌شود. در این مقاله به مفاهیم کلیدی، متدهای پرکاربرد، مثال‌های عملی و نکات پیشرفته می‌پردازیم.

چرا pathlib؟

• خوانایی بهتر: کار با مسیرها به‌صورت اشیاء Path به مراتب واضح‌تر است.
• تطبیق‌پذیری با سیستم‌عامل: کلاس‌های PurePath، PurePosixPath و PureWindowsPath برای کار بدون اجرا روی سیستم خاص مفیدند.
• API کامل: خواندن و نوشتن فایل، پیمایش دایرکتوری، الگوهای glob و عملیات متداول فایلی را پوشش می‌دهد.

شروع سریع — ایجاد و ترکیب مسیرها

from pathlib import Path

p = Path('/home/user') / 'projects' / 'demo.txt'
print(p)

در این مثال، عملگر / برای ترکیب اجزای مسیر استفاده می‌شود که خواناتر از os.path.join است. خروجی یک شیء Path خواهد بود (مثلاً /home/user/projects/demo.txt).

بررسی وجود و نوع مسیر

p = Path('example.txt')
if p.exists():
    if p.is_file():
        print('It is a file')
    elif p.is_dir():
        print('It is a directory')
else:
    print('Path does not exist')

متدهای exists(), is_file() و is_dir() کمک می‌کنند تا نوع و وجود مسیر را بررسی کنید. این متدها با اشاره به سیستم‌فایل کار می‌کنند.

خواندن و نوشتن متن

p = Path('notes.txt')
p.write_text('سلام؛ این یک نمونه استn')
content = p.read_text()
print(content)

write_text متنی را در مسیر نوشته و read_text آن را برمی‌گرداند. این متدها برای فایل‌های کوچک و ساده مناسبند و به‌صورت پیش‌فرض از انکدینگ UTF-8 استفاده می‌کنند.

باز کردن فایل با شی Path

with Path('data.csv').open('r', encoding='utf-8') as f:
    for line in f:
        print(line.strip())

Path.open همانند built-in open عمل می‌کند ولی با نوشتن کمتر کد و استفاده از اشیاء Path یکپارچگی بهتری با باقی APIهای pathlib فراهم می‌آورد.

نکات مربوط به امنیت و نوشتن اتمیک (بهبود)

from pathlib import Path
import tempfile

def atomic_write(path: Path, data: str, encoding='utf-8'):
    path = Path(path)
    dirpath = path.parent
    with tempfile.NamedTemporaryFile('w', dir=str(dirpath), delete=False, encoding=encoding) as tf:
        tf.write(data)
        tempname = tf.name
    Path(tempname).replace(path)

این تابع فایل را ابتدا در یک فایل موقت همان دایرکتوری می‌نویسد و سپس با replace جایگزین می‌کند تا از نوشتن ناقص جلوگیری شود. این روش نسبت به write_text امن‌تر است، مخصوصاً در زمان‌های قطع برق یا خطاهای نوشتن.

جستجو و الگوها (glob و rglob)

p = Path('.')
for pyfile in p.rglob('*.py'):
    print(pyfile)

rglob به‌صورت بازگشتی درخت دایرکتوری را جستجو می‌کند و فایل‌های منطبق با الگو را برمی‌گرداند. glob مشابه است اما غیر بازگشتی.

کلاس‌های PurePath و تفاوت‌ها

PurePath و مشتقاتش برای کار با مسیرها به‌صورت صرفاً متنی مفیدند (بدون دسترسی به سیستم‌فایل). مثلاً زمانی که می‌خواهید مسیرها را پردازش یا نرمالایز کنید اما نیازی به exist یا read ندارید.

from pathlib import PurePosixPath, PureWindowsPath
p1 = PurePosixPath('/home/user/docs')
p2 = PureWindowsPath('C:\Users\User\docs')
print(p1, p2)

این کلاس‌ها برای تولید مسیرهای مخصوص هر سیستم‌عامل و پردازش رشته‌ای کاربرد دارند و با متدهای سیستمی تداخل نمی‌کنند.

تبدیل به رشته و پلتفرم‌های متفاوت

p = Path('dir') / 'file.txt'
s1 = str(p)         # نمایش مناسب برای سیستم‌عامل فعلی
s2 = p.as_posix()   # نمایش با اسلش بین‌المللی '/'

as_posix زمانی مفید است که بخواهید مسیر را در فرمت POSIX (مثلاً برای URL یا سیستم‌های یونیکس) دریافت کنید. تبدیل به str برای ارسال به APIهای قدیمی یا کتابخانه‌هایی که Path را نمی‌پذیرند لازم است.

عملیات تغییر نام، حذف و کپی

p = Path('old.txt')
p.replace('new.txt')   # تغییر نام/جابجایی
p.unlink()             # حذف فایل

replace برای جابجایی فایل استفاده می‌شود و در صورت وجود مقصد آن را بازنویسی می‌کند. unlink فایل را حذف می‌کند. برای حذف دایرکتوری از rmdir یا shutil.rmtree استفاده کنید.

مثال‌های واقعی و موارد کاربردی

• اسکریپت‌های پردازش داده: خواندن چند فایل با rglob، استخراج متادیتا و نوشتن خروجی.
• ابزارهای CLI: ساخت مسیرهای خروجی بر اساس کاربر و تاریخ با Path.home() و mkdir.
• کار با مسیرهای پلتفرم-متقابل: استفاده از PurePath برای تولید مسیرهایی که در سیستم‌های دیگر مصرف می‌شوند.

جدول مرجع سریع متدهای مهم

نکات پیشرفته و بهترین شیوه‌ها

• هنگام کار با فایل‌های باینری از open(mode=’rb’/’wb’) یا read_bytes()/write_bytes() استفاده کنید.
• برای چندپلتفرم بودن اسکریپت از Path.home() و Path.expanduser(‘~’) برای مسیرهای کاربر استفاده کنید.
• از PurePath وقتی نیاز به عملیات متنی روی مسیرها دارید اما نمی‌خواهید وارد I/O شوید.
• برای عملیات‌های حجیم روی درخت دایرکتوری از itertools و generatorها در ترکیب با rglob استفاده کنید تا حافظه کمتر مصرف شود.

جمع‌بندی

pathlib به عنوان API استاندارد و شی‌گرا برای کار با مسیرها، توسعه‌دهندگان پایتون را از پیچیدگی‌های os.path خلاص کرده و کدی خواناتر، قابل‌نگهداری‌تر و امن‌تر فراهم می‌آورد. یاد گرفتن متدهای کلیدی و استفاده از الگوهای درست (مانند نوشتن اتمیک) به شما کمک می‌کند تا ابزارها و اسکریپت‌های مطمئن‌تر و قابل‌انتقال‌تری بنویسید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال