This library gives you access to the Hafez Poems. To get more information about this poet, you can check https://en.wikipedia.org/wiki/Hafez.

Poems can be accessed as following:

• By the number of poem,
• By searching a query,
• Random poem (known as Omen or Fal in Persian)

This package can be installed:

• using pip:

pip install hafez

• using Makefile on a cloned/forked repo:

make install

• using pip on a cloned/forked repo:

pip install -e . --upgrade --upgrade-strategy only-if-needed

• hafez.total_poems() -> int

• hafez.get_poem(poem_id: int) -> dict

• poem_id: int: It is a number between 1 and hafez.total_poems().

• hafez.omen() or hafez.fal() -> dict

• hafez.search(qeury: str) -> list

• query: str: It is a string to search within the verses of the Divan Hafez

• hafez.download_all_audio(force: boolean = False) -> int

• force: boolean = False: If it is set to False, it only downloads the file if not previously downloaded. If set to True, it will force to re-download and replace the existing file.

• hafez.download_audio(poem: int) -> int

• hafez.get_audio(poem: int=1, download: boolean = True) -> str

• poem: int=1: It is the poem number.
• download: boolean = True: If download=True, it downloads the audio file if not existing.

{"id": 1,
"poem": [],
"interpretation": "",
"mp3": "https://..."}

# it returns the total number of poems
# returns: int
total_number_of_poems = hafez.total_poems()

# get a poem by ID
# returns: dict
poem_5 = hafez.get_poem(5)

# get a random poem - omen (fal)
# returns: dict
omen = hafez.omen()  # same as: hafez.fal()

# search within the verses of poems
# returns: list[dict]
search_result = hafez.search("حافظ")

The poems of Divan Hafez are extracted from an open-source database as below:

Source: https://github.com/mahmoud-eskandari/HafezFaalDatabase

The vocal audio files are done by Ms. Modares Zadeh, and it is available below:

Source: https://avayemastan.deklame.net/hafez/

You can access the demo version deployed on Streamlit server at:

https://divan-hafez.streamlit.app/

Kaveh Bakhtiyari - Website | Medium | LinkedIn | GitHub

Feel free to join the open-source community and contribute to this repository.