pathlib --- مسیرهای شیء‌گرای سامانه فایل‌بندی

اضافه شده در نسخه‌ی 3.4.

کد منبع: Lib/pathlib/

---

این ماژول کلاس‌هایی را ارائه می‌دهد که مسیرهای سامانه فایل‌بندی را با معناشناسی مناسب برای سیستم‌عامل‌های مختلف بازنمایی می‌کنند. کلاس‌های مسیر بین مسیرهای خالص، که عملیات کاملاً محاسباتی بدون ورودی/خروجی را فراهم می‌کنند، و مسیرهای ملموس، که از مسیرهای خالص ارث می‌برند اما عملیات ورودی/خروجی را نیز فراهم می‌کنند، تقسیم می‌شوند.

اگر تاکنون از این ماژول استفاده نکرده‌اید یا صرفاً اطمینان ندارید کدام کلاس برای کار شما مناسب است، Path به احتمال زیاد همان چیزی است که به آن نیاز دارید. این کلاس یک مسیر مشخص را برای سکویی که کد روی آن اجرا می‌شود، نمونه‌سازی می‌کند.

مسیرهای خالص در برخی موارد خاص به کار می‌آیند؛ برای مثال:

1. اگر می‌خواهید مسیرهای ویندوزی را روی یک ماشین یونیکسی دستکاری کنید (یا برعکس). هنگام اجرا در یونیکس، شما نمی‌توانید از WindowsPath نمونه‌سازی کنید، اما می‌توانید از PureWindowsPath نمونه‌سازی کنید.

2. شما می‌خواهید مطمئن شوید که کد شما فقط مسیرها را دستکاری می‌کند، بدون اینکه واقعاً به سیستم‌عامل دسترسی داشته باشد. در این حالت، نمونه‌سازی یکی از کلاس‌های خالص می‌تواند مفید باشد، زیرا این کلاس‌ها به‌سادگی هیچ عملیاتی برای دسترسی به سیستم‌عامل ندارند.

همچنین ملاحظه نمائید

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

فهرست پرونده‌های منبع پایتون در این درخت پوشه:

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

استثناها

exception pathlib.UnsupportedOperation

استثنایی که از NotImplementedError ارث‌بری می‌کند و هنگامی پرتاب می‌شود که یک عملیات پشتیبانی‌نشده روی یک شیء مسیر فراخوانی شود.

اضافه شده در نسخه‌ی 3.13.

مسیرهای خالص

اشیای مسیر خالص، عملیات مدیریت مسیر را فراهم می‌کنند که در واقع به یک سیستم پرونده دسترسی ندارند. سه روش برای دسترسی به این کلاس‌ها وجود دارد که به آن‌ها گونه‌ها (flavours) نیز می‌گوییم:

class pathlib.PurePath(*pathsegments)

یک کلاس عام که نشان‌دهنده‌ی سبک مسیر سیستم است (نمونه‌سازی از آن یک PurePosixPath یا PureWindowsPath ایجاد می‌کند):

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

هر عنصر از pathsegments می‌تواند یا رشته‌ای باشد که یک قطعه مسیر را نشان می‌دهد، یا شیء‌ای که رابط os.PathLike را پیاده‌سازی می‌کند و متد __fspath__() آن یک رشته برمی‌گرداند، مانند یک شیء مسیر دیگر:

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

در ویندوز، هنگام مواجهه با یک بخش مسیر نسبی ریشه‌دار (برای نمونه، r'\foo')، درایو بازنشانی نمی‌شود:

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

اسلش‌های اضافی و نقطه‌های تکی جمع می‌شوند، اما نقطه‌های دوتایی ('..') و دو اسلش آغازین ('//') جمع نمی‌شوند، زیرا این کار معنای مسیر را به دلایل مختلف (مانند پیوندهای نمادین، مسیرهای UNC) تغییر می‌دهد:

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> 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 است، مسیرهای سیستم‌پرونده‌ای غیرویندوزی را نشان می‌دهد:

>>> PurePosixPath('/etc/hosts')
PurePosixPath('/etc/hosts')

pathsegments مشابه PurePath مشخص می‌شود.

class pathlib.PureWindowsPath(*pathsegments)

این گونه مسیر، زیرکلاسی از PurePath، مسیرهای سامانه فایل‌بندی ویندوز را نشان می‌دهد، از جمله UNC paths:

>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments مشابه PurePath مشخص می‌شود.

صرف‌نظر از سیستمی که روی آن اجرا می‌شوید، می‌توانید همه این کلاس‌ها را نمونه‌سازی کنید، زیرا آن‌ها هیچ عملیاتی که فراخوانی‌های سیستمی انجام دهد ارائه نمی‌کنند.

ویژگی‌های عمومی

مسیرها تغییرناپذیر و هش‌پذیر هستند. مسیرهای هم‌نوع قابل مقایسه و مرتب‌سازی هستند. این ویژگی‌ها معناشناسی تبدیل حالت حروف (case-folding) آن نوع را رعایت می‌کنند:

>>> 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(). اگر آرگومان یک مسیر مطلق باشد، مسیر قبلی نادیده گرفته می‌شود. در ویندوز، وقتی آرگومان یک مسیر نسبی ریشه‌دار باشد، درایو بازنشانی نمی‌شود (مثلاً r'\foo'):

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')
>>> p / '/an_absolute_path'
PurePosixPath('/an_absolute_path')
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

می‌توان از یک شیء مسیر در هر جایی که شیءای پیاده‌سازی‌کننده‌ی os.PathLike پذیرفته می‌شود، استفاده کرد:

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

نمایش رشته‌ای یک مسیر، خود مسیر خام سامانه فایل‌بندی است (به شکل بومی، مثلاً با بک‌اسلش‌ها در ویندوز) که می‌توانید آن را به هر تابعی که مسیر پرونده را به‌عنوان یک رشته دریافت می‌کند، بدهید:

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

به‌طور مشابه، فراخوانی bytes روی یک مسیر، مسیر خام سامانه فایل‌بندی را به‌صورت یک شیء بایت که توسط os.fsencode() کدگذاری شده است، برمی‌گرداند:

>>> bytes(p)
b'/etc'

توجه

فراخوانی bytes فقط در یونیکس توصیه می‌شود. در ویندوز، فرم یونیکد، نمایش کانونیکال مسیرهای سامانه فایل‌بندی است.

دسترسی به بخش‌های منفرد

برای دسترسی به تک‌تک «بخش‌های» یک مسیر (کامپوننت‌ها)، از ویژگی زیر استفاده کنید:

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.parser

پیاده‌سازی ماژول os.path که برای تجزیه و الحاق مسیر در سطح پایین استفاده می‌شود: یا posixpath یا ntpath.

اضافه شده در نسخه‌ی 3.13.

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

اگر مسیر با بیش از دو اسلش متوالی شروع شود، PurePosixPath آن‌ها را ادغام می‌کند:

>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'

توجه

این رفتار مطابق با The Open Group Base Specifications Issue 6، بند 4.11 Pathname Resolution است:

«مسیری که با دو اسلش پشت‌سرهم آغاز می‌شود ممکن است به‌صورت تعریف‌شده توسط پیاده‌سازی تفسیر شود، هرچند بیش از دو اسلش ابتدایی باید به‌عنوان یک اسلش واحد در نظر گرفته شوند»

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

تغییر یافته در نسخه‌ی 3.10: دنباله‌ی والدین اکنون از اسلایس‌ها و مقادیر منفی اندیس پشتیبانی می‌کند.

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

این معمولاً پسوند پرونده نامیده می‌شود.

تغییر یافته در نسخه‌ی 3.14: یک نقطه («.») یک پسوند معتبر در نظر گرفته می‌شود.

PurePath.suffixes

فهرستی از پسوندهای مسیر، که اغلب پسوندهای پرونده نامیده می‌شوند:

>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]

تغییر یافته در نسخه‌ی 3.14: یک نقطه («.») یک پسوند معتبر در نظر گرفته می‌شود.

