# واجهة برمجة تطبيقات نظام الملفات

توفر فئة `HfFileSystem` واجهة ملفات بأسلوب بايثون للوصول إلى Hugging Face Hub بناءً على [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/).

## HfFileSystem[[huggingface_hub.HfFileSystem]]

`HfFileSystem` مبني على [fsspec](https://filesystem-spec.readthedocs.io/en/latest/)، لذا فهو متوافق مع معظم الواجهات البرمجية التي يوفرها. لمزيد من التفاصيل، راجع [دليلنا](../guides/hf_file_system) و[مرجع الواجهات البرمجية](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) الخاص بـ fsspec.

#### huggingface_hub.HfFileSystem[[huggingface_hub.HfFileSystem]]

```python
huggingface_hub.HfFileSystem(*args, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L370)

**المعاملات:**

endpoint (`str`، *اختياري*) : نقطة نهاية Hub. القيمة الافتراضية هي .

token (`bool` أو `str`، *اختياري*) : رمز وصول مستخدم صالح (نص). الافتراضي هو رمز الوصول المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لتعطيل المصادقة، مرر `False`.

block_size (`int`، *اختياري*) : حجم الكتلة لقراءة الملفات وكتابتها.

expand_info (`bool`، *اختياري*) : ما إذا كان سيتم توسيع معلومات الملفات.

max_workers (`int`, *اختياري*) : الحد الأقصى لعدد الطلبات المتزامنة المستخدمة لجرد المجلدات الكبيرة بالتوازي (انظر [find()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem.find)). القيمة الافتراضية هي 16. اضبطها على 1 لتعطيل الجرد المتوازي.

live_follow (`bool`, *اختياري*) : ما إذا كان يجب متابعة التغييرات في الملفات داخل الدلاء (buckets) كما تحدث على الـ Hub، بحيث تبقى القوائم المخزنة مؤقتًا محدّثة دون الحاجة إلى استدعاءات يدوية لـ [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache). عند التفعيل، يؤدي عرض قائمة الدلو إلى فتح اتصال في الخلفية مع قناة أحداث الـ Hub الخاصة بذلك الدلو. لا يؤثر هذا الإعداد على مستودعات النماذج والبيانات والمساحات (حيث لا يوفر الـ Hub تغييرات لها).

- ****storage_options** (`dict`، *اختياري*) : خيارات إضافية لنظام الملفات. راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__).

الوصول إلى مستودع بعيد على Hugging Face Hub وكأنه نظام ملفات محلي.

> [!WARNING]
> يوفر [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) توافقًا مع fsspec، وهو أمر مفيد للمكتبات التي تتطلب ذلك (مثل قراءة مجموعات بيانات Hugging Face مباشرةً باستخدام `pandas`). ومع ذلك، فإنه يُدخل عبئًا إضافيًا بسبب هذا طبقة التوافق. للحصول على أداء وموثوقية أفضل، يُنصح باستخدام طرق `HfApi` كلما أمكن ذلك.

يدعم نظام الملفات المسارات الخاصة ببروتوكول `hf://`، والذي يتبع مخططات عناوين URL التالية:

* مستودعات النماذج ومجموعات البيانات والمساحات:

```
hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>
```

* Buckets (التخزين العام):

```
hf://buckets/<bucket-id>/<path/in/bucket>
```

ملاحظة: عند استخدام [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) مباشرةً، يكون تمرير بادئة البروتوكول `hf://` اختيارياً في المسارات.

طريقة الاستخدام:

```python
>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)
```

حدد رمز المصادقة:
```python
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)
```

#### cp_file[[huggingface_hub.HfFileSystem.cp_file]]

```python
cp_file(path1: str, path2: str, revision: str | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1115)

**المعاملات:**

path1 (`str`) : المسار المصدر للنسخ منه.

path2 (`str`) : المسار الوجهة للنسخ إليه.

revision (`str`، *اختياري*) : المراجعة الخاصة بـ git التي سيتم النسخ منها.

انسخ ملفًا داخل مستودع أو بين مستودعات، أو إلى دلو.

> [!WARNING]
> ملاحظة: عند الإمكان، استخدم `HfApi.upload_file()` للحصول على أداء أفضل.

#### يوجد[[huggingface_hub.HfFileSystem.exists]]

```python
exists(path, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1336)

**المعاملات:**

path (`str`) : المسار الذي يجب التحقق منه.

**يعيد:** `bool`

صحيح إذا كان الملف موجودًا، وإلا فخطأ.

تحقق من وجود ملف.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.exists).

> [!WARNING]
> ملاحظة: عند الإمكان، استخدم `HfApi.file_exists()` للحصول على أداء أفضل.

#### البحث[[huggingface_hub.HfFileSystem.find]]

