Python/pathlib/PurePath

 الصنف pathlib.PurePath في بايثون

يحوي هذا الصنف التوابع والعمليات الأساسية للتعامل مع المسارات، إلا أنها لا تحوي أي وصول حقيقي إلى نظام الملفات، ومن ثمّ فليس فيها أي عملية إدخال أو إخراج بل تقتصر على العمليات النصية على المسارات، ويمكننا تلخيص عملها بأنها توابع لمعالجة السلاسل النصية التي تمثل مسارات الملفات.

يمكن للمسارات النقية أن تكون مفيدةٌ في بعض الحالات الخاصة المماثلة لما يلي:

1. لمعالجة مسارات نظام ويندوز أثناء العمل على جهاز يعمل بنظام يونكس (والعكس بالعكس)، حيث لا يمكنك إنشاء كائن من الصنف WindowsPath عند العمل على نظام يونكس، ولكن يمكنك إنشاء كائن من الصنف PureWindowsPath.
2. عليك التأكد بأن الشيفرة البرمجية تعالج المسارات فقط دون الوصول الفعلي إلى نظام التشغيل، ففي هذه الحالة، يمكنك إنشاء كائن من أحد الأصناف النقية، فهي لا تملك عمليات تسمح لها بالوصول إلى نظام التشغيل.

يمكنك إنشاء كائنات من أيٍّ من الأصناف المذكورة آنفًا على أي نظام تشغيل، وذلك لأنها لا تقوم بأي استدعاءات من النظام.

الاستخدام الأساسي للصنف PurePath

يمكن إنشاء كائنات من هذا الصنف لمعالجة المسارات بحيث لا يتم الوصول الفعلي إلى نظام الملفات. وتوجد ثلاث طرائق لإنشاء كائنات من هذا الصنف (تُسمّى الطرق بالنكهات)

عند استخدام الصنف العام المجرد PurePath فإن الصنف الحقيقي للكائن المنشأ منه يعتمد على نظام التشغيل، فهو إما PurePosixPath أو PureWindowsPath

>>> PurePath('setup.py')      # يتم العمل على نظام يونكس
PurePosixPath('setup.py')

يمكن لكل عنصر من الوسيط pathsegments أن يكون سلسلة نصية تمثل قطعة مسار أو كائنًا ينفذ الواجهة os.PathLike التي تعيد سلسلة نصية، كما يمكن أن تكون كائن مسار آخر.

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')

>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

ويُفترض وجود المسار '.' عندما يكون الوسيط pathsegments  خاليًا:

>>> PurePath()
PurePosixPath('.')

عندما تُعطى عدة مسارات مطلقة، يُعتبر المسار الأخير على أنه مسار المبدأ(anchor) (بشكل مطابق لسلوك التابع os.path.join)

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')

>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

عند العمل في مسارات ويندوز، فإن تغيير مجلد الجذر المحلي لا يؤدي إلى إهمال إعدادات القرص السابق

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

يُضمّ رمز الشرطة '/' المكرر وكذلك النقطة المفردة، إلا أنه لا يُتعامل بالمثل مع النقطتين المزدوجتين '..' وذلك لأن هذا قد يغير دلالة المسار في حال استخدام الروابط الرمزية:

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')

>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')

>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

قد يبدو للوهلة الأولى أن المسار ‎‎‎PurePosixPath('foo/../bar')‎‎ يجب أن يكون مساويًا للمسار PurePosixPath('bar')‎ ولكن ذلك غير صحيح إذا كان المجلد 'foo' رابطًا رمزيًّا (symbolic link) لمجلد آخر.

تقوم كائنات المسار النقي بتنفيذ الواجهة os.PathLike، بما يسمح باستخدامها في أي مكان تُقبل في هذه الواجهة.

تغيرت في النسخة 3.6: أُضيف الدعم للواجهة os.PathLike

الخصائص الأساسية لكائنات الصنف PurePath

تتميز أصناف المسارات بكونها ثابتة immutable و قابلة للتهشير hashable، كما يمكن مقارنة وترتيب كائنات المسارات التي تكون من نفس النكهة مع مراعاة خصائص المسارات الخاصة بكل نكهة

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

العمليات المُعاد تعريفها للصنف PurePath

تساعد عملية القسمة '/' في إنشاء مسارات الأبناء، بشكل مشابه لما يقوم به التابع os.path.join

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')

>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')

>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

