Add Quran local translation JSON support, public-domain Quran scrapers, and misc enhancements for IslamBot

.gitignore

@@ -1,4 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+## Repo-specific
 config.ini
 .idea
-__pycache__
-venv

example_config.ini

@@ -14,4 +14,7 @@ server_translations_table_name =
 server_tafsir_table_name =
 server_atafsir_table_name =
 server_prayer_times_table_name =
-user_prayer_times_table_name =
+user_prayer_times_table_name =
+
+[general]
+local_bot_use = false

main.py

@@ -9,6 +9,8 @@
 config = configparser.ConfigParser()
 config.read('config.ini')
 
+local_bot_use = config.getboolean('general', 'local_bot_use', fallback=False)
+
 token = config['IslamBot']['token']
 
 description = "A Discord bot with Islamic utilities. View Qur'an, hadith, prayer times and more."
@@ -44,9 +46,13 @@ def __init__(self) -> None:
             "tafsir.tafsir",
             "miscellaneous.reload",
             "miscellaneous.help",
-            "miscellaneous.TopGG" # Remove if using the bot locally
         ]
 
+        token_topgg = config['APIs'].get('top.gg',"").strip()
+        if token_topgg and not local_bot_use:
+            self.initial_extensions.append("miscellaneous.TopGG")
+
+
     async def setup_hook(self):
         self.session = aiohttp.ClientSession()
         for ext in self.initial_extensions:
@@ -55,12 +61,13 @@ async def setup_hook(self):
     async def on_ready(self):
         print(f'Logged in as {bot.user.name} ({bot.user.id}) on {len(bot.guilds)} servers')
 
-        # Sync commands globally
-        await bot.tree.sync(guild=None)
-
-        # If you are using the bot locally, uncomment the below and comment out the statement above so that commands
-        # only sync to your server. Global syncs are slow to propagate and are strictly rate-limited.
-        # await bot.tree.sync(guild=discord.Object(308241121165967362))
+        if(local_bot_use):
+            # If you are using the bot locally, commands should
+            # only sync to your server. Global syncs are slow to propagate and are strictly rate-limited.
+            await bot.tree.sync(guild=discord.Object(308241121165967362))
+        else:
+            # Sync commands globally
+            await bot.tree.sync(guild=None)
 
         # Starting this in the setup hook causes a deadlock as before_presence_update calls wait_until_ready()
         update_presence.start()

quran/quran.py

@@ -10,6 +10,8 @@
 from utils.errors import InvalidTranslation, respond_to_interaction_error
 from utils.utils import convert_to_arabic_number, convert_to_superscript_number, get_site_json
 
+from quran.quran_local_translations import LocalTranslations
+
 TOO_LONG = "This passage was too long to send."
 
 ICON = 'https://i.imgur.com/cIhpv80.png'
@@ -138,20 +140,42 @@
     'mukhtasar_vietnamese': TranslationInfo(id=177, fullname="Al-Mukhtasar (Vietnamese)"),  # Vietnamese
 }
 
+# ---------------------------------------------------------------------------
+# Optional ALIASES for the keys in `translation_list`.
+# The *left‑hand side* is what the user may type; the *right‑hand side*
+# **must** be an existing key in `translation_list`.
+# ---------------------------------------------------------------------------
+translation_aliases: dict[str, str] = {
+    'clear':        'khattab',           # "clear" ➜ Dr Mustafa Khattab, Clear Qur’an
+    'saheeh':       'sahih',
+    'sablukov':     'sablukov_vt'        # default 'sablukov' translation is the modern language one
+}
 
 class Translation:
-    def __init__(self, key):
-        self.id = self.get_translation_id(key)
+    def __init__(self, key: str):
+        # keep the canonical identifier so other code can rely on it
+        self.key = translation_aliases.get(key.lower().strip(), key.lower().strip())
+        self.id  = self.get_translation_id(self.key)
 
     @staticmethod
-    def get_translation_id(key):
+    def get_translation_id(key: str) -> int | None:
+        key = key.lower().strip()                     # normalise
+        key = translation_aliases.get(key, key)       # alias → canonical
+
+        # 1/3 remote translations that use the Qur’an‑com API
         if key in translation_list:
-            return translation_list[key].id
+            return translation_list[key].id      # normal path
+
+        # 2/3 local JSON translations that live in ./quran_local_translations
+        local_ids = LocalTranslations().get_all_ids()
+        if key in local_ids:
+            # local files don’t need an external numeric ID
+            return None
 
+        # 3/3 fall back: try to treat the user string as a *full name*
         translation_id = Translation.get_id_from_fullname(key)
         if translation_id is None:
             raise InvalidTranslation