PurePath.stem

آخرین کامپوننت مسیر، بدون پسوند آن:

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

تغییر یافته در نسخه‌ی 3.14: یک نقطه («.») یک پسوند معتبر در نظر گرفته می‌شود.

PurePath.as_posix()

نمایش رشته‌ای از مسیر را با اسلش‌های رو به جلو (/) برمی‌گرداند:

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

PurePath.is_absolute()

بازگشت می‌دهد که آیا مسیر مطلق است یا نه. مسیر در صورتی مطلق در نظر گرفته می‌شود که هم دارای ریشه و هم (در صورتی که نوع (flavour) اجازه دهد) دارای درایو باشد:

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

برمی‌گرداند که آیا این مسیر نسبت به مسیر other نسبی است یا خیر.

>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False

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

>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False

اضافه شده در نسخه‌ی 3.9.

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.14 حذف شده است: ارسال آرگومان‌های اضافی منسوخ شده است؛ در صورت ارائه، به other پیوست می‌شوند.

PurePath.is_reserved()

در PureWindowsPath، اگر مسیر در ویندوز رزروشده محسوب شود، True و در غیر این صورت False برمی‌گرداند. در PurePosixPath، همیشه False برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.13: نام مسیرهای ویندوزی که شامل دونقطه باشند، یا با نقطه یا فاصله پایان یابند، رزروشده محسوب می‌شوند. مسیرهای UNC ممکن است رزروشده باشند.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: این متد منسوخ‌شده است؛ برای تشخیص مسیرهای رزروشده در ویندوز از os.path.isreserved() استفاده کنید.

PurePath.joinpath(*pathsegments)

فراخوانی این متد معادل ترکیب مسیر با هر یک از pathsegments داده‌شده به‌نوبت است:

>>> 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.full_match(pattern, *, case_sensitive=None)

این مسیر را با الگوی به‌سبک glob ارائه‌شده تطبیق می‌دهد. اگر تطبیق موفقیت‌آمیز باشد، True و در غیر این صورت False برمی‌گرداند. برای مثال:

>>> PurePath('a/b.py').full_match('a/*.py')
True
>>> PurePath('a/b.py').full_match('*.py')
False
>>> PurePath('/a/b/c.py').full_match('/a/**')
True
>>> PurePath('/a/b/c.py').full_match('**/*.py')
True

همچنین ملاحظه نمائید

مستندات زبان الگو.

مانند سایر متدها، حساسیت به بزرگی و کوچکی حروف از پیش‌فرض‌های سکو پیروی می‌کند:

>>> PurePosixPath('b.py').full_match('*.PY')
False
>>> PureWindowsPath('b.py').full_match('*.PY')
True

برای لغو این رفتار، case_sensitive را روی True یا False تنظیم کنید.

اضافه شده در نسخه‌ی 3.13.

PurePath.match(pattern, *, case_sensitive=None)

این مسیر را با الگوی غیربازگشتی به‌سبک glob ارائه‌شده تطبیق می‌دهد. اگر تطبیق موفقیت‌آمیز باشد، True و در غیر این صورت False برمی‌گرداند.

این متد مشابه full_match() است، اما الگوهای خالی مجاز نیستند (ValueError پرتاب می‌شود)، وایلدکارد بازگشتی "**" پشتیبانی نمی‌شود (مانند "*" غیربازگشتی عمل می‌کند)، و اگر یک الگوی نسبی ارائه شود، تطبیق از سمت راست انجام می‌شود:

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

تغییر یافته در نسخه‌ی 3.12: پارامتر pattern یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.12: پارامتر case_sensitive افزوده شد.

PurePath.relative_to(other, walk_up=False)

نسخه‌ای از این مسیر را نسبت به مسیری که 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 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other is absolute.

وقتی walk_up نادرست است (پیش‌فرض)، مسیر باید با other شروع شود. وقتی آرگومان درست باشد، ممکن است ورودی‌های .. برای تشکیل مسیر نسبی افزوده شوند. در تمام موارد دیگر، مانند مسیرهایی که به درایوهای مختلف ارجاع می‌دهند، 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 تأثیر بگذارد، زیرا فرض می‌کند هیچ پیوند نمادینی در مسیر وجود ندارد؛ در صورت نیاز، ابتدا resolve() را فراخوانی کنید تا پیوندهای نمادین حل شوند.

تغییر یافته در نسخه‌ی 3.12: پارامتر walk_up افزوده شد (رفتار قدیمی همان walk_up=False است).

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.14 حذف شده است: ارسال آرگومان‌های جایگاهی اضافی منسوخ شده است؛ در صورت ارائه، آن‌ها با other ادغام می‌شوند.

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

یک مسیر جدید با stem تغییریافته برمی‌گرداند. اگر مسیر اصلی نام نداشته باشد، 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

اضافه شده در نسخه‌ی 3.9.

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

تغییر یافته در نسخه‌ی 3.14: یک نقطه (.) یک پسوند معتبر در نظر گرفته می‌شود. در نسخه‌های پیشین، در صورت ارائه یک نقطه، ValueError پرتاب می‌شد.

PurePath.with_segments(*pathsegments)

با ترکیب pathsegments داده‌شده، یک شیء مسیر جدید از همان نوع ایجاد می‌کند. این متد هر زمان که یک مسیر مشتق‌شده ایجاد شود، فراخوانی می‌شود؛ مانند مسیرهای مشتق‌شده از parent و 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

اضافه شده در نسخه‌ی 3.12.

مسیرهای عینی

مسیرهای ملموس، زیرکلاس‌هایی از کلاس‌های مسیر خالص هستند. علاوه بر عملیات ارائه‌شده توسط آن کلاس‌ها، متدهایی نیز برای انجام فراخوانی‌های سیستمی روی اشیای مسیر فراهم می‌کنند. سه روش برای نمونه‌سازی مسیرهای ملموس وجود دارد:

class pathlib.Path(*pathsegments)

زیرکلاسی از PurePath، این کلاس مسیرهای عینیِ سبک مسیر سیستم را نشان می‌دهد (نمونه‌سازی از آن، یک PosixPath یا WindowsPath ایجاد می‌کند):

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments مشابه PurePath مشخص می‌شود.

class pathlib.PosixPath(*pathsegments)

این کلاس، زیرکلاسی از Path و PurePosixPath، مسیرهای عینی سیستم‌پرونده‌ای غیرویندوزی را نشان می‌دهد:

>>> PosixPath('/etc/hosts')
PosixPath('/etc/hosts')

pathsegments مشابه PurePath مشخص می‌شود.

تغییر یافته در نسخه‌ی 3.13: در ویندوز UnsupportedOperation را پرتاب می‌کند. در نسخه‌های پیشین، به‌جای آن NotImplementedError پرتاب می‌شد.

class pathlib.WindowsPath(*pathsegments)

این کلاس، زیرکلاسی از Path و PureWindowsPath است و مسیرهای عینی سامانه فایل‌بندی‌ای ویندوز را نشان می‌دهد:

>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')

pathsegments مشابه PurePath مشخص می‌شود.

تغییر یافته در نسخه‌ی 3.13: در سکوهای غیر ویندوزی، UnsupportedOperation را پرتاب می‌کند. در نسخه‌های پیشین، به جای آن NotImplementedError پرتاب می‌شد.

شما فقط می‌توانید نوع کلاسی را نمونه‌سازی کنید که با سیستم شما مطابقت دارد (اجازه دادن به فراخوانی‌های سیستمی در انواع مسیر ناسازگار ممکن است به اشکال‌ها یا شکست‌ها در برنامه شما منجر شود):

>>> 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__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system

برخی متدهای مسیر عینی ممکن است در صورت شکست یک فراخوانی سیستمی، استثنای OSError را پرتاب کنند (برای مثال به این دلیل که مسیر وجود ندارد).

تجزیه و تولید URIها

