{"id":32558305,"url":"https://github.com/grv96/surahdb","last_synced_at":"2026-05-17T04:41:05.614Z","repository":{"id":301088997,"uuid":"972287666","full_name":"GRV96/surahdb","owner":"GRV96","description":"A database for the Quran's surahs. This project is the result of an intellectual interest in Islam's sacred book.","archived":false,"fork":false,"pushed_at":"2025-06-25T04:26:42.000Z","size":79,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-25T05:25:20.973Z","etag":null,"topics":["csv","csv-files","matplotlib","mysql","mysql-database","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GRV96.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-24T20:41:04.000Z","updated_at":"2025-06-24T21:38:04.000Z","dependencies_parsed_at":"2025-06-25T05:36:31.101Z","dependency_job_id":null,"html_url":"https://github.com/GRV96/surahdb","commit_stats":null,"previous_names":["grv96/surahdb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GRV96/surahdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GRV96%2Fsurahdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GRV96%2Fsurahdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GRV96%2Fsurahdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GRV96%2Fsurahdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GRV96","download_url":"https://codeload.github.com/GRV96/surahdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GRV96%2Fsurahdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281533444,"owners_count":26517827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csv","csv-files","matplotlib","mysql","mysql-database","python","python3"],"created_at":"2025-10-28T23:54:12.076Z","updated_at":"2025-10-28T23:55:10.018Z","avatar_url":"https://github.com/GRV96.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SurahDB\n\n## FRANÇAIS\n\nCe projet est né d'un intérêt intellectuel pour le Coran. Des scripts à la\nracine du dépôt communiquent avec une base de données rassemblant des\ninformations sur les 114 sourates du livre sacré de l'islam.\n\n### Connexion à un serveur MySQL\n\nTous les scripts se connectent à un serveur MySQL pour accéder à la base de\ndonnées. L'utilisateur doit leur fournir en argument le chemin d'un fichier\nJSON configurant cette connexion. Le fichier de configuration doit correspondre\nà [ce schéma](src/database/db_config_schema.json).\n\nUne configuration valide ressemble au modèle ci-dessous.\n```\n{\n  \"host\": \"host_name\",\n  \"user\": \"username\",\n  \"password\": \"password\",\n  \"allow_local_infile\": true\n}\n```\n\nChaque propriété de la configuration doit correspondre à un\n[argument de connexion](https://dev.mysql.com/doc/connector-python/en/connector-python-connectargs.html).\nL'argument `allow_local_infile` est optionnel; sa valeur par défaut est vrai\n(`true`). La configuration peut contenir des proprités autres que celles\nindiquées ci-dessus.\n\n### Ordre des sourates\n\nL'ordre des sourates dans le Coran (l'ordre traditionnel) ne correspond pas à\nl'ordre chronologique de leur révélation. Lorsqu'on extrait les données des\nsourates, on peut les ordonner traditionnellement ou chronologiquement.\n\n### Propriétés des sourates\n\n`id`: numéro dans l'ordre traditionnel et identifiant.\n\n`chronology`: position dans l'ordre chronologique.\n\n`titlefr`: titre en français.\n\n`titleen`: titre en anglais.\n\n`period`: période mecquoise (0) ou médinoise (1).\n\n`nbverses`: nombre de versets.\n\n### Fichiers de données\n\nCertains scripts utilisent des fichiers CSV contenant les données des sourates.\nDes points-virgules (`;`) séparent les valeurs. Tout fichier de données doit\navoir les colonnes suivantes, qui correspondent aux propriétés des sourates.\n\n```\nid;chronology;titlefr;titleen;period;nbverses\n```\n\nLe fichier de données [surahs.csv](surahs.csv), à la racine du dépôt, permet\nd'initialiser la base de données.\n\n### Dépendances\n\nLa commande suivante installe les dépendances de ce dépôt.\n```\npip install -r requirements.txt\n```\n\n### Scripts\n\nLes exemples d'exécution supposent l'existence de `db_config.json`, un fichier\nde configration pour la connexion à la base de données, à la racine du dépôt\nlocal de l'utilisateur. Ce fichier n'existe pas dans le dépôt distant;\nl'utilisateur doit le créer.\n\nLe drapeau `-c` fait ordonner à certains scripts les sourates chronologiquement\nplutôt que traditionnellement.\n\n#### Création de la base de données\n\n`load_surah_data.py` crée la base de données et charge les données des sourates\ndepuis un fichier CSV. L'utilisateur doit fournir le chemin de ce fichier comme\nargument.\n\nL'argument de connexion à un serveur MySQL `allow_local_infile` doit être vrai\n(`true`) pour `load_surah_data.py`. Autrement, ce script sera incapable de\ncharger les données dpuis un fichier et il lèvera une exception.\n\nAide:\n```\npython load_surah_data.py -h\n```\n\nExemple d'exécution:\n```\npython load_surah_data.py -d db_config.json -s surahs.csv\n```\n\n#### Suppression de la base de données\n\n`delete_database.py` supprime la base de données.\n\nAide:\n```\npython delete_database.py -h\n```\n\nExemple d'exécution:\n```\npython delete_database.py -d db_config.json\n```\n\n#### Écriture des données\n\n`dump_surah_data.py` écrit les données sur les sourates dans un fichier CSV.\n\nAide:\n```\npython dump_surah_data.py -h\n```\n\nExemple d'exécution:\n```\npython dump_surah_data.py -d db_config.json -s exemple.csv -c\n```\n\n#### Somme cumulative de la longueur des sourates\n\n`cumulength.py` parcourt les données des sourates, calculant pour chacune la\nsomme de sa longueur et de la longueur des sourates précédentes. Il calcule\naussi la proportion des versets que ces sommes cumulatives représentent.\n\nEnfin, ce script écrit ses résultats dans un fichier CSV. Ce fichier de données\ncontient deux colonnes supplémentaires: `cumulnbverses` et `cumulproportion`.\n\nAide:\n```\npython cumulength.py -h\n```\n\nExemple d'exécution:\n```\npython cumulength.py -d db_config.json -s exemple.csv -c -p 0\n```\n\n#### Longueur des sourates\n\n`plot_surah_length.py` produit un diagramme à bandes montrant la longueur des\nsourates.\n\nAide:\n```\npython plot_surah_length.py -h\n```\n\nExemple d'exécution:\n```\npython plot_surah_length.py -d db_config.json -l fr -c\n```\n\n#### Progression dans la lecture du Coran\n\n`plot_progression_in_reading.py` produit un graphique montrant la progression\ndans la lecture du Coran selon la dernière sourate entièrement lue.\n\nAide:\n```\npython plot_progression_in_reading.py -h\n```\n\nExemple d'exécution:\n```\npython plot_progression_in_reading.py -d db_config.json -l fr -c\n```\n\n## ENGLISH\n\nThis project is the result of an intellectual interest in the Quran. Scripts at\nthe repository's root communicate with a database containing information about\nthe 114 surahs of Islam's sacred book.\n\n### Connection to a MySQL server\n\nAll scripts connect to a MySQL server to access the database. The user must\nprovide as an argument the path to a JSON file that configures the connection.\nThe connection configuration file must match\n[this schema](src/database/db_config_schema.json).\n\nA valid configuration resembles the template below.\n```\n{\n  \"host\": \"host_name\",\n  \"user\": \"username\",\n  \"password\": \"password\",\n  \"allow_local_infile\": true\n}\n```\n\nEach property must correspond to a\n[connection argument](https://dev.mysql.com/doc/connector-python/en/connector-python-connectargs.html).\nArgument `allow_local_infile` is optional; its default value is `true`. The\nconfiguration may contain other properties than those indicated above.\n\n### Order of the surahs\n\nThe surahs' order in the Quran (the traditional order) does not match the\nchronological order of their revelation. When the surahs' data is extracted, it\ncan be ordered traditonnally or chronologically.\n\n### Properties of the surahs\n\n`id`: number in the traditional order and identifier.\n\n`chronology`: position in the chronological order.\n\n`titlefr`: title in French.\n\n`titleen`: title in English.\n\n`period`: Meccan (0) or Medinan (1).\n\n`nbverses`: number of verses.\n\n### Data files\n\nCertain sripts use CSV files that store data about the surahs. Semicolons (`;`)\nseparate the values. Any data file must have the following columns, which\ncorrespond to the surahs' properties.\n\n```\nid;chronology;titlefr;titleen;period;nbverses\n```\n\nData file [surahs.csv](surahs.csv), at the repository's root, allows to\ninitialize the database.\n\n### Dependencies\n\nThe following command installs this repository's dependencies.\n```\npip install -r requirements.txt\n```\n\n### Scripts\n\nThe execution examples suppose that `db_config.json`, a configuration file for\nthe connection to the database, exists at the user's local repository's root.\nThis file does not exist in the remote repository; the user must create it.\n\nFlag `-c` makes certain scripts order the surahs chronologically rather than\ntraditionnally.\n\n#### Database creation\n\n`load_surah_data.py` creates the database and loads the surahs' data from a CSV\nfile. The user must provide the path to this file as an argument.\n\nMySQL connection argument `allow_local_infile` must be `true` for\n`load_surah_data.py`. Otherwise, this script will be unable to load data from a\nfile and will raise an exception.\n\nHelp:\n```\npython load_surah_data.py -h\n```\n\nExecution example:\n```\npython load_surah_data.py -d db_config.json -s surahs.csv\n```\n\n#### Database deletion\n\n`delete_database.py` does what its name says.\n\nHelp:\n```\npython delete_database.py -h\n```\n\nExecution example:\n```\npython delete_database.py -d db_config.json\n```\n\n#### Data writing\n\n`dump_surah_data.py` writes the surahs' data in a CSV file.\n\nHelp:\n```\npython dump_surah_data.py -h\n```\n\nExecution example:\n```\npython dump_surah_data.py -d db_config.json -s example.csv -c\n```\n\n#### Cumulative sum of the surahs' length\n\n`cumulength.py` goes through the surahs' data and, for each, calculates the sum\nof its length and the previous surahs' length. It also calculates the\nproportion of the verses that these cumulative sums represent.\n\nFinally, this script writes its results in a CSV file. This data file contains\ntwo additional columns: `cumulnbverses` and `cumulproportion`.\n\nHelp:\n```\npython cumulength.py -h\n```\n\nExecution example:\n```\npython cumulength.py -d db_config.json -s example.csv -c -p 0\n```\n\n#### Surah length\n\n`plot_surah_length.py` produces a bar diagram showing the surahs' length.\n\nHelp:\n```\npython plot_surah_length.py -h\n```\n\nExecution example:\n```\npython plot_surah_length.py -d db_config.json -l en -c\n```\n\n#### Progression in reading the Quran\n\n`plot_progression_in_reading.py` produces a graph showing the progression in\nthe Quran's reading based on the last surah entirely read.\n\nHelp:\n```\npython plot_progression_in_reading.py -h\n```\n\nExecution example:\n```\npython plot_progression_in_reading.py -d db_config.json -l en -c\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrv96%2Fsurahdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrv96%2Fsurahdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrv96%2Fsurahdb/lists"}