يمكن استخدام كائنات المسارات في أي مكان يقبل كائنًا ينفذ الواجهة 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 المسار الخام كما هو موجود في نظام الملفات ككائن من النوع bytes وذلك بنفس طريقة التابع os.fsencode

>>> bytes(p)

b'/etc'

مثال آخر في نظام ويندوز

>>> p=Path('C:\\Program Files\\Everything\\Everything.exe')
>>> p
WindowsPath('C:/Program Files/Everything/Everything.exe')
>>> bytes(p)
b'C:\\Program Files\\Everything\\Everything.exe'
>>> os.fsencode(p)
b'C:\\Program Files\\Everything\\Everything.exe'

ملاحظة:

يُستحسن استدعاء التابع bytes ضمن نظام يونكس فقط، فترميز unicode في نظام ويندوز هو التمثيل الأساسي لمسارات نظام الملفات.

المتغيرات الأعضاء في الصنف PurePath

المتغير PurePath.parts

يمثّل هذا المتغير tuple لعناصر المسار

المتغير PurePath.drive

سلسلة نصية تمثل اسم السواقة أو الحرف الممثل لها (في حال وجوده ضمن المسار)

المتغير PurePath.anchor

يجمع اسم السواقة مع مسار الجذر

المتغير PurePath.parents

سلسة غير قابلة للتعديل (immutable) تُعطي وصولًا للآباء المنطقية للمسار

المتغير PurePath.parent

الأب المنطقي للمسار الحالي

المتغير PurePath.name

سلسة نصية تُمثّل العنصر الأخير في المسار، مع استثناء السواقة ومسارالجذر إن وُجد أي منهما

المتغير PurePath.suffix

امتداد الملف لآخر عنصر في المسار (إن كان له امتداد)

المتغير PurePath.suffixes

قائمة بامتدادات الملف الذي يشير إليه المسار.

المتغير PurePath.stem

آخر عنصر في المسار، دون امتداده

التوابع الأعضاء في الصنف PurePath

التابع PurePath.as_posix

يعيد تمثيلًا نصّيًّا للمسار مع استخدام الشرطة الأمامية للفصل بين المستويات في المسار '/'

>>> p = PureWindowsPath('c:\\windows')

>>> str(p)
'c:\\windows'

>>> p.as_posix()
'c:/windows'

التابع PurePath.as_uri

يعيد تمثيل المسار بتمثيل URI، ويرمي استثناء ValueError إن لم يكن المسار بصيغته المطلقة.

>>> p = PurePosixPath('/etc/passwd')

>>> p.as_uri()
'file:///etc/passwd'

>>> p = PureWindowsPath('c:/Windows')

>>> p.as_uri()
'file:///c:/Windows'

التابع PurePath.is_absolute

يعيد True إن كان كائن المسار يشير إلى مسارٍ مطلق. يكون المسار مطلقًا إن كان يحتوي على مسار جذر واسم السواقة (إن كانت نكهة كائن المسار تسمح بذلك).

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

يعيد True عند استخدام النكهة PureWindowsPath إذا كان المسار يُعتبر اسمًا مجوزًا في نظام ويندوز.

أما عند استخدام النكهة PurePosixPath فالتابع يعيد False دومًا.

>>> PureWindowsPath('nul').is_reserved()
True

>>> PurePosixPath('nul').is_reserved()
False

عند إجراء استعداءات نظام على مسارات محجوزة فإنها قد تفضل بشكل غامض ويمكن أن يكون لها آثار غير متوقعة.

التابع PurePath.joinpath

يُؤدي استدعاء هذا التابع إلى دمج المسار مع كلٍّ من الوسطاء الممررة له بالترتيب.

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

يختبر هذا التابع مطابقة المسار لنمط اختبار المطابقة glob المعطى.

التابع PurePath.relative_to

يحسب هذا التابع كيف يبدو المسار عند اعتباره منسوبًا إلى المسار المُعطى، ويرمي الاستثناء 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 694, in relative_to
   .format(str(self), str(formatted)))
ValueError: '/etc/passwd' does not start with '/usr'

التابع PurePath.with_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_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')

التقابل مع الوحدة os

يبيّن الجدول التالي تقابل عدة توابع من الوحدة os  مع ما يقابلها و يكافئها من الوحدة PurePath.

الوحدة os والوحدة os.path	الوحدة pathlib
os.path.isabs()	PurePath.is_absolute()
os.path.join()	PurePath.joinpath()
os.path.basename()	PurePath.name
os.path.dirname()	PurePath.parent
os.path.splitext()	PurePath.suffix