```python
find(path: str, maxdepth: int | None = None, withdirs: bool = False, detail: bool = False, refresh: bool = False, revision: str | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1051)

**المعاملات:**

path (`str`) : المسار الجذري الذي تُستخرج منه قائمة الملفات.

maxdepth (`int`, *اختياري*) : أقصى عمق للنزول إلى المجلدات الفرعية.

withdirs (`bool`، *اختياري*) : تضمين مسارات المجلدات في المخرجات. القيمة الافتراضية هي False.

detail (`bool`، *اختياري*) : إذا كانت القيمة True، تُرجع قاموسًا يربط المسارات بمعلومات الملفات. القيمة الافتراضية هي False.

refresh (`bool`، *اختياري*) : إذا كانت القيمة True، يتم تجاوز ذاكرة التخزين المؤقت وجلب أحدث البيانات. القيمة الافتراضية هي False.

revision (`str`، *اختياري*) : المراجعة الخاصة بـ git التي سيتم سرد العناصر منها.

**يعيد:** `Union[list[str], dict[str, dict[str, Any]]]`

قائمة مسارات أو قاموس لمعلومات الملفات.

قائمة بجميع الملفات الموجودة أسفل المسار.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.find).

> [!TIP]
> تُدرج المستودعات الكبيرة مجلدًا بمجلد، بالتوازي، لتجاوز ترقيم الصفحات القائم على المؤشر في نقطة نهاية `tree` في Hub. اضبط ذلك باستخدام الحجة `max_workers` في [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem).

#### get_file[[huggingface_hub.HfFileSystem.get_file]]

```python
get_file(rpath, lpath = None, callback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>, outfile = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1444)

**المعاملات:**

rpath (`str`) : المسار البعيد للتنزيل منه.

lpath (`str`، *اختياري*) : المسار المحلي للتنزيل إليه. يمكن تركه فارغًا إذا تم تقديم `outfile`.

callback (`Callback`، *اختياري*) : استدعاء اختياري لتتبع تقدم التنزيل. الافتراضي هو عدم وجود استدعاء.

outfile (`IO`، *اختياري*) : كائن مشابه للملف اختياري للكتابة إليه. إذا تم توفيره، يتم تجاهل `lpath`.

نسخ ملف بعيد واحد إلى المحلي.

> [!WARNING]
> ملاحظة: عند الإمكان، استخدم `HfApi.hf_hub_download()` أو `HfApi.download_bucket_files` للحصول على أداء أفضل.

#### glob[[huggingface_hub.HfFileSystem.glob]]

```python
glob(path: str, maxdepth: int | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1033)

**المعاملات:**

path (`str`) : نمط المسار المطابق.

maxdepth (`int`, *اختياري*) : الحد الأقصى للعمق الذي يمكن النزول إليه داخل المجلدات. افتراضيًا، لا يوجد حد.

**يعيد:** `list[str]`

قائمة بالمسارات المطابقة للنمط.

ابحث عن الملفات باستخدام مطابقة الأنماط (glob-matching).

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.glob).

#### معلومة[[huggingface_hub.HfFileSystem.info]]

```python
info(path: str, refresh: bool = False, revision: str | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1226)

**المعاملات:**

path (`str`) : المسار للحصول على معلوماته.

refresh (`bool`، *اختياري*) : إذا كانت القيمة True، يتم تجاوز ذاكرة التخزين المؤقت وجلب أحدث البيانات. القيمة الافتراضية هي False.

revision (`str`، *اختياري*) : المراجعة (revision) في git التي سيتم جلب المعلومات منها.

**يعيد:** `dict[str, Any]`

قاموس يحتوي على معلومات الملف (النوع، الحجم، معلومات الالتزام، وما إلى ذلك).

احصل على معلومات حول ملف أو مجلد.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.info).

> [!WARNING]
> ملاحظة: عند الإمكان، استخدم `HfApi.get_paths_info()` أو `HfApi.repo_info()` للحصول على أداء أفضل (أو `HfApi.get_bucket_paths_info()` أو `HfApi.bucket_info()` للحاويات)

#### invalidate_cache[[huggingface_hub.HfFileSystem.invalidate_cache]]

```python
invalidate_cache(path: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L599)

**المعاملات:**

path (`str`، *اختياري*) : المسار الذي يجب مسحُه من ذاكرة التخزين المؤقت. إذا لم يُقدَّم، فسيتم مسح ذاكرة التخزين المؤقت بالكامل.

امسح ذاكرة التخزين المؤقت للمسار المحدد.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.invalidate_cache).

#### isdir[[huggingface_hub.HfFileSystem.isdir]]

```python
isdir(path)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1361)

**المعاملات:**

path (`str`) : المسار الذي يجب التحقق منه.

