a3rbly 0.1.0__tar.gz

a3rbly-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: a3rbly
+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
+
+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
+
+On Debian or Ubuntu, install into a virtual environment rather than the system Python:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install a3rbly
+```
+
+## 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).
+

a3rbly-0.1.0/README.md

@@ -0,0 +1,101 @@
+# 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](https://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:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install a3rbly
+```
+
+## 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).
+

a3rbly-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a3rbly"
+version = "0.1.0"
+description = "Python client for the A3rbly Arabic grammar and diacritization API"
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["a3rbly", "arabic", "i3rab", "diacritization", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Text Processing :: Linguistic",
+]
+
+[project.urls]
+Homepage = "https://a3rbly.com"
+API = "https://api.a3rbly.com"
+Documentation = "https://api.a3rbly.com/openapi.json"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

a3rbly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

a3rbly-0.1.0/src/a3rbly/__init__.py

@@ -0,0 +1,21 @@
+"""Python client for the A3rbly Arabic language API."""
+
+from .client import A3rblyClient
+from .exceptions import (
+    A3rblyAPIError,
+    A3rblyAuthenticationError,
+    A3rblyConnectionError,
+    A3rblyError,
+    A3rblyRateLimitError,
+)
+
+__all__ = [
+    "A3rblyClient",
+    "A3rblyError",
+    "A3rblyAPIError",
+    "A3rblyAuthenticationError",
+    "A3rblyRateLimitError",
+    "A3rblyConnectionError",
+]
+
+__version__ = "0.1.0"

a3rbly-0.1.0/src/a3rbly/client.py

@@ -0,0 +1,164 @@
+"""Synchronous HTTP client for the A3rbly API."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .exceptions import (
+    A3rblyAPIError,
+    A3rblyAuthenticationError,
+    A3rblyConnectionError,
+    A3rblyRateLimitError,
+)
+
+
+class A3rblyClient:
+    """Call A3rbly's Arabic grammar and diacritization endpoints.
+
+    Pass ``api_key`` directly, or set the ``A3RBLY_API_KEY`` environment
+    variable. The client never contains a built-in API key.
+    """
+
+    API_KEY_URL = "https://a3rbly.com"
+    DEFAULT_BASE_URL = "https://api.a3rbly.com"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        key = api_key or os.getenv("A3RBLY_API_KEY")
+        if not key or not key.strip():
+            raise ValueError(
+                "An A3rbly API key is required. Get one at "
+                f"{self.API_KEY_URL} or set the A3RBLY_API_KEY environment variable."
+            )
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+
+        self._api_key = key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def parse(self, sentence: str) -> dict[str, Any]:
+        """Parse an Arabic sentence with ``POST /i3rab``.
+
+        Returns the decoded JSON object from the API. The API commonly
+        returns parsed words under ``data.words``.
+        """
+        sentence = self._validate_text(sentence, "sentence")
+        return self._request(
+            "POST",
+            "/i3rab",
+            payload={"prompt": sentence},
+        )
+
+    def i3rab(self, sentence: str) -> dict[str, Any]:
+        """Alias for :meth:`parse`."""
+        return self.parse(sentence)
+
+    def diacritize(self, text: str) -> dict[str, Any]:
+        """Add Arabic diacritics with ``GET /diacritize``.
+
+        Returns the decoded JSON object from the API. Depending on the
+        response, the resulting text may be in ``diacritized_text``,
+        ``result``, or ``text``.
+        """
+        text = self._validate_text(text, "text")
+        return self._request("GET", "/diacritize", query={"text": text})
+
+    @staticmethod
+    def _validate_text(value: str, field: str) -> str:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"{field} must be a non-empty string")
+        return value.strip()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        query: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        if query:
+            url = f"{url}?{urlencode(query)}"
+
+        headers = {
+            "Accept": "application/json",
+            "x-api-key": self._api_key,
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": "a3rbly-python/0.1.0",
+        }
+        body = None
+        if payload is not None:
+            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        request = Request(url, data=body, headers=headers, method=method)
+
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                raw_body = response.read()
+                status_code = response.status
+        except HTTPError as error:
+            raw_body = error.read()
+            raise self._api_exception(error.code, raw_body) from None
+        except (URLError, TimeoutError, OSError) as error:
+            reason = getattr(error, "reason", error)
+            raise A3rblyConnectionError(
+                f"Could not connect to {self.base_url}: {reason}"
+            ) from error
+
+        try:
+            decoded = json.loads(raw_body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise A3rblyAPIError(
+                status_code,
+                "A3rbly returned a response that was not valid JSON.",
+            ) from error
+
+        if not isinstance(decoded, dict):
+            raise A3rblyAPIError(
+                status_code,
+                "A3rbly returned JSON in an unexpected format.",
+            )
+        return decoded
+
+    @staticmethod
+    def _api_exception(status_code: int, raw_body: bytes) -> A3rblyAPIError:
+        try:
+            response = json.loads(raw_body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            response = {}
+        if not isinstance(response, dict):
+            response = {}
+
+        message = (
+            response.get("detail")
+            or response.get("error")
+            or response.get("title")
+            or f"A3rbly API request failed with HTTP {status_code}."
+        )
+        code = response.get("code")
+
+        error_type = A3rblyAPIError
+        if status_code in (401, 403):
+            error_type = A3rblyAuthenticationError
+        elif status_code == 429:
+            error_type = A3rblyRateLimitError
+
+        return error_type(
+            status_code,
+            str(message),
+            code=str(code) if code is not None else None,
+            response=response,
+        )

a3rbly-0.1.0/src/a3rbly/exceptions.py

@@ -0,0 +1,38 @@
+"""Exceptions raised by the A3rbly client."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class A3rblyError(Exception):
+    """Base exception for errors raised by this package."""
+
+
+class A3rblyAPIError(A3rblyError):
+    """An unsuccessful response returned by the A3rbly API."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        code: str | None = None,
+        response: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.response = dict(response or {})
+        super().__init__(message)
+
+
+class A3rblyAuthenticationError(A3rblyAPIError):
+    """The API key is missing, invalid, or not authorized."""
+
+
+class A3rblyRateLimitError(A3rblyAPIError):
+    """The API rejected a request because a usage limit was reached."""
+
+
+class A3rblyConnectionError(A3rblyError):
+    """The client could not connect to the A3rbly API."""

a3rbly-0.1.0/src/a3rbly.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: a3rbly
+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
+
+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
+
+On Debian or Ubuntu, install into a virtual environment rather than the system Python:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install a3rbly
+```
+
+## 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).
+

a3rbly-0.1.0/src/a3rbly.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/a3rbly/__init__.py
+src/a3rbly/client.py
+src/a3rbly/exceptions.py
+src/a3rbly.egg-info/PKG-INFO
+src/a3rbly.egg-info/SOURCES.txt
+src/a3rbly.egg-info/dependency_links.txt
+src/a3rbly.egg-info/top_level.txt

a3rbly-0.1.0/src/a3rbly.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

a3rbly-0.1.0/src/a3rbly.egg-info/top_level.txt

@@ -0,0 +1 @@
+a3rbly