-
         return translation_id
 
     @staticmethod
@@ -180,23 +204,54 @@ def __init__(self, interaction: discord.Interaction, ref: str, is_arabic: bool,
         self.ref = QuranReference(ref=ref, allow_multiple_verses=True, reveal_order=False)
         self.is_arabic = is_arabic
         self.format_paragraph = separate_verses is False
+
+        self.local_translations = LocalTranslations()
+
         if translation_key is not None:
-            self.translation = Translation(translation_key)
+            self.translation     = Translation(translation_key)
+            self.translation_key = self.translation.key
 
         self.regular_url = 'https://api.quran.com/api/v4/quran/translations/{}?verse_key={}:{}'
         self.arabic_url = 'https://api.quran.com/api/v4/quran/verses/uthmani?verse_key={}'
         self.footnote_url = 'https://api.qurancdn.com/api/qdc/foot_notes/{}' # unofficial API
         self.verse_ayah_dict = {}
         self.footnotes = []
-    
+
     def clean_text(self, text):
         text = re.sub(CLEAN_HTML_REGEX, ' ', text)  # remove HTML tags
         text = text.replace('"', '"')  # replace """ with quotation marks
         return text
 
     async def get_verses(self):
+        use_local_only = self.translation_key in self.local_translations.get_all_ids()
+
         for ayah in self.ref.ayat_list:
-            json = await get_site_json(self.regular_url.format(self.translation.id, self.ref.surah, ayah))
+            # --- 1/3 try the local JSON first ---
+            local_text = self.local_translations.get_verse(
+                self.translation_key, self.ref.surah, ayah
+            )
+            if local_text:
+                self.verse_ayah_dict[f'{self.ref.surah}:{ayah}'] = local_text
+                if not hasattr(self, 'translation_name'):
+                    self.translation_name = (
+                        self.local_translations.get_translation_name(self.translation_key)
+                        or self.translation_key
+                    )
+                continue
+
+            # --- 2/3 if it’s a local translation and verse is missing, just skip ---
+            if use_local_only:
+                continue        #   or: raise an error / fall back — your choice
+
+            # --- 3/3 fall back to the Qurʼan.com API for remote translations ---
+            if self.translation.id is None:          # defensive guard
+                raise InvalidTranslation(
+                    f"No numeric id for translation '{self.translation_key}'"
+                )
+
+            json = await get_site_json(
+                self.regular_url.format(self.translation.id, self.ref.surah, ayah)
+            )
             text = json['translations'][0]['text']
 
             # Process footnotes: replace <sup> tags with superscript numbers
@@ -377,6 +432,9 @@ async def raquran(self, interaction: discord.Interaction):
     async def set_translation(self, interaction: discord.Interaction, translation: str):
         await interaction.response.defer(thinking=True, ephemeral=True)
 
+        # accept an alias in /settranslation
+        translation = translation_aliases.get(translation.lower(), translation.lower())
+
         translation_id = Translation.get_translation_id(translation)
         # this is so when giving success message, it says it sets it to the actual translation instead of user's typos
         # e.g user gives `khatab` but it will set it to `khattab` and tell the user the bot set it to `khattab`
@@ -387,8 +445,18 @@ async def set_translation(self, interaction: discord.Interaction, translation: s
     @quran.autocomplete('translation')
     @rquran.autocomplete('translation')
     @set_translation.autocomplete('translation')
-    async def translation_autocomplete_callback(self, interaction: discord.Interaction, current: int):
-        closest_matches = [match[0] for match in process.extract(current, [v.fullname for v in translation_list.values()], scorer=fuzz.partial_ratio, limit=5)]
+    async def translation_autocomplete_callback(self, interaction: discord.Interaction, current: str):
+        local_trans = LocalTranslations()
+        all_local = local_trans.get_all_ids()
+
+        all_aliases  = list(translation_aliases.keys())
+
+        # Extract names for both online and local translations
+        online_names = [trans.fullname for trans in translation_list.values()]
+        local_names = [local_trans.get_translation_name(tid) for tid in all_local]
+        all_names = online_names + local_names + all_aliases
+
+        closest_matches = [match[0] for match in process.extract(current, all_names, scorer=fuzz.partial_ratio, limit=5)]
         choices = [discord.app_commands.Choice(name=match, value=match) for match in closest_matches]
         return choices
 
@@ -444,4 +512,3 @@ async def on_error(self, interaction: discord.Interaction, error: discord.app_co
 
 async def setup(bot):
     await bot.add_cog(Quran(bot))
-