می‌توان اشیای مسیر عینی را از URIهای 'file' منطبق بر RFC 8089 ایجاد کرد و آن‌ها را به‌صورت URIهای 'file' بازنمایی کرد.

توجه

URIهای پرونده بین ماشین‌هایی با کدگذاری‌های سامانه فایل‌بندی متفاوت، قابل‌حمل نیستند.

classmethod Path.from_uri(uri)

یک شیء مسیر جدید را از تجزیه‌ی یک URI از نوع 'file' برمی‌گرداند. برای مثال:

>>> p = Path.from_uri('file:///etc/hosts')
PosixPath('/etc/hosts')

در ویندوز، می‌توان مسیرهای دستگاه DOS و مسیرهای UNC را از URIها تجزیه کرد:

>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file://server/share')
WindowsPath('//server/share')

چندین شکل جایگزین پشتیبانی می‌شود:

>>> p = Path.from_uri('file:////server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file://///server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file:c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file:/c|/windows')
WindowsPath('c:/windows')

اگر URI با file: شروع نشود، یا مسیر تجزیه‌شده مطلق نباشد، ValueError پرتاب می‌شود.

اضافه شده در نسخه‌ی 3.13.

تغییر یافته در نسخه‌ی 3.14: اگر بخش authority در URL با نام میزبان محلی مطابقت داشته باشد، حذف می‌شود. در غیر این صورت، اگر authority خالی یا localhost نباشد، در ویندوز یک مسیر UNC برگردانده می‌شود (مانند قبل)، و در سایر پلتفرم‌ها یک ValueError پرتاب می‌شود.

Path.as_uri()

مسیر را به‌عنوان یک URI از نوع 'file' نمایش می‌دهد. اگر مسیر مطلق نباشد، ValueError پرتاب می‌شود.

>>> p = PosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = WindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

منسوخ شده از نسخه‌ی 3.14, در نسخه‌ی 3.19 حذف خواهد شد: فراخوانی این متد از PurePath به‌جای Path امکان‌پذیر است، اما منسوخ است. استفاده‌ی این متد از os.fsencode() آن را کاملاً ناخالص می‌کند.

گسترش و حل مسیرها

classmethod Path.home()

یک شیء مسیر جدید را برمی‌گرداند که نشان‌دهنده‌ی پوشه‌ی خانه‌ی کاربر است (همان‌طور که توسط os.path.expanduser() با ساختار ~ برگردانده می‌شود). اگر پوشه‌ی خانه قابل تعیین نباشد، RuntimeError پرتاب می‌شود.

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

اضافه شده در نسخه‌ی 3.5.

Path.expanduser()

مسیر جدیدی با ساختارهای بسط‌یافته‌ی ~ و ~user برمی‌گرداند، همان‌طور که توسط os.path.expanduser() برگردانده می‌شود. اگر پوشه‌ی خانه قابل تعیین نباشد، RuntimeError پرتاب می‌شود.

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

اضافه شده در نسخه‌ی 3.5.

classmethod Path.cwd()

یک شیء مسیر جدید را برمی‌گرداند که نشان‌دهنده‌ی پوشه جاری است (همان‌طور که os.getcwd() آن را برمی‌گرداند):

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

Path.absolute()

مسیر را بدون عادی‌سازی یا حل پیوندهای نمادین، مطلق می‌کند. یک شیء مسیر جدید بازمی‌گرداند:

>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')

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 باشد، OSError پرتاب می‌شود. اگر strict برابر False باشد، مسیر تا حد ممکن حل می‌شود و هر بخش باقی‌مانده بدون بررسی وجود آن، افزوده می‌شود.

تغییر یافته در نسخه‌ی 3.6: پارامتر strict افزوده شد (رفتار پیش از 3.6 strict است).

تغییر یافته در نسخه‌ی 3.13: با حلقه‌های پیوند نمادین مانند سایر خطاها برخورد می‌شود: در حالت سخت‌گیرانه OSError پرتاب می‌شود و در حالت غیرسخت‌گیرانه هیچ استثنایی پرتاب نمی‌شود. در نسخه‌های پیشین، RuntimeError صرف‌نظر از مقدار strict پرتاب می‌شد.

Path.readlink()

مسیری را که پیوند نمادین به آن اشاره می‌کند برمی‌گرداند (همان‌طور که توسط os.readlink() برگردانده می‌شود):

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')

اضافه شده در نسخه‌ی 3.9.

تغییر یافته در نسخه‌ی 3.13: اگر os.readlink() در دسترس نباشد، UnsupportedOperation پرتاب می‌شود. در نسخه‌های پیشین، NotImplementedError پرتاب می‌شد.

پرس‌وجوی نوع و وضعیت پرونده

تغییر یافته در نسخه‌ی 3.8: exists()، is_dir()، is_file()، is_mount()، is_symlink()، is_block_device()، is_char_device()، is_fifo()، is_socket() اکنون برای مسیرهایی که حاوی نویسه‌های غیرقابل بازنمایی در سطح سیستم‌عامل هستند، به‌جای پرتاب یک استثنا False برمی‌گردانند.

تغییر یافته در نسخه‌ی 3.14: متدهای ذکرشده در بالا اکنون به جای پرتاب هیچ‌گونه استثنای OSError از سوی سیستم‌عامل، False برمی‌گردانند. در نسخه‌های پیشین، برخی از انواع استثنای OSError پرتاب می‌شدند و برخی دیگر سرکوب می‌شدند. رفتار جدید با os.path.exists()، os.path.isdir() و غیره سازگار است. برای بازیابی وضعیت پرونده بدون سرکوب استثناها، از stat() استفاده کنید.

Path.stat(*, follow_symlinks=True)

یک شیء os.stat_result حاوی اطلاعاتی درباره این مسیر، مانند os.stat() برمی‌گرداند. نتیجه در هر فراخوانی این متد جستجو می‌شود.

این متد معمولاً پیوندهای نمادین را دنبال می‌کند؛ برای گرفتن وضعیت (stat) یک پیوند نمادین، آرگومان follow_symlinks=False را اضافه کنید، یا از lstat() استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.10: پارامتر follow_symlinks افزوده شد.

Path.lstat()

مانند Path.stat()، اما اگر مسیر به یک پیوند نمادین اشاره کند، اطلاعات پیوند نمادین را به‌جای اطلاعات هدف آن برمی‌گرداند.

Path.exists(*, follow_symlinks=True)

اگر مسیر به یک پرونده یا پوشه‌ی موجود اشاره کند، True را برمی‌گرداند. اگر مسیر نامعتبر، دسترس‌ناپذیر یا مفقود باشد، False برگردانده می‌شود. برای تمایز بین این حالات از Path.stat() استفاده کنید.

این متد معمولاً پیوندهای نمادین را دنبال می‌کند؛ برای بررسی وجود یک پیوند نمادین، آرگومان follow_symlinks=False را اضافه کنید.

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

تغییر یافته در نسخه‌ی 3.12: پارامتر follow_symlinks افزوده شد.

Path.is_file(*, follow_symlinks=True)

اگر مسیر به یک پرونده معمولی اشاره کند، True برگردانده می‌شود. اگر مسیر نامعتبر باشد، در دسترس نباشد یا وجود نداشته باشد، یا به چیزی غیر از یک پرونده معمولی اشاره کند، False برگردانده می‌شود. برای تمایز بین این حالت‌ها از Path.stat() استفاده کنید.

این متد معمولاً پیوندهای نمادین را دنبال می‌کند؛ برای مستثنی کردن پیوندهای نمادین، آرگومان follow_symlinks=False را اضافه کنید.

تغییر یافته در نسخه‌ی 3.13: پارامتر follow_symlinks افزوده شد.

Path.is_dir(*, follow_symlinks=True)

اگر مسیر به یک پوشه اشاره کند، True برگردانده می‌شود. اگر مسیر نامعتبر، دسترسی‌ناپذیر یا وجود نداشته باشد، یا به چیزی غیر از یک پوشه اشاره کند، False برگردانده می‌شود. برای تمایز بین این موارد از Path.stat() استفاده کنید.

