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

مسیرها تغییرناپذیر و هش‌پذیر هستند. مسیرهای هم‌نوع قابل مقایسه و مرتب‌سازی هستند. این ویژگی‌ها معناشناسی تبدیل حالت حروف (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'

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

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

PurePath.parts¶

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

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

(توجه کنید که چگونه درایو و ریشه‌ی محلی در یک بخش واحد دوباره گروه‌بندی شده‌اند)

متدها و ویژگی‌ها¶

خصوصیات parent، name، stem و suffix بخش‌های مختلف یک مسـیر را توصیف می‌کنند. برای مثال، با فرض:

>>> p = PurePosixPath('/srv/holy/grail.tar.gz')

بخش stem فقط پسوند نهایی را حذف می‌کند: در این مثال، شامل .tar می‌شود.

مسیرهای خالص، متدها و ویژگی‌های زیر را ارائه می‌دهند:

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.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('**/*.py')
True
>>> PurePath('/a/b/c.py').full_match('/a/**')
True

الگوهایی که به "/**" ختم می‌شوند، همان‌طور که در مثال بالا دیدید، ممکن است هنگام ارسال به full_match تعجب‌برانگیز باشند. با اینکه "**" می‌تواند با صفر بخش مطابقت پیدا کند، اما ".../**" برای مطابقت به یک جداکننده نیاز دارد. از این رو، "/a/**" با مسیر "/a" مطابقت نمی‌کند. از آنجا که PurePath اسلش‌های پایانی را حذف می‌کند، این الگو همچنین با "/a/" مطابقت ندارد.

>>> PurePath('/a').full_match('/a/**')
False
>>> PurePath('/a/').full_match('/a/**')
False

همچنین ببینید

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

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

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

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

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

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 پرتاب می‌شد.

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

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()  # The current directory.
True
>>> 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) باشد، 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, *, parent_mode=None)¶

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

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

اگر parent_mode برابر با None نباشد، هنگامی که parents برابر با true باشد، به عنوان حالت (mode) برای هر پوشه‌ی سطح میانیِ تازه‌ایجادشده استفاده می‌شود. مانند mode، این مقدار با مقدار umask فرایند ترکیب می‌شود. در غیر این صورت، پوشه‌های میانی با مجوزهای پیش‌فرض ایجاد می‌شوند (که آن‌ها نیز مشمول umask هستند).

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

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

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

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

اضافه شده در نسخه‌ی 3.15: پارامتر parent_mode.

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() است، اما اگر مسیر به یک پیوند نمادین اشاره کند، حالت پیوند نمادین به جای حالت هدف آن تغییر می‌کند.

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

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

پانویس‌ها