refactor: improve language normalization and date handling utilities

- Introduced a new `normalize_lang` function to standardize language codes across the application, ensuring consistent handling of user language preferences.
- Refactored date handling utilities by adding `parse_utc_iso` and `parse_utc_iso_naive` functions for better parsing of ISO 8601 date strings, enhancing timezone awareness.
- Updated various modules to utilize the new language normalization and date parsing functions, improving code clarity and maintainability.
- Enhanced error handling in date validation to raise specific `DateRangeValidationError` exceptions, providing clearer feedback on validation issues.
- Improved test coverage for date range validation and language normalization functionalities, ensuring robustness and reliability.

duty_teller/handlers/commands.py

@@ -11,8 +11,8 @@ from duty_teller.db.repository import (
     get_or_create_user,
     set_user_phone,
     create_calendar_token,
-    is_admin_for_telegram_user,
 )
+from duty_teller.handlers.common import is_admin_async
 from duty_teller.i18n import get_lang, t
 from duty_teller.utils.user import build_full_name
 
@@ -151,13 +151,7 @@ async def help_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         t(lang, "help.calendar_link"),
         t(lang, "help.pin_duty"),
     ]
-
-    def check_admin() -> bool:
-        with session_scope(config.DATABASE_URL) as session:
-            return is_admin_for_telegram_user(session, update.effective_user.id)
-
-    is_admin_user = await asyncio.get_running_loop().run_in_executor(None, check_admin)
-    if is_admin_user:
+    if await is_admin_async(update.effective_user.id):
         lines.append(t(lang, "help.import_schedule"))
     await update.message.reply_text("\n".join(lines))
 

duty_teller/handlers/common.py

@@ -0,0 +1,24 @@
+"""Shared handler helpers (e.g. async admin check)."""
+
+import asyncio
+
+import duty_teller.config as config
+from duty_teller.db.repository import is_admin_for_telegram_user
+from duty_teller.db.session import session_scope
+
+
+async def is_admin_async(telegram_user_id: int) -> bool:
+    """Check if Telegram user is admin (username or phone). Runs DB check in executor.
+
+    Args:
+        telegram_user_id: Telegram user id.
+
+    Returns:
+        True if user is in ADMIN_USERNAMES or their stored phone is in ADMIN_PHONES.
+    """
+
+    def _check() -> bool:
+        with session_scope(config.DATABASE_URL) as session:
+            return is_admin_for_telegram_user(session, telegram_user_id)
+
+    return await asyncio.get_running_loop().run_in_executor(None, _check)

duty_teller/handlers/import_duty_schedule.py

@@ -7,7 +7,7 @@ from telegram import Update
 from telegram.ext import CommandHandler, ContextTypes, MessageHandler, filters
 
 from duty_teller.db.session import session_scope
-from duty_teller.db.repository import is_admin_for_telegram_user
+from duty_teller.handlers.common import is_admin_async
 from duty_teller.i18n import get_lang, t
 from duty_teller.importers.duty_schedule import (
     DutyScheduleParseError,
@@ -24,13 +24,7 @@ async def import_duty_schedule_cmd(
     if not update.message or not update.effective_user:
         return
     lang = get_lang(update.effective_user)
-
-    def check_admin() -> bool:
-        with session_scope(config.DATABASE_URL) as session:
-            return is_admin_for_telegram_user(session, update.effective_user.id)
-
-    is_admin_user = await asyncio.get_running_loop().run_in_executor(None, check_admin)
-    if not is_admin_user:
+    if not await is_admin_async(update.effective_user.id):
         await update.message.reply_text(t(lang, "import.admin_only"))
         return
     context.user_data["awaiting_handover_time"] = True
@@ -45,13 +39,7 @@ async def handle_handover_time_text(
         return
     if not context.user_data.get("awaiting_handover_time"):
         return
-
-    def check_admin() -> bool:
-        with session_scope(config.DATABASE_URL) as session:
-            return is_admin_for_telegram_user(session, update.effective_user.id)
-
-    is_admin_user = await asyncio.get_running_loop().run_in_executor(None, check_admin)
-    if not is_admin_user:
+    if not await is_admin_async(update.effective_user.id):
         return
     lang = get_lang(update.effective_user)
     text = update.message.text.strip()
@@ -78,13 +66,7 @@ async def handle_duty_schedule_document(
     handover = context.user_data.get("handover_utc_time")
     if not handover:
         return
-
-    def check_admin() -> bool:
-        with session_scope(config.DATABASE_URL) as session:
-            return is_admin_for_telegram_user(session, update.effective_user.id)
-
-    is_admin_user = await asyncio.get_running_loop().run_in_executor(None, check_admin)
-    if not is_admin_user:
+    if not await is_admin_async(update.effective_user.id):
         return
     if not (update.message.document.file_name or "").lower().endswith(".json"):
         await update.message.reply_text(t(lang, "import.need_json"))