feat(rewrite-v2): add python_italy_bot application

- Entry point, config, handlers (welcome, moderation, spam)
- Services: captcha, spam detector, moderation
- DB: in-memory and Postgres repositories

Author: MattiaFailla

src/python_italy_bot/__init__.py

@@ -0,0 +1,3 @@
+"""Python Italy Telegram Bot - Official bot for Italian Python community groups."""
+
+__version__ = "0.1.0"

src/python_italy_bot/assets/.gitkeep

@@ -0,0 +1,51 @@
+"""Configuration loaded from environment variables."""
+
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def _get_env(key: str, default: str | None = None) -> str:
+    value = os.environ.get(key, default)
+    if value is None:
+        raise ValueError(f"Missing required environment variable: {key}")
+    return value
+
+
+def _get_optional_env(key: str, default: str | None = None) -> str | None:
+    return os.environ.get(key, default)
+
+
+def _get_optional_int(key: str) -> int | None:
+    val = os.environ.get(key)
+    if val is None or val.strip() == "":
+        return None
+    try:
+        return int(val.strip())
+    except ValueError:
+        return None
+
+
+def _get_int_list(key: str) -> list[int]:
+    val = os.environ.get(key)
+    if val is None or val.strip() == "":
+        return []
+    return [int(x.strip()) for x in val.split(",") if x.strip()]
+
+
+class Settings:
+    """Bot configuration from environment."""
+
+    def __init__(self) -> None:
+        self.telegram_bot_token: str = _get_env("TELEGRAM_BOT_TOKEN")
+        self.database_url: str | None = _get_optional_env("DATABASE_URL")
+        self.captcha_secret_command: str = _get_optional_env(
+            "CAPTCHA_SECRET_COMMAND", "python-italy"
+        )
+        self.captcha_file_path: str = _get_optional_env(
+            "CAPTCHA_FILE_PATH", "assets/regolamento.md"
+        )
+        self.main_group_id: int | None = _get_optional_int("MAIN_GROUP_ID")
+        self.local_group_ids: list[int] = _get_int_list("LOCAL_GROUP_IDS")

src/python_italy_bot/config.py

@@ -0,0 +1,32 @@
+"""Database abstraction layer."""
+
+from .base import AsyncRepository, Repository
+from .in_memory import InMemoryRepository
+from .models import Ban, Mute, Report
+from .postgres import PostgresRepository
+
+__all__ = [
+    "Repository",
+    "AsyncRepository",
+    "InMemoryRepository",
+    "PostgresRepository",
+    "Ban",
+    "Mute",
+    "Report",
+    "create_repository",
+]
+
+
+async def create_repository(database_url: str | None) -> AsyncRepository:
+    """Create a repository based on the database URL.
+
+    Returns PostgresRepository if database_url is a PostgreSQL URL,
+    otherwise returns InMemoryRepository.
+    """
+    if database_url and database_url.startswith("postgresql"):
+        from psycopg_pool import AsyncConnectionPool
+
+        pool = AsyncConnectionPool(database_url, open=False)
+        await pool.open()
+        return PostgresRepository(pool)
+    return InMemoryRepository()

src/python_italy_bot/db/__init__.py