این متد معمولاً پیوندهای نمادین را دنبال می‌کند؛ برای مستثنی کردن پیوندهای نمادین به پوشه‌ها، آرگومان follow_symlinks=False را اضافه کنید.

تغییر یافته در نسخه‌ی 3.13: پارامتر follow_symlinks افزوده شد.

Path.is_symlink()

اگر مسیر به یک پیوند نمادین اشاره داشته باشد، True برگردانده می‌شود، حتی اگر آن پیوند نمادین شکسته باشد. اگر مسیر نامعتبر، غیرقابل‌دسترسی یا مفقود باشد، یا به چیزی غیر از یک پیوند نمادین اشاره داشته باشد، False برگردانده می‌شود. برای تمایز بین این موارد از Path.stat() استفاده کنید.

Path.is_junction()

اگر مسیر به یک اتصال (junction) اشاره کند، True را برمی‌گرداند و برای هر نوع پرونده دیگری، False را برمی‌گرداند. در حال حاضر تنها ویندوز از اتصال‌ها (junction) پشتیبانی می‌کند.

اضافه شده در نسخه‌ی 3.12.

Path.is_mount()

اگر مسیر یک نقطه سوارکردن (mount point) <mount point> باشد، True را برمی‌گرداند: نقطه‌ای در یک سامانه فایل‌بندی که سامانه فایل‌بندی متفاوتی در آن سوار شده است. در POSIX، تابع بررسی می‌کند که آیا والد path، یعنی path/..، روی دستگاه متفاوتی نسبت به path قرار دارد، یا آیا path/.. و path به همان آی‌نود (i-node) روی همان دستگاه اشاره می‌کنند --- این باید نقاط سوارکردن را در همه‌ی انواع Unix و POSIX تشخیص دهد. در Windows، یک نقطه سوارکردن به‌عنوان ریشه‌ی حرف درایو (مثلاً c:\)، اشتراک UNC (مثلاً \\server\share)، یا پوشه‌ی یک سامانه فایل‌بندی سوارشده در نظر گرفته می‌شود.

اضافه شده در نسخه‌ی 3.7.

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از ویندوز افزوده شد.

Path.is_socket()

اگر مسیر به یک سوکت یونیکس (Unix socket) اشاره کند، True را برمی‌گرداند. اگر مسیر نامعتبر یا غیرقابل‌دسترسی باشد، یا وجود نداشته باشد، یا به چیزی غیر از یک سوکت یونیکس اشاره کند، False را برمی‌گرداند. برای تمایز بین این موارد از Path.stat() استفاده کنید.

Path.is_fifo()

اگر مسیر به یک FIFO اشاره کند، True برگردانده می‌شود. اگر مسیر نامعتبر، دسترسی‌ناپذیر یا مفقود باشد، یا به چیزی غیر از FIFO اشاره کند، False برگردانده می‌شود. برای تمایز بین این حالت‌ها از Path.stat() استفاده کنید.

Path.is_block_device()

اگر مسیر به یک دستگاه بلوکی اشاره کند، True برگردانده می‌شود. اگر مسیر نامعتبر یا غیرقابل‌دسترسی باشد یا وجود نداشته باشد، یا به چیزی جز یک دستگاه بلوکی اشاره کند، False برگردانده می‌شود. برای تمایز بین این موارد از Path.stat() استفاده کنید.

Path.is_char_device()

اگر مسیر به یک دستگاه نویسه‌ای اشاره کند، True برمی‌گرداند. اگر مسیر نامعتبر، غیرقابل‌دسترسی یا وجود نداشته باشد، یا به چیزی جز یک دستگاه نویسه‌ای اشاره کند، False برگردانده می‌شود. برای تمایز بین این حالت‌ها از Path.stat() استفاده کنید.

Path.samefile(other_path)

برمی‌گرداند که آیا این مسیر به همان پرونده‌ای اشاره می‌کند که 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.info

یک شیء PathInfo که از پرس‌وجوی اطلاعات نوع پرونده پشتیبانی می‌کند. این شیء متدهایی را ارائه می‌دهد که نتایج خود را در نهانگاه ذخیره می‌کنند، که می‌تواند به کاهش تعداد فراخوانی‌های سیستمی مورد نیاز هنگام تعیین نوع پرونده کمک کند. برای مثال:

>>> p = Path('src')
>>> if p.info.is_symlink():
...     print('symlink')
... elif p.info.is_dir():
...     print('directory')
... elif p.info.exists():
...     print('something else')
... else:
...     print('not found')
...
directory

اگر مسیر از Path.iterdir() ایجاد شده باشد، این ویژگی با اطلاعاتی درباره‌ی نوع پرونده که از پویش پوشه‌ی والد به‌دست آمده است، مقداردهی اولیه می‌شود. صرفاً دسترسی به Path.info هیچ پرس‌وجویی در سامانه فایل‌بندی انجام نمی‌دهد.

برای دریافت اطلاعات به‌روز، بهتر است به‌جای متدهای این ویژگی، Path.is_dir()، is_file() و is_symlink() را فراخوانی کنید. راهی برای بازنشانی نهانگاه وجود ندارد؛ در عوض می‌توانید از طریق p = Path(p) یک شیء مسیر جدید با نهانگاه اطلاعات خالی ایجاد کنید.

اضافه شده در نسخه‌ی 3.14.

خواندن و نوشتن پرونده‌ها

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.read_text(encoding=None, errors=None, newline=None)

محتوای کدگشایی‌شده‌ی پرونده اشاره‌شده را به‌صورت یک رشته برگردانید:

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

پرونده باز می‌شود و سپس بسته می‌شود. پارامترهای اختیاری همان معنای موجود در open() را دارند.

اضافه شده در نسخه‌ی 3.5.

تغییر یافته در نسخه‌ی 3.13: پارامتر newline افزوده شد.

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.write_text(data, encoding=None, errors=None, newline=None)

پرونده اشاره‌شده را در حالت متنی باز کنید، data را در آن بنویسید و پرونده را ببندید:

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

پرونده موجود با نام مشابه بازنویسی می‌شود. پارامترهای اختیاری همان معنای موجود در open() را دارند.

اضافه شده در نسخه‌ی 3.5.

تغییر یافته در نسخه‌ی 3.10: پارامتر newline افزوده شد.

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

فرزندان به ترتیب دلخواه برگردانده می‌شوند، و ورودی‌های ویژه '.' و '..' گنجانده نمی‌شوند. اگر پس از ایجاد پیمایش‌گر، پرونده‌ای از پوشه حذف یا به آن اضافه شود، نامشخص است که شیء مسیر برای آن پرونده گنجانده می‌شود یا خیر.

اگر مسیر پوشه نباشد یا به هر شکل دیگری دسترسی‌ناپذیر باشد، OSError پرتاب می‌شود.

Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)

pattern نسبی داده‌شده را در پوشه‌ای که این مسیر آن را نشان می‌دهد، گلوب (glob) می‌کند و همه‌ی پرونده‌های منطبق (از هر نوع) را تولید می‌کند:

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

توجه

مسیرها بدون ترتیب خاصی بازگردانده می‌شوند. اگر به ترتیب خاصی نیاز دارید، نتایج را مرتب کنید.

همچنین ملاحظه نمائید

مستندات زبان الگو.

به‌طور پیش‌فرض، یا زمانی که آرگومان فقط کلیدواژه‌ای case_sensitive روی None تنظیم شده باشد، این متد مسیرها را با استفاده از قواعد مربوط به بزرگی و کوچکی حروفِ خاصِ پلتفرم مطابقت می‌دهد: معمولاً در POSIX حساس به بزرگی و کوچکی حروف، و در Windows غیرحساس به آن است. برای نادیده گرفتن این رفتار، case_sensitive را روی True یا False تنظیم کنید.

