Metadata-Version: 2.4
Name: a3rbly-api
Version: 0.1.0
Summary: Python client for the A3rbly Arabic grammar and diacritization API
Project-URL: Homepage, https://a3rbly.com
Project-URL: API, https://api.a3rbly.com
Project-URL: Documentation, https://api.a3rbly.com/openapi.json
Keywords: a3rbly,arabic,i3rab,diacritization,api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# a3rbly-api

A small Python client for the A3rbly Arabic grammar parsing and diacritization API.
It uses the standard library and works with Python 3.9 and newer.

## Get an API key

Get your API key from [a3rbly.com](https://a3rbly.com). Keep it private; do not
commit it to source control or place it in client-side code.

## Install

```bash
pip install a3rbly-api
```

## Quick start

Pass the key to the client:

```python
from a3rbly import A3rblyClient

client = A3rblyClient(api_key="YOUR_A3RBLY_API_KEY")

parsed = client.parse("قرأ الطالب الكتاب")
print(parsed)

vocalized = client.diacritize("قرأ الطالب الكتاب")
print(vocalized)
```

Or set an environment variable so the key stays out of your source code:

```bash
export A3RBLY_API_KEY="YOUR_A3RBLY_API_KEY"
```

```python
from a3rbly import A3rblyClient

client = A3rblyClient()
print(client.i3rab("قرأ الطالب الكتاب"))
```

## API methods

| Python method | HTTP request | Description |
| --- | --- | --- |
| `client.parse(sentence)` | `POST /i3rab` | Parses a sentence. Sends `{"prompt": "..."}`. |
| `client.i3rab(sentence)` | `POST /i3rab` | Alias for `parse`. |
| `client.diacritize(text)` | `GET /diacritize?text=...` | Adds diacritics to Arabic text. |

The base URL defaults to `https://api.a3rbly.com`. Each method returns the
decoded JSON response as a Python dictionary. The client sends the key in both
the `x-api-key` and `Authorization: Bearer ...` headers.

## Errors

All client errors derive from `A3rblyError`:

- `A3rblyAuthenticationError` for HTTP 401 or 403
- `A3rblyRateLimitError` for HTTP 429
- `A3rblyAPIError` for other unsuccessful or malformed API responses
- `A3rblyConnectionError` when the API cannot be reached

```python
from a3rbly import A3rblyAPIError, A3rblyClient

client = A3rblyClient()  # Reads A3RBLY_API_KEY from the environment

try:
    result = client.parse("الطالب مجتهد")
except A3rblyAPIError as error:
    print(error.status_code, error.code, error)
```

The request timeout defaults to 30 seconds and can be changed when creating
the client: `A3rblyClient(timeout=10)`.

## Build for PyPI

From this directory, build the wheel and source archive with:

```bash
python -m pip install build
python -m build
```

Choose the package license and PyPI account credentials before publishing the
generated files in `dist/`.

## API reference

The live API schema is available at
[api.a3rbly.com/openapi.json](https://api.a3rbly.com/openapi.json).

