📚 Documentation & API Usage

The arrand.arrandom module provides simple functions to retrieve random Arabic texts across various categories.

🧠 Available Functions

Function	Description	Supports Vocalized
`aya()`	Returns a random Quranic verse	✅
`hadith()`	Returns a random Hadith	✅
`phrase()`	Returns a random literary phrase	✅
`proverb()`	Returns a random Arabic proverb	✅
`poem()`	Returns a random line of poetry	✅
`paragraph()`	Returns a random paragraph	✅
`word()`	Returns a single random Arabic word	✅
`select(category)`	Generic text selector by category	✅
`sample(category, max_length)`	Returns multiple lines from category	✅
`rand_sentence()`	Generates a nonsense sentence	❌
`rand_sentences(n)`	Generates multiple nonsense lines	❌

🔎 Example: Get One Text from Each Category

import arrand.arrandom as rnd

print(rnd.aya())
print(rnd.hadith())
print(rnd.proverb())
print(rnd.phrase())
print(rnd.word())
print(rnd.poem())
print(rnd.paragraph())

🔄 Example: Get Vocalized Data

print(rnd.aya(vocalized=True))
print(rnd.sample("text", max_length=2, vocalized=True))

📦 Example: Generate Nonsense Sentences

print(rnd.rand_sentence())
print(rnd.rand_sentences(3))

To retrieve multiple lines, use:

rnd.sample(category="poem", max_length=2)

To get a single random line:

rnd.select("proverb")

Generate samples with word count control

rnd.arrandom.sample(category="text", max_length=3, min_words=9, max_words=20)

🖥️ Command Line Interface (CLI)

Once installed, you can use arrand directly from the command line:

🔧 Basic usage

```bash
arrand

Outputs a random Arabic text from the “text” category.

🗂️ Select a specific category

arrand --category aya
arrand --category hadith
arrand --category phrase
arrand --category poem
arrand --category proverb
arrand --category paragraph
arrand --category word

🔢 Generate multiple entries

Use -n or --number to control how many items to generate:

arrand -c poem -n 3
arrand -c phrase -n 5

🔤 Enable vocalization (tashkeel)

arrand -c hadith --vocalized

🤪 Generate nonsense sentences

arrand --category nonsense
arrand -c nonsense -n 2

✂️ Filter text by length

arrand --category poem --min-words 5 --max-words 10
arrand --category phrase --max-chars 120

🆘 Show help

arrand --help