**يعيد:** `bool`

صحيح إذا كان المسار مجلدًا، وإلا فخطأ.

تحقق مما إذا كان المسار مجلدًا.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isdir).

#### isfile[[huggingface_hub.HfFileSystem.isfile]]

```python
isfile(path)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1379)

**المعاملات:**

path (`str`) : المسار الذي يجب التحقق منه.

**يعيد:** `bool`

صحيح إذا كان المسار ملفًا، وإلا فخطأ.

تحقق مما إذا كان المسار ملفًا.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isfile).

#### ls[[huggingface_hub.HfFileSystem.ls]]

```python
ls(path: str, detail: bool = True, refresh: bool = False, revision: str | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L788)

**المعاملات:**

path (`str`) : المسار إلى المجلد.

detail (`bool`، *اختياري*) : إذا كانت القيمة True، تُرجع قائمة من القواميس تحتوي على معلومات الملفات. إذا كانت False، تُرجع قائمة من مسارات الملفات. القيمة الافتراضية هي True.

refresh (`bool`، *اختياري*) : إذا كانت القيمة True، يتم تجاوز ذاكرة التخزين المؤقت وجلب أحدث البيانات. القيمة الافتراضية هي False.

revision (`str`، *اختياري*) : المراجعة الخاصة بـ git التي سيتم سرد العناصر منها.

**يعيد:** `list[Union[str, dict[str, Any]]]`

قائمة مسارات الملفات (إذا كان detail=False) أو قائمة قواميس معلومات الملفات (إذا كان detail=True).

قائمة محتويات مجلد.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls).

> [!WARNING]
> ملاحظة: عند الإمكان، استخدم `HfApi.list_repo_tree()` للحصول على أداء أفضل.

#### تم التعديل[[huggingface_hub.HfFileSystem.modified]]

```python
modified(path: str, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1201)

**المعاملات:**

path (`str`) : مسار الملف.

**يعيد:** `datetime`

وقت آخر تعديل للملف.

احصل على وقت آخر تعديل للملف.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.modified).

#### resolve_path[[huggingface_hub.HfFileSystem.resolve_path]]

```python
resolve_path(path: str, revision: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L520)

**المعاملات:**

path (`str`) : المسار الذي يجب حله.

revision (`str`، *اختياري*) : المراجعة (revision) المستودع التي سيتم حلها. الافتراضي هو المراجعة المحددة في المسار.

**يعيد:** `HfFileSystemResolvedPath`

معلومات المسار المحلول التي تحتوي على `repo_type` و`repo_id` و`revision` و`path_in_repo`.

**يرفع:** ``ValueError`` أو ``NotImplementedError``

- ``ValueError`` -- إذا احتوى المسار على معلومات إصدار متضاربة.
- ``NotImplementedError`` -- عند محاولة سرد المستودعات.

حل مسار نظام ملفات Hugging Face إلى مكوّناته.

#### rm[[huggingface_hub.HfFileSystem.rm]]

```python
rm(path: str, recursive: bool = False, maxdepth: int | None = None, revision: str | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L738)

**المعاملات:**

path (`str`) : المسار الذي سيتم حذفه.

recursive (`bool`، *اختياري*) : إذا كانت القيمة True، يتم حذف المجلد وكل محتوياته. القيمة الافتراضية هي False.

maxdepth (`int`, *اختياري*) : الحد الأقصى لعدد الدلائل الفرعية التي يجب زيارتها عند الحذف بشكل تكراري.

revision (`str`، *اختياري*) : المراجعة الخاصة بنظام git التي سيتم الحذف منها.

حذف الملفات من مستودع.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.rm).

> [!WARNING]
> ملاحظة: عند الإمكان، استخدم `HfApi.delete_file()` للحصول على أداء أفضل.

#### url[[huggingface_hub.HfFileSystem.url]]

```python
url(path: str)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1397)

**المعاملات:**

path (`str`) : المسار للحصول على عنوان URL الخاص به.

**يعيد:** `str`

رابط HTTP للوصول إلى الملف أو المجلد على Hub.

احصل على عنوان URL الخاص بـ HTTP للمسار المحدد.

#### المشي[[huggingface_hub.HfFileSystem.walk]]

```python
walk(path: str, *args, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hf_file_system.py#L1017)

**المعاملات:**

path (`str`) : المسار الجذري الذي تُستخرج منه قائمة الملفات.

**يعيد:** `Iterator[tuple[str, list[str], list[str]]]`

مُتكرِّر (iterator) من tuples من الشكل (path, قائمة أسماء المجلدات، قائمة أسماء الملفات).

إرجاع جميع الملفات الموجودة أسفل المسار المحدد.

لمزيد من التفاصيل، راجع [توثيق fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.walk).