Python SDK
Sync and async Python client. Supports Python 3.9+. Built on httpx.
Installation
bash
pip install kalimalabUse a virtual environment:
python -m venv .venv && source .venv/bin/activateClient initialization
import osfrom kalimalab import KalimaLabclient = KalimaLab(api_key=os.environ["KALIMALAB_API_KEY"])Methods
client.words.searchSearch Arabic words with optional filters.
python
client.words.search( q: str, limit: int = 20, offset: int = 0, root: str | None = None, pos: str | None = None, letters: int | None = None,) -> SearchResult| Param | Type | Req | Description |
|---|---|---|---|
q | str | Yes | Search query |
limit | int | No | 1–100. Default: 20 |
offset | int | No | Offset. Default: 0 |
root | str | None | No | Filter by root |
pos | str | None | No | Part-of-speech filter |
letters | int | None | No | Exact letter count |
python
result = client.words.search(q="كتب", limit=5)print(result.total) # 47print(result.data[0].word) # 'كتب'client.words.getFetch full details for a single word.
python
client.words.get(slug: str) -> Word| Param | Type | Req | Description |
|---|---|---|---|
slug | str | Yes | Word slug or ID |
python
word = client.words.get("كتب")print(word.meaning_en) # 'to write'client.words.dailyGet the word of the day.
python
client.words.daily() -> Wordpython
word = client.words.daily()print(word.word) # 'الأَمَل'client.words.validateValidate Arabic words against the database.
python
client.words.validate(words: list[str]) -> ValidationResult| Param | Type | Req | Description |
|---|---|---|---|
words | list[str] | Yes | Up to 100 words |
python
result = client.words.validate(["كتب", "xyz", "مدرسة"])print(result.valid) # ['كتب', 'مدرسة']print(result.invalid) # ['xyz']client.text.analyzeAnalyze a passage of Arabic text.
python
client.text.analyze(text: str) -> TextAnalysis| Param | Type | Req | Description |
|---|---|---|---|
text | str | Yes | Arabic text (max 5,000 characters) |
python
analysis = client.text.analyze("بسم الله الرحمن الرحيم")print(analysis.word_count) # 4Async usage
python
import asynciofrom kalimalab import AsyncKalimaLabasync def main(): async with AsyncKalimaLab(api_key="...") as client: result = await client.words.search(q="كتب") print(result.total)asyncio.run(main())Error handling
python
from kalimalab import KalimaLabErrortry: result = client.words.search(q="كتب")except KalimaLabError as e: print(e.status) print(e.code) print(e.message)