Divan Hafez Poems & Omen

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)

Installation

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

Methods

• hafez.total_poems() -> int

It returns `int`, the total number of poems available in the package.

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

It returns the poem in a dictionary format (see Poem Data Structure)

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

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

It returns a random poem in a dictionary format (see Poem Data Structure)

• hafez.search(qeury: str, exact_match: bool = False) -> list

It returns a list of poems in a dictionary format (see Poem Data Structure)

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

• `exact_match: bool': if True, it will search for exact match of the query

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

It downloads all the audio files.

• 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

It downloads the audio file of the given `poem`. It returns `1`, once the downloaded is completed.

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

It returns the absolute path of the audio file related to the given `poem`.

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

Poem's Data Structure

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

Example

# 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("حافظ")

Database

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

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

Vocal Audios

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

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

Demo

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

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

Developer(s)

Kaveh Bakhtiyari - Website | Medium | LinkedIn | GitHub

Contribution

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