----------------------------------------------------------------------
This is the API documentation for the gdtest_i18n_arabic library.
----------------------------------------------------------------------


## الفئات

الفئات الأساسية


Formatter(left_delim: str = '{{', right_delim: str = '}}', auto_escape: bool = True)

تنسيق النصوص باستخدام القوالب.

يدعم استبدال العناصر النائبة، وترميز HTML،
وفواصل قابلة للتخصيص.

Parameters
----------
left_delim : str
    الفاصل الأيسر للعناصر النائبة.
right_delim : str
    الفاصل الأيمن للعناصر النائبة.
auto_escape : bool
    ترميز HTML تلقائياً للقيم المستبدلة.

See Also
--------
format_text
    تغليف النص بعرض سطر محدد.
escape_html
    ترميز الأحرف الخاصة في HTML.

Examples
--------
>>> fmt = Formatter(left_delim="{{", right_delim="}}")
>>> fmt.render("مرحباً {{name}}!", name="World")
'مرحباً World!'

.. versionadded:: 0.1.0


## الدوال

الدوال العامة


format_text(text: str, width: int = 80) -> str

تغليف النص بعرض سطر محدد.

Parameters
----------
text : str
    النص المراد تغليفه.
width : int
    أقصى عرض للسطر.

Returns
-------
str
    النص المُغلَّف.

See Also
--------
Formatter
    تنسيق النصوص باستخدام القوالب.
parse_template
    تحليل نص القالب إلى مكوناته.

.. versionchanged:: 0.1.0 أصبح العرض الافتراضي 80 حرفاً.

parse_template(source: str) -> dict

تحليل نص القالب إلى مكوناته.

Parameters
----------
source : str
    نص القالب الخام.

Returns
-------
dict
    القالب المحلل مع مفاتيح 'text' و 'placeholders'.

escape_html(value: str) -> str

ترميز الأحرف الخاصة في HTML.

Parameters
----------
value : str
    النص المراد ترميزه.

Returns
-------
str
    نص آمن لاستخدامه في HTML.

See Also
--------
Formatter
    تنسيق النصوص باستخدام القوالب.
format_text
    تغليف النص بعرض سطر محدد.

.. deprecated:: 0.1.0
    استخدم Formatter(auto_escape=True) بدلاً من ذلك.


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------


## الأساسيات

# نظرة عامة

يوفر هذا الحزمة أدوات لتنسيق النصوص مع دعم
القوالب وترميز HTML.

## التثبيت

```bash
pip install gdtest-i18n-arabic
```

## مثال سريع

```python
from gdtest_i18n_arabic import Formatter

fmt = Formatter()
result = fmt.render("مرحباً {{name}}!", name="World")
print(result)
```


# القوالب

تعلم كيفية استخدام نصوص القوالب مع العناصر النائبة.

## صيغة العناصر النائبة

```python
from gdtest_i18n_arabic import parse_template

result = parse_template("مرحباً {{name}}، أهلاً بك في {{place}}!")
print(result["placeholders"])
```

## ترميز HTML

```python
from gdtest_i18n_arabic import escape_html

safe = escape_html("<script>alert('test')</script>")
print(safe)
```


# مستكشف الجدول

استخدم `tbl_explorer()` لاستكشاف بياناتك بشكل تفاعلي.

```{python}
#| echo: false
import tempfile
from great_docs import tbl_explorer
rows = "الاسم,العمر,المدينة,الدرجة\nأحمد,28,القاهرة,92.5\nفاطمة,35,الرياض,87.3\nخالد,22,دبي,95.1\nنور,41,بيروت,78.6\nسارة,30,الدار البيضاء,88.9\nعمر,27,تونس,91.2\nليلى,33,عمان,84.7"
tf = tempfile.NamedTemporaryFile(mode="w", suffix=".csv", delete=False)
tf.write(rows)
tf.close()
tbl_explorer(tf.name)
```