به‌طور پیش‌فرض، یا زمانی که آرگومان فقط کلیدواژه‌ای recurse_symlinks روی False تنظیم شده باشد، این متد پیوندهای نمادین را دنبال می‌کند، به‌جز هنگام بسط وایلدکاردها "**". برای دنبال کردن همیشگی پیوندهای نمادین، recurse_symlinks را روی True تنظیم کنید.

توجه

هر استثنای OSError که از پویش سامانه فایل‌بندی پرتاب شود، مهار می‌شود. این شامل PermissionError هنگام دسترسی به پوشه‌های بدون اجازه‌ی خواندن نیز می‌شود.

یک رویداد حسابرسی pathlib.Path.glob را با آرگومان‌های self و pattern پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.12: پارامتر case_sensitive افزوده شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر recurse_symlinks اضافه شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر pattern یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.13: تمام استثناهای OSError که هنگام پویش سامانه فایل‌بندی پرتاب می‌شوند، مهار می‌شوند. در نسخه‌های پیشین، چنین استثناهایی در بسیاری از موارد مهار می‌شدند، اما نه همه.

Path.rglob(pattern, *, case_sensitive=None, recurse_symlinks=False)

الگوی نسبیِ داده‌شده‌ی pattern را به‌صورت بازگشتی گلُب کنید. این کار مانند فراخوانی Path.glob() است که عبارت "**/" به ابتدای pattern افزوده شده باشد.

توجه

مسیرها بدون ترتیب خاصی بازگردانده می‌شوند. اگر به ترتیب خاصی نیاز دارید، نتایج را مرتب کنید.

توجه

هر استثنای OSError که از پویش سامانه فایل‌بندی پرتاب شود، مهار می‌شود. این شامل PermissionError هنگام دسترسی به پوشه‌های بدون اجازه‌ی خواندن نیز می‌شود.

همچنین ملاحظه نمائید

مستندات زبان الگو و Path.glob().

یک رویداد حسابرسی pathlib.Path.rglob را با آرگومان‌های self، pattern پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.12: پارامتر case_sensitive افزوده شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر recurse_symlinks اضافه شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر pattern یک path-like object را می‌پذیرد.

Path.walk(top_down=True, on_error=None, follow_symlinks=False)

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

برای هر پوشه در درخت پوشه‌ای که ریشه‌ی آن self است (شامل self اما بدون '.' و '..')، این متد یک ۳-تایی از (dirpath, dirnames, filenames) تولید می‌کند.

dirpath یک Path به پوشه‌ای است که در حال حاضر پیمایش می‌شود، dirnames فهرستی از رشته‌ها برای نام‌های پوشه‌های فرعی در dirpath (به استثنای '.' و '..') است، و filenames فهرستی از رشته‌ها برای نام‌های پرونده‌های غیرپوشه‌ای در dirpath است. برای به دست آوردن یک مسیر کامل (که با self شروع می‌شود) به یک پرونده یا پوشه در dirpath، از dirpath / name استفاده کنید. اینکه فهرست‌ها مرتب‌شده باشند یا نه، به سامانه فایل‌بندی وابسته است.

اگر آرگومان اختیاری top_down درست باشد (که پیش‌فرض است)، سه‌تایی مربوط به یک پوشه پیش از سه‌تایی‌های مربوط به هر یک از زیرپوشه‌های آن تولید می‌شود (پوشه‌ها به‌صورت بالا به پایین پیمایش می‌شوند). اگر top_down نادرست باشد، سه‌تایی مربوط به یک پوشه پس از سه‌تایی‌های مربوط به همه‌ی زیرپوشه‌های آن تولید می‌شود (پوشه‌ها به‌صورت پایین به بالا پیمایش می‌شوند). صرف‌نظر از مقدار top_down، فهرست زیرپوشه‌ها پیش از آنکه سه‌تایی‌های مربوط به پوشه و زیرپوشه‌های آن پیمایش شوند، بازیابی می‌شود.

وقتی top_down true باشد، فراخوان می‌تواند فهرست dirnames را به‌صورت درجا تغییر دهد (برای مثال، با استفاده از del یا انتساب اسلایسی)، و Path.walk() فقط به زیرپوشه‌هایی که نام آن‌ها در dirnames باقی مانده است، به‌صورت بازگشتی وارد می‌شود. از این کار می‌توان برای هرس جستجو، اعمال ترتیب مشخصی برای بازدید، یا حتی اطلاع دادن به Path.walk() در مورد پوشه‌هایی استفاده کرد که فراخوان پیش از آنکه Path.walk() را دوباره از سر بگیرد، ایجاد یا تغییر نام می‌دهد. تغییر dirnames وقتی top_down false باشد، تأثیری بر رفتار Path.walk() ندارد، زیرا در لحظه‌ای که dirnames به فراخوان تحویل داده می‌شود، پوشه‌های موجود در dirnames از قبل تولید شده‌اند.

به‌طور پیش‌فرض، خطاهای حاصل از os.scandir() نادیده گرفته می‌شوند. اگر آرگومان اختیاری on_error مشخص شده باشد، باید یک شیء فراخوانی‌پذیر باشد؛ این شیء با ۱ آرگومان فراخوانی می‌شود که یک نمونه از OSError است. شیء فراخوانی‌پذیر می‌تواند خطا را مدیریت کند تا پیمایش ادامه یابد یا آن را دوباره پرتاب کند تا پیمایش متوقف شود. توجه داشته باشید که نام پرونده به‌عنوان ویژگی filename شیء استثنا در دسترس است.

به‌طور پیش‌فرض، Path.walk() پیوندهای نمادین را دنبال نمی‌کند و در عوض آن‌ها را به فهرست filenames اضافه می‌کند. follow_symlinks را روی مقدار درست تنظیم کنید تا پیوندهای نمادین حل شوند و متناسب با هدف‌هایشان در dirnames و filenames قرار بگیرند، و در نتیجه پوشه‌هایی که پیوندهای نمادین به آن‌ها اشاره دارند پیمایش شوند (در صورت پشتیبانی).

توجه

توجه داشته باشید که تنظیم follow_symlinks روی true می‌تواند منجر به بازگشت بی‌نهایت شود، اگر پیوندی به پوشه والد خودش اشاره کند. Path.walk() پوشه‌هایی را که از قبل بازدید کرده است پیگیری نمی‌کند.

توجه

Path.walk() فرض می‌کند پوشه‌هایی که پیمایش می‌کند در حین اجرا تغییر داده نمی‌شوند. برای مثال، اگر پوشه‌ای از dirnames با یک پیوند نمادین جایگزین شده باشد و follow_symlinks نادرست باشد، Path.walk() همچنان تلاش می‌کند وارد آن شود. برای جلوگیری از چنین رفتاری، در صورت لزوم پوشه‌ها را از dirnames حذف کنید.

توجه

برخلاف os.walk()، Path.walk() در صورتی که follow_symlinks نادرست باشد، پیوندهای نمادین به پوشه‌ها را در filenames فهرست می‌کند.

این مثال تعداد بایت‌های استفاده‌شده توسط تمام پرونده‌ها در هر پوشه را، در حالی که پوشه‌های __pycache__ نادیده گرفته می‌شوند، نمایش می‌دهد:

from pathlib import Path
for root, dirs, files in Path("cpython/Lib/concurrent").walk(on_error=print):
  print(
      root,
      "consumes",
      sum((root / file).stat().st_size for file in files),
      "bytes in",
      len(files),
      "non-directory files"
  )
  if '__pycache__' in dirs:
        dirs.remove('__pycache__')

مثال بعدی یک پیاده‌سازی ساده از shutil.rmtree() است. پیمایش درخت به‌صورت پایین‌به‌بالا ضروری است، زیرا rmdir() اجازه‌ی حذف یک پوشه را پیش از خالی شدن آن نمی‌دهد:

# Delete everything reachable from the directory "top".
# CAUTION:  This is dangerous! For example, if top == Path('/'),
# it could delete all of your files.
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()

