a3rbly

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. Keep it private; do not commit it to source control or place it in client-side code.

Install

On Debian or Ubuntu, install into a virtual environment rather than the system Python:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install a3rbly

Quick start

Pass the key to the client:

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:

export A3RBLY_API_KEY="YOUR_A3RBLY_API_KEY"

from a3rbly import A3rblyClient

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

API methods

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

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:

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.