@@ -0,0 +1,175 @@
+"""Abstract repository interface for persistence."""
+
+from abc import ABC, abstractmethod
+
+
+class Repository(ABC):
+    """Abstract interface for data persistence (sync)."""
+
+    @abstractmethod
+    def add_pending_verification(self, user_id: int, chat_id: int) -> None:
+        """Record that user joined chat and needs to complete captcha."""
+        ...
+
+    @abstractmethod
+    def get_pending_chats(self, user_id: int) -> list[int]:
+        """Return chat IDs where user is pending verification."""
+        ...
+
+    @abstractmethod
+    def remove_pending(self, user_id: int, chat_id: int) -> bool:
+        """Remove pending verification. Returns True if existed."""
+        ...
+
+    @abstractmethod
+    def is_user_verified(self, user_id: int, chat_id: int) -> bool:
+        """Check if user has completed captcha for the given chat."""
+        ...
+
+    @abstractmethod
+    def mark_user_verified(self, user_id: int, chat_id: int) -> None:
+        """Mark user as verified for the given chat."""
+        ...
+
+    @abstractmethod
+    def get_banned_users(self, chat_id: int) -> list[int]:
+        """Return user IDs banned in the given chat."""
+        ...
+
+    @abstractmethod
+    def add_ban(
+        self,
+        user_id: int,
+        chat_id: int,
+        admin_id: int,
+        reason: str | None = None,
+    ) -> None:
+        """Record a ban."""
+        ...
+
+    @abstractmethod
+    def remove_ban(self, user_id: int, chat_id: int) -> bool:
+        """Remove a ban. Returns True if ban existed."""
+        ...
+
+    @abstractmethod
+    def get_muted_users(self, chat_id: int) -> list[int]:
+        """Return user IDs currently muted in the given chat."""
+        ...
+
+    @abstractmethod
+    def add_mute(
+        self,
+        user_id: int,
+        chat_id: int,
+        admin_id: int,
+        reason: str | None = None,
+        until: int | None = None,
+    ) -> None:
+        """Record a mute. until is Unix timestamp or None for indefinite."""
+        ...
+
+    @abstractmethod
+    def remove_mute(self, user_id: int, chat_id: int) -> bool:
+        """Remove a mute. Returns True if mute existed."""
+        ...
+
+    @abstractmethod
+    def add_report(
+        self,
+        reporter_id: int,
+        reported_user_id: int,
+        chat_id: int,
+        message_id: int | None = None,
+        reason: str | None = None,
+    ) -> None:
+        """Record a report."""
+        ...
+
+
+class AsyncRepository(ABC):
+    """Abstract interface for data persistence (async)."""
+
+    @abstractmethod
+    async def add_pending_verification(self, user_id: int, chat_id: int) -> None:
+        """Record that user joined chat and needs to complete captcha."""
+        ...
+
+    @abstractmethod
+    async def get_pending_chats(self, user_id: int) -> list[int]:
+        """Return chat IDs where user is pending verification."""
+        ...
+
+    @abstractmethod
+    async def remove_pending(self, user_id: int, chat_id: int) -> bool:
+        """Remove pending verification. Returns True if existed."""
+        ...
+
+    @abstractmethod
+    async def is_user_verified(self, user_id: int, chat_id: int) -> bool:
+        """Check if user has completed captcha for the given chat."""
+        ...
+
+    @abstractmethod
+    async def mark_user_verified(self, user_id: int, chat_id: int) -> None:
+        """Mark user as verified for the given chat."""
+        ...
+
+    @abstractmethod
+    async def get_banned_users(self, chat_id: int) -> list[int]:
+        """Return user IDs banned in the given chat."""
+        ...
+
+    @abstractmethod
+    async def add_ban(
+        self,
+        user_id: int,
+        chat_id: int,
+        admin_id: int,
+        reason: str | None = None,
+    ) -> None:
+        """Record a ban."""
+        ...
+
+    @abstractmethod
+    async def remove_ban(self, user_id: int, chat_id: int) -> bool:
+        """Remove a ban. Returns True if ban existed."""
+        ...
+
+    @abstractmethod
+    async def get_muted_users(self, chat_id: int) -> list[int]:
+        """Return user IDs currently muted in the given chat."""
+        ...
+
+    @abstractmethod
+    async def add_mute(
+        self,
+        user_id: int,
+        chat_id: int,
+        admin_id: int,
+        reason: str | None = None,
+        until: int | None = None,
+    ) -> None:
+        """Record a mute. until is Unix timestamp or None for indefinite."""
+        ...
+
+    @abstractmethod
+    async def remove_mute(self, user_id: int, chat_id: int) -> bool:
+        """Remove a mute. Returns True if mute existed."""
+        ...
+
+    @abstractmethod
+    async def add_report(
+        self,
+        reporter_id: int,
+        reported_user_id: int,
+        chat_id: int,
+        message_id: int | None = None,
+        reason: str | None = None,
+    ) -> None:
+        """Record a report."""
+        ...
+
+    async def close(self) -> None:
+        """Close any resources (override if needed)."""
+        pass