اضافه شده در نسخه‌ی 3.12.

ایجاد پرونده‌ها و پوشه‌ها

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

پرونده‌ای در این مسیر داده‌شده ایجاد می‌کند. اگر mode داده شده باشد، با مقدار umask فرایند ترکیب می‌شود تا حالت پرونده و پرچم‌های دسترسی تعیین شود. اگر پرونده از قبل وجود داشته باشد، هنگامی که exist_ok درست باشد، تابع موفق عمل می‌کند (و زمان تغییر آن به زمان فعلی به‌روزرسانی می‌شود)، در غیر این صورت FileExistsError پرتاب می‌شود.

همچنین ملاحظه نمائید

متدهای open()، write_text() و write_bytes() اغلب برای ایجاد پرونده‌ها استفاده می‌شوند.

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

یک پوشه جدید در این مسیر داده‌شده ایجاد می‌کند. اگر mode داده شود، با مقدار umask فرایند ترکیب می‌شود تا حالت پرونده و پرچم‌های دسترسی را تعیین کند. اگر مسیر از قبل وجود داشته باشد، استثنای FileExistsError پرتاب می‌شود.

اگر parents درست باشد، هر والدِ موجودنشده‌ای از این مسیر در صورت نیاز ایجاد می‌شود؛ آن‌ها با دسترسی‌های پیش‌فرض ایجاد می‌شوند، بدون اینکه mode در نظر گرفته شود (با تقلید از دستور mkdir -p در POSIX).

اگر parents نادرست باشد (پیش‌فرض)، نبودِ یک والد باعث پرتاب FileNotFoundError می‌شود.

اگر exist_ok نادرست باشد (پیش‌فرض)، در صورتی که پوشه هدف از قبل وجود داشته باشد، FileExistsError پرتاب می‌شود.

اگر exist_ok درست باشد، FileExistsError پرتاب نخواهد شد، مگر اینکه مسیر داده‌شده از قبل در سامانه فایل‌بندی وجود داشته باشد و پوشه نباشد (مشابه رفتار دستور POSIX mkdir -p).

تغییر یافته در نسخه‌ی 3.5: پارامتر exist_ok اضافه شد.

Path.symlink_to(target, target_is_directory=False)

این مسیر را به یک پیوند نمادین اشاره‌کننده به target تبدیل کنید.

در ویندوز، یک پیوند نمادین (symlink) نشان‌دهنده یک پرونده یا یک پوشه است و به‌صورت پویا به هدف تغییر شکل نمی‌دهد. اگر هدف وجود داشته باشد، نوع پیوند نمادین متناسب با هدف ایجاد می‌شود. در غیر این صورت، اگر target_is_directory برابر true باشد، پیوند نمادین به‌عنوان پوشه ایجاد می‌شود؛ در غیر این صورت پیوند نمادین پرونده (حالت پیش‌فرض) ایجاد خواهد شد. در پلتفرم‌های غیر ویندوزی، 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

توجه

ترتیب آرگومان‌ها (link, target) معکوسِ ترتیب آرگومان‌های os.symlink() است.

تغییر یافته در نسخه‌ی 3.13: اگر os.symlink() در دسترس نباشد، UnsupportedOperation پرتاب می‌شود. در نسخه‌های پیشین، NotImplementedError پرتاب می‌شد.

Path.hardlink_to(target)

این مسیر را به یک پیوند سخت (hard link) به همان پرونده target تبدیل کنید.

توجه

ترتیب آرگومان‌ها (link, target) معکوسِ ترتیب آرگومان‌های os.link() است.

اضافه شده در نسخه‌ی 3.10.

تغییر یافته در نسخه‌ی 3.13: اگر os.link() در دسترس نباشد، UnsupportedOperation پرتاب می‌شود. در نسخه‌های پیشین، NotImplementedError پرتاب می‌شد.

کپی، جابه‌جایی و حذف

Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)

این پرونده یا درخت پوشه را به target داده‌شده کپی می‌کند و نمونه‌ای جدید از Path را که به target اشاره می‌کند، برمی‌گرداند.

اگر منبع یک پرونده باشد، مقصد در صورتی که پرونده موجودی باشد، جایگزین می‌شود. اگر منبع یک پیوند نمادین باشد و follow_symlinks برابر true باشد (پیش‌فرض)، هدف پیوند نمادین کپی می‌شود. در غیر این صورت، پیوند نمادین در مقصد دوباره ایجاد می‌شود.

اگر preserve_metadata برابر false باشد (پیش‌فرض)، تضمین می‌شود که فقط ساختارهای پوشه‌ها و داده‌های پرونده کپی شوند. برای اطمینان از اینکه مجوزهای پرونده و پوشه، پرچم‌ها، زمان‌های آخرین دسترسی و تغییر، و ویژگی‌های توسعه‌یافته در صورت پشتیبانی کپی شوند، preserve_metadata را روی true تنظیم کنید. این آرگومان هنگام کپی کردن پرونده‌ها در ویندوز (که فراداده همیشه حفظ می‌شود) هیچ تأثیری ندارد.

توجه

در صورتی که سیستم‌عامل و سامانه فایل‌بندی پشتیبانی کنند، این متد یک کپی سبک‌وزن انجام می‌دهد، به طوری که بلوک‌های داده فقط زمانی کپی می‌شوند که تغییر یابند. این به‌عنوان کپی در زمان نوشتن (copy-on-write) شناخته می‌شود.

اضافه شده در نسخه‌ی 3.14.

Path.copy_into(target_dir, *, follow_symlinks=True, preserve_metadata=False)

این پرونده یا درخت پوشه را در target_dir داده‌شده کپی می‌کند، که باید پوشه‌ای موجود باشد. سایر آرگومان‌ها دقیقاً مانند Path.copy() پردازش می‌شوند. یک نمونه‌ی جدید از Path برمی‌گرداند که به کپی اشاره می‌کند.

اضافه شده در نسخه‌ی 3.14.

Path.rename(target)

نام این پرونده یا پوشه را به target داده‌شده تغییر می‌دهد و یک نمونه جدید از Path را برمی‌گرداند که به target اشاره می‌کند. در یونیکس، اگر target وجود داشته باشد و پرونده باشد، در صورتی که کاربر اجازه داشته باشد، بدون پیام جایگزین می‌شود. در ویندوز، اگر target وجود داشته باشد، FileExistsError پرتاب می‌شود. 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.

این تابع بر پایه‌ی os.rename() پیاده‌سازی شده است و همان تضمین‌ها را ارائه می‌دهد.

تغییر یافته در نسخه‌ی 3.8: مقدار بازگشتی افزوده شد، نمونه‌ی جدید Path را برمی‌گرداند.

Path.replace(target)

نام این پرونده یا پوشه را به target داده‌شده تغییر می‌دهد و نمونه‌ای جدید از Path برمی‌گرداند که به target اشاره می‌کند. اگر target به یک پرونده موجود یا پوشه خالی اشاره کند، بدون قید و شرط جایگزین می‌شود.

مسیر هدف می‌تواند مطلق یا نسبی باشد. مسیرهای نسبی نسبت به پوشه‌ی کاری جاری تفسیر می‌شوند، نه پوشه‌ی شیء Path.

تغییر یافته در نسخه‌ی 3.8: مقدار بازگشتی افزوده شد، نمونه‌ی جدید Path را برمی‌گرداند.

Path.move(target)

این پرونده یا درخت پوشه را به target داده‌شده منتقل می‌کند و یک نمونه‌ی جدید از Path را برمی‌گرداند که به target اشاره می‌کند.

اگر target وجود نداشته باشد، ایجاد می‌شود. اگر هم این مسیر و هم target پرونده‌های موجود باشند، آنگاه مقصد بازنویسی می‌شود. اگر هر دو مسیر به یک پرونده یا پوشه اشاره کنند، یا target یک پوشه‌ی غیرخالی باشد، OSError پرتاب می‌شود.

