aruudy 0.5.1

Arabic poetry package

Aruudy

Aruudy is a light library for Arabic prosody (Aruud) or "Science of Poetry".

Test here

web API: kariminf.pythonanywhere.com/

Notions

• Verse [Bayt]: (بيت) a line of poetry which is composed of two parts.
• Hemistich [Shatr]: (شطر) a part of a verse
• Meter [Bahr]: (بحر) The rhythme
• Scansion [Wazn]: (وزن) the weight of syllables, or the rhythmic structure
• Foot [Tafiila]: (تفعيلة) the rhythmic parts which compose the scansion

In Arabic scansion, we use two letters:

• "w": watad [peg] (وتد); it represents a vowelled letter
• "s": sabad [cord] (سبب); it represents an unvowelled letter

In english scansion, we use two characters:

• "u": short syllable;
• "-": long syllable

Features

• bahr

  • Recover all meters (arabic name, english name, transliterated name)
  • Get the meters information by either its arabic or english names

• poetry

  • Information about Arabic poetery meters
  • Normalizing part (shatr) of a verse: delete tatweel, add forgotten diacretics
  • Writing the part into prosody form
  • Finding the arabic prosodic units "watad" and "sabab" based on haraka (vowel)
  • Finding the english prosodic units based on syllables
  • Detecting Arabic poetry meter
  • Affording feet types and the parts according to these feet

• web

  • API with flask
  • CGI (Common Gateway Interface) program

Use

Install

pip install aruudy

Command line

List all available meters

aruudy [-l | --list] [a|e|t]

Will print the 16 meters names in

• Arabic if the option is "a"
• English if the option is "e"
• Transliteration if the option is "t"

For example:

aruudy -l a

Get information about a meter

aruudy [-i, --info] <name>

The name can be in Arabic or in English.

Example:

aruudy -i long

Get the meter of a Shatr (part of verse)

aruudy [-s, --shatr] <text>

Example:

aruudy -s "أَسِرْبَ القَطا هَلْ مَنْ يُعِيْرُ جَناحَهُ"

Web Api

The api uses flask which must be installed. To test the api on your machine (locally), type:

aruudy_flask

This will create a server on http://127.0.0.1:5000.

The api has these request types:

$host/ls

Returns a json list with names of available Arabic poetry meters (16 meters). The names are:

• arabic: Arabic names of the 16 meters
• english: English equivalent names
• trans: transliterated names

$host/info/[name]

Retrieve information about a meter by its name (arabic or english). It returns a json object describing the meter (bahr).

• name: an object containing the different names of the meter

  • arabic: Arabic names of the 16 meters
  • english: English equivalent names
  • trans: transliterated names

• std_scansion and used_scansion: the standard scansion of the bahr, and the used one. The two of them have the following elements:

  • ameter: meter used by Arabs as defined by Al-Khalil
  • emeter: the meter by syllables (European method)
  • mnemonic: the feet of the hemistich
  • type: the type of each foot

• key: a verse which describs the bahr

$host/info/long

$host/info/complete

$host/shatr/[text]

Used to find the meter of the given text (a shatr: part of the verse). It returns a json object with these information:

• norm: the text normalized: no tatweel, fix some diacretics

• prosody: prosody writing (الكتابة العروضية) of the text

• ameter: the arabic meter of the text

• emeter: the english/european meter of the text

• bahr: the name of the bahr

  • if not found, it is a string "None"
  • if found, it is a json object with all the bahr's description

• parts: the text divided into parts accoding to the feet (as a list). each element is an object with the following information:

  • emeter: foot's english meter
  • mnemonic: foot's mnemonic
  • part: part of the text that fits the foot
  • type: the type of the foot

$host/shatr/فَـلا%20تَظُـنّـنّ%20أنّ%20اللّيْـثَ%20يَبْتَسِـمُ

$host/shatr/فَـلا%20تَظُـنّـنّ%20أنّ

$host/shatr/[text]/[opt]

Same as $host/shatr/[text], but you can choose which elements to include in the response by separating their names with a comma (","). If you ommit "bahr", it will return just the names of the meter and not all its information. Example:

$host/shatr/فَـلا%20تَظُـنّـنّ%20أنّ%20اللّيْـثَ%20يَبْتَسِـمُ/ameter

This will return the names of the meter with the texts arabic scansion.

If you want to include all elements and ommit some, you can put a minus in front of your options list. Example:

$host/shatr/فَـلا%20تَظُـنّـنّ%20أنّ%20اللّيْـثَ%20يَبْتَسِـمُ/-parts,bahr

If you put "none", you will receive just the names of the meter.

$host/shatr/فَـلا%20تَظُـنّـنّ%20أنّ%20اللّيْـثَ%20يَبْتَسِـمُ/none

Programming

Arabic poetry meter detection

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from aruudy.poetry import prosody

text = u'أَسِرْبَ القَطا هَلْ مَنْ يُعِيْرُ جَناحَهُ'

shatr = meter.process_shatr(text)

#Normalized text
print("normalized: " + shatr.norm)

#prosody form
print("prosody form: " + shatr.prosody)

# Farahidi meter for poetry
print("arabic scansion: " + shatr.ameter)

# Western-like metre
print("western scansion: " + shatr.emeter)

#get the bahr: it has aname, ename, trans,
b = shatr.bahr

You can process a text with sub-functions (without using meter.process_shatr which uses them all):

• prosody.normalize(text): returns a normalized text; deletes tatweel and fix some diacretics problems
• prosody.prosody_form(text): returns the prosody writing (الكتابة العروضية) of the text
• meter.get_ameter(text): returns a string of arabic meter with "v" as haraka "c" as sukuun

To read the API documentation (chack Aruudy on readthedocs)[https://aruudy.readthedocs.io/en/latest/]

Recommendations

To detect the meter, the verse's part must be fully vocalized (has diacritics). This program can detect and infer some common unvolization patterns, such as the first letter of a word if it is not an alif (must be vocalized). In this case, it marks a letter as vocalized without giving the right vocalization: if it is damma, kasra or fatha.

If the text is not vocalized at all, you must vocalize it manually or automatically. A project you can use is Mishkal. When you use it with Aruudy, you have to keep in mind that Aruudy is Apache-2 licensed while Mishkal is GPL-3 licensed.

License

Copyright (C) 2014-2019 Abdelkrime Aries

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.