src/python_italy_bot/db/base.py

@@ -0,0 +1,119 @@
+"""In-memory implementation of the repository (no persistent DB)."""
+
+from datetime import datetime, timezone
+
+from .base import AsyncRepository
+from .models import Ban, Mute, Report
+
+
+class InMemoryRepository(AsyncRepository):
+    """In-memory repository for development and testing."""
+
+    def __init__(self) -> None:
+        self._verified: set[tuple[int, int]] = set()
+        self._pending: set[tuple[int, int]] = set()
+        self._bans: list[Ban] = []
+        self._mutes: list[Mute] = []
+        self._reports: list[Report] = []
+
+    async def add_pending_verification(self, user_id: int, chat_id: int) -> None:
+        self._pending.add((user_id, chat_id))
+
+    async def get_pending_chats(self, user_id: int) -> list[int]:
+        return [c for u, c in self._pending if u == user_id]
+
+    async def remove_pending(self, user_id: int, chat_id: int) -> bool:
+        key = (user_id, chat_id)
+        if key in self._pending:
+            self._pending.discard(key)
+            return True
+        return False
+
+    async def is_user_verified(self, user_id: int, chat_id: int) -> bool:
+        return (user_id, chat_id) in self._verified
+
+    async def mark_user_verified(self, user_id: int, chat_id: int) -> None:
+        self._verified.add((user_id, chat_id))
+
+    async def get_banned_users(self, chat_id: int) -> list[int]:
+        return [b.user_id for b in self._bans if b.chat_id == chat_id]
+
+    async def add_ban(
+        self,
+        user_id: int,
+        chat_id: int,
+        admin_id: int,
+        reason: str | None = None,
+    ) -> None:
+        self._bans.append(
+            Ban(
+                user_id=user_id,
+                chat_id=chat_id,
+                admin_id=admin_id,
+                reason=reason,
+                created_at=datetime.now(timezone.utc),
+            )
+        )
+
+    async def remove_ban(self, user_id: int, chat_id: int) -> bool:
+        before = len(self._bans)
+        self._bans = [
+            b for b in self._bans if not (b.user_id == user_id and b.chat_id == chat_id)
+        ]
+        return len(self._bans) < before
+
+    async def get_muted_users(self, chat_id: int) -> list[int]:
+        now = datetime.now(timezone.utc)
+        return [
+            m.user_id
+            for m in self._mutes
+            if m.chat_id == chat_id and (m.until is None or m.until > now)
+        ]
+
+    async def add_mute(
+        self,
+        user_id: int,
+        chat_id: int,
+        admin_id: int,
+        reason: str | None = None,
+        until: int | None = None,
+    ) -> None:
+        until_dt = datetime.fromtimestamp(until, tz=timezone.utc) if until else None
+        self._mutes.append(
+            Mute(
+                user_id=user_id,
+                chat_id=chat_id,
+                admin_id=admin_id,
+                reason=reason,
+                until=until_dt,
+                created_at=datetime.now(timezone.utc),
+            )
+        )
+
+    async def remove_mute(self, user_id: int, chat_id: int) -> bool:
+        before = len(self._mutes)
+        self._mutes = [
+            m
+            for m in self._mutes
+            if not (m.user_id == user_id and m.chat_id == chat_id)
+        ]
+        return len(self._mutes) < before
+
+    async def add_report(
+        self,
+        reporter_id: int,
+        reported_user_id: int,
+        chat_id: int,
+        message_id: int | None = None,
+        reason: str | None = None,
+    ) -> None:
+        self._reports.append(
+            Report(
+                reporter_id=reporter_id,
+                reported_user_id=reported_user_id,
+                chat_id=chat_id,
+                message_id=message_id,
+                reason=reason,
+                created_at=datetime.now(timezone.utc),
+            )
+        )