اگر هر دو مسیر روی یک سامانه فایل‌بندی باشند، جابه‌جایی با os.replace() انجام می‌شود. در غیر این صورت، این مسیر (با حفظ فراداده و پیوندهای نمادین) کپی و سپس حذف می‌شود.

اضافه شده در نسخه‌ی 3.14.

Path.move_into(target_dir)

این پرونده یا درخت پوشه را به target_dir داده‌شده منتقل می‌کند، که باید یک پوشه موجود باشد. یک نمونه جدید Path را برمی‌گرداند که به مسیر منتقل‌شده اشاره می‌کند.

اضافه شده در نسخه‌ی 3.14.

Path.unlink(missing_ok=False)

این پرونده یا پیوند نمادین را حذف کنید. اگر مسیر به یک پوشه اشاره می‌کند، در عوض از Path.rmdir() استفاده کنید.

اگر missing_ok نادرست باشد (پیش‌فرض)، در صورتی که مسیر وجود نداشته باشد، FileNotFoundError پرتاب می‌شود.

اگر missing_ok درست باشد، استثناهای FileNotFoundError نادیده گرفته می‌شوند (رفتاری مشابه دستور POSIX rm -f).

تغییر یافته در نسخه‌ی 3.8: پارامتر missing_ok افزوده شد.

Path.rmdir()

این پوشه را حذف کنید. پوشه باید خالی باشد.

مجوزها و مالکیت

Path.owner(*, follow_symlinks=True)

نام کاربر مالک پرونده را برمی‌گرداند. اگر شناسه کاربر (UID) پرونده در پایگاه داده سیستم پیدا نشود، KeyError پرتاب می‌شود.

این متد معمولاً پیوندهای نمادین را دنبال می‌کند؛ برای گرفتن مالک پیوند نمادین، آرگومان follow_symlinks=False را اضافه کنید.

تغییر یافته در نسخه‌ی 3.13: اگر ماژول pwd در دسترس نباشد، استثنای UnsupportedOperation را پرتاب می‌کند. در نسخه‌های پیشین، استثنای NotImplementedError پرتاب می‌شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر follow_symlinks افزوده شد.

Path.group(*, follow_symlinks=True)

نام گروه مالک پرونده را برمی‌گرداند. اگر شناسه گروه پرونده (GID) در پایگاه داده سیستم پیدا نشود، KeyError پرتاب می‌شود.

این متد به‌طور معمول پیوندهای نمادین را دنبال می‌کند؛ برای گرفتن گروه پیوند نمادین، آرگومان follow_symlinks=False را اضافه کنید.

تغییر یافته در نسخه‌ی 3.13: اگر ماژول grp در دسترس نباشد، UnsupportedOperation پرتاب می‌شود. در نسخه‌های پیشین، NotImplementedError پرتاب می‌شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر follow_symlinks افزوده شد.

Path.chmod(mode, *, follow_symlinks=True)

حالت و مجوزهای پرونده را تغییر می‌دهد، مانند os.chmod().

این متد معمولاً پیوندهای نمادین را دنبال می‌کند. برخی از نسخه‌های یونیکس از تغییر مجوزها روی خود پیوند نمادین پشتیبانی می‌کنند؛ در این پلتفرم‌ها می‌توانید آرگومان follow_symlinks=False را اضافه کنید، یا از lchmod() استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.10: پارامتر follow_symlinks افزوده شد.

Path.lchmod(mode)

مانند Path.chmod() است، اما اگر مسیر به یک پیوند نمادین اشاره کند، حالت پیوند نمادین به جای حالت هدف آن تغییر می‌کند.

زبان الگو

وایلدکارد زیر در الگوهای full_match()، glob() و rglob() پشتیبانی می‌شوند:

** (کل بخش)

با هر تعداد بخش پرونده یا پوشه، از جمله صفر، مطابقت دارد.

* (کل بخش)

با یک بخش پرونده یا پوشه مطابقت دارد.

* (بخشی از یک بخش)

با هر تعداد نویسه‌ی غیرجداکننده، از جمله صفر، مطابقت می‌کند.

?

با یک نویسه‌ی غیرجداکننده تطابق دارد.

[seq]

با یک نویسه در seq مطابقت دارد، که در آن seq دنباله‌ای از نویسه‌هاست. از عبارت‌های بازه پشتیبانی می‌شود؛ برای مثال، [a-z] با هر حرف کوچک ASCII مطابقت دارد. می‌توان چند بازه را ترکیب کرد: [a-zA-Z0-9_] با هر حرف، رقم یا زیرخط ASCII مطابقت دارد.

[!seq]

با یک نویسه خارج از seq مطابقت می‌کند؛ seq از همان قوانین بالا پیروی می‌کند.

برای تطبیق لفظی، فرانویسه‌هارا در کروشه قرار دهید. برای مثال، "[?]" با نویسه‌ی "?" مطابقت دارد.

وایلدکارد ** امکان تطبیق الگوی بازگشتی (recursive globbing) را فراهم می‌کند. چند نمونه:

الگو	معنی
**/*	هر مسیری که دست‌کم یک بخش داشته باشد.
**/*.py	هر مسیری که بخش پایانی آن به .py ختم می‌شود.
assets/**	هر مسیری که با «assets/» آغاز شود.
assets/**/*	هر مسیری که با "assets/" آغاز می‌شود، به‌جز خود "assets/".

توجه

تطبیق الگو (globbing) با وایلدکارد «**» تمام پوشه‌های درخت را بازدید می‌کند. جستجو در درخت‌های پوشه‌ای بزرگ ممکن است زمان زیادی ببرد.

تغییر یافته در نسخه‌ی 3.13: تطبیق الگو با الگویی که به «**» ختم می‌شود، هم پرونده‌ها و هم پوشه‌ها را برمی‌گرداند. در نسخه‌های پیشین، فقط پوشه‌ها برگردانده می‌شدند.

در Path.glob() و rglob()، می‌توان یک اسلش پایانی به الگو اضافه کرد تا فقط با پوشه‌ها مطابقت کند.

تغییر یافته در نسخه‌ی 3.11: تطبیق الگو با الگویی که به یک جداکننده‌ی اجزای مسیر (sep یا altsep) ختم می‌شود، فقط پوشه‌ها را برمی‌گرداند.

مقایسه با ماژول glob

الگوهای پذیرفته‌شده و نتایج تولیدشده توسط Path.glob() و Path.rglob() اندکی با موارد ماژول glob تفاوت دارند:

1. پرونده‌هایی که با یک نقطه آغاز می‌شوند، در pathlib ویژه نیستند. این مانند فرستادن include_hidden=True به glob.glob() است.

2. در pathlib، کامپوننت‌های الگوی «**» همیشه بازگشتی هستند. این مانند ارسال recursive=True به glob.glob() است.

3. در pathlib، کامپوننت‌های الگوی «**» به‌طور پیش‌فرض پیوندهای نمادین را دنبال نمی‌کنند. این رفتار معادلی در glob.glob() ندارد، اما می‌توانید برای رفتار سازگار، recurse_symlinks=True را به Path.glob() ارسال کنید.

4. مانند همه‌ی اشیاء PurePath و Path، مقادیر برگردانده‌شده از Path.glob() و Path.rglob() شامل اسلش‌های پایانی نمی‌شوند.

5. مقادیر برگردانده‌شده از path.glob() و path.rglob() در pathlib، برخلاف نتایج glob.glob(root_dir=path)، شامل مسیر به‌عنوان پیشوند هستند.

6. مقادیر برگردانده‌شده از path.glob() و path.rglob() در pathlib ممکن است شامل خود path باشند، برای مثال هنگام تطبیق الگو با «**»، در حالی که نتایج glob.glob(root_dir=path) هرگز شامل رشته خالی‌ای که متناظر با path باشد، نمی‌شوند.

مقایسه با ماژول‌های os و os.path

pathlib عملیات مسیر را با استفاده از اشیای PurePath و Path پیاده‌سازی می‌کند و بنابراین به آن شیءگرا گفته می‌شود. از سوی دیگر، ماژول‌های os و os.path توابعی ارائه می‌دهند که با اشیای سطح پایین str و bytes کار می‌کنند، که رویکردی رویه‌ای‌تر است. برخی کاربران سبک شیءگرا را خواناتر می‌دانند.

توابع بسیاری در os و os.path از مسیرهای bytes و مسیرهای نسبی به توصیف‌گرهای پوشه پشتیبانی می‌کنند. این قابلیت‌ها در pathlib در دسترس نیستند.

انواع str و bytes پایتون، و بخش‌هایی از ماژول‌های os و os.path، به زبان C نوشته شده‌اند و بسیار سریع هستند. pathlib به زبان پایتون خالص نوشته شده است و اغلب کندتر است، اما به‌ندرت آن‌قدر کند است که اهمیت داشته باشد.

نرمال‌سازی مسیر در pathlib کمی سخت‌گیرانه‌تر و سازگارتر از os.path است. برای مثال، در حالی که os.path.abspath() بخش‌های ".." را از یک مسیر حذف می‌کند، که ممکن است اگر پیوندهای نمادین دخیل باشند، معنای مسیر را تغییر دهد، Path.absolute() این بخش‌ها را برای ایمنی بیشتر حفظ می‌کند.

نرمال‌سازی مسیر در pathlib ممکن است آن را برای برخی کاربردها نامناسب کند:

1. pathlib Path("my_folder/") را به Path("my_folder") عادی‌سازی می‌کند، که این کار معنای مسیر را هنگام ارائه به APIهای مختلف سیستم‌عامل و ابزارهای خط فرمان تغییر می‌دهد. به‌طور مشخص، نبود یک جداکننده انتهایی ممکن است باعث شود مسیر به‌عنوان یک پرونده یا پوشه تفسیر شود، نه فقط به‌عنوان یک پوشه.

2. pathlib Path("./my_program") را به Path("my_program") عادی‌سازی می‌کند، که این کار معنای یک مسیر را هنگام استفاده به‌عنوان مسیر جستجوی پرونده‌های اجرایی، مانند استفاده در پوسته یا هنگام ایجاد یک فرایند فرزند، تغییر می‌دهد. به‌طور مشخص، نبود یک جداکننده در مسیر ممکن است باعث شود که آن مسیر به‌جای پوشه جاری در PATH جستجو شود.

در نتیجه‌ی این تفاوت‌ها، pathlib جایگزینی بی‌نیاز از تغییر (drop-in replacement) برای os.path نیست.

ابزارهای متناظر

در زیر جدولی آمده است که توابع مختلف os را به معادل‌های متناظر آن‌ها از PurePath/Path نگاشت می‌کند.

os و os.path	pathlib
os.path.dirname()	PurePath.parent
os.path.basename()	PurePath.name
os.path.splitext()	PurePath.stem, PurePath.suffix
os.path.join()	PurePath.joinpath()
os.path.isabs()	PurePath.is_absolute()
os.path.relpath()	PurePath.relative_to() [1]
os.path.expanduser()	Path.expanduser() [2]
os.path.realpath()	Path.resolve()
os.path.abspath()	Path.absolute() [3]
os.path.exists()	Path.exists()
os.path.isfile()	Path.is_file()
os.path.isdir()	Path.is_dir()
os.path.islink()	Path.is_symlink()
os.path.isjunction()	Path.is_junction()
os.path.ismount()	Path.is_mount()
os.path.samefile()	Path.samefile()
os.getcwd()	Path.cwd()
os.stat()	Path.stat()
os.lstat()	Path.lstat()
os.listdir()	Path.iterdir()
os.walk()	Path.walk() [4]
os.mkdir(), os.makedirs()	Path.mkdir()
os.link()	Path.hardlink_to()
os.symlink()	Path.symlink_to()
os.readlink()	Path.readlink()
os.rename()	Path.rename()
os.replace()	Path.replace()
os.remove(), os.unlink()	Path.unlink()
os.rmdir()	Path.rmdir()
os.chmod()	Path.chmod()
os.lchmod()	Path.lchmod()

پانویس‌ها

[1]

os.path.relpath() abspath() را فراخوانی می‌کند تا مسیرها را مطلق کند و بخش‌های «..» را حذف کند، در حالی که PurePath.relative_to() یک عملیات لغوی است که هنگامی که لنگرهای ورودی‌های آن متفاوت باشند، استثنای ValueError را پرتاب می‌کند (برای مثال اگر یک مسیر مطلق و دیگری نسبی باشد.)

[2]

os.path.expanduser() در صورتی که پوشه‌ی خانه قابل تشخیص نباشد، مسیر را بدون تغییر برمی‌گرداند، در حالی که Path.expanduser() استثنای RuntimeError را پرتاب می‌کند.

[3]

os.path.abspath() کامپوننت‌های ".." را بدون حل کردن پیوندهای نمادین حذف می‌کند، که ممکن است معنای مسیر را تغییر دهد، در حالی که Path.absolute() هر یک از کامپوننت‌های ".." را در مسیر باقی می‌گذارد.

[4]

os.walk() همیشه هنگام دسته‌بندی مسیرها به dirnames و filenames پیوندهای نمادین را دنبال می‌کند، در حالی که Path.walk() وقتی follow_symlinks برابر false باشد (پیش‌فرض)، تمام پیوندهای نمادین را در filenames دسته‌بندی می‌کند.

پروتکل‌ها

ماژول pathlib.types انواعی برای بررسی ایستای نوع ارائه می‌کند.

اضافه شده در نسخه‌ی 3.14.

class pathlib.types.PathInfo

یک typing.Protocol که ویژگی Path.info را توصیف می‌کند. پیاده‌سازی‌ها می‌توانند نتایج نهان‌شده در نهانگاه را از متدهای خود بازگردانند.

exists(*, follow_symlinks=True)

اگر مسیر یک پرونده یا پوشه‌ی موجود، یا هر نوع پرونده دیگری باشد، True برمی‌گرداند؛ اگر مسیر وجود نداشته باشد، False برمی‌گرداند.

اگر follow_symlinks برابر False باشد، برای پیوندهای نمادین بدون بررسی وجود مقصدشان، True برمی‌گرداند.

is_dir(*, follow_symlinks=True)

اگر مسیر یک پوشه یا یک پیوند نمادین به یک پوشه باشد، True را برمی‌گرداند؛ اگر مسیر هر نوع پرونده دیگری باشد (یا به آن اشاره کند)، یا وجود نداشته باشد، False را برمی‌گرداند.

اگر follow_symlinks برابر False باشد، تنها در صورتی True را برمی‌گرداند که مسیر یک پوشه باشد (بدون دنبال کردن پیوندهای نمادین)؛ اگر مسیر هر نوع پرونده دیگری باشد یا وجود نداشته باشد، False را برمی‌گرداند.

is_file(*, follow_symlinks=True)

اگر مسیر یک پرونده یا پیوند نمادینی باشد که به یک پرونده اشاره می‌کند، True را برمی‌گرداند؛ اگر مسیر یک پوشه باشد (یا به یک پوشه اشاره کند) یا هر چیز دیگری غیر از پرونده باشد، یا اگر وجود نداشته باشد، False را برمی‌گرداند.

اگر follow_symlinks برابر False باشد، تنها در صورتی True را برمی‌گرداند که مسیر یک پرونده باشد (بدون دنبال کردن پیوندهای نمادین)؛ اگر مسیر یک پوشه یا غیرفایل دیگر باشد، یا وجود نداشته باشد، False را برمی‌گرداند.

is_symlink()

اگر مسیر یک پیوند نمادین باشد (حتی اگر شکسته باشد)، True را برمی‌گرداند؛ اگر مسیر یک پوشه یا هر نوع پرونده باشد، یا وجود نداشته باشد، False را برمی‌گرداند.