thon/GEMINI.md

GEMINI.md - Project Context: Thon

Project Overview

Thon is a Python library for converting and processing Telegram sessions. It is designed to be integrated into other projects as a dependency. It leverages telethon to handle .session files, converting them into a structured JSON format and providing an asynchronous framework for automated session management.

Main Technologies

• Python 3.10+
• Telethon: Core library for Telegram interaction.
• aiofiles: Asynchronous file operations.
• asyncio: Powers the asynchronous iterator and processing logic.
• Setuptools: Build system for packaging.

---

Architecture and Key Modules

• thon.Thon: The main class and asynchronous iterator. Orchestrates the flow from raw session files to an active, authorized client.
• thon.converter.Converter: Internal module that transforms raw .session files into JSON metadata files (containing string_session and proxy info).
• thon.process.ProcessThon: A context manager that wraps a telethon.TelegramClient. It handles connection, authorization checks, and provides high-level methods like search_code.
• thon.models: Organized data structures:
  • ThonOptions: Configuration for retries, timeouts, and checks.
  • ThonSession: The object yielded by the iterator, containing both metadata and the processing instance.
• thon.utils: Shared utilities for JSON I/O, regex extraction, and file system management.

---

Usage and Integration

Installation

Install as a library:

pip install git+https://github.com/your-username/thon.git

Core Pattern

The library is designed around the async for pattern:

from thon import Thon
from thon.models.options import ThonOptions

async def run():
    options = ThonOptions(retries=5)
    async for ts in Thon(options, sessions_folder=Path("path/to/sessions")):
        async with ts.thon as client:
            # client is an authorized Telethon instance
            pass

---

Development Conventions

• Asynchronous Flow: All I/O and network calls must be async.
• Session Management: Automatically handles "banned" status by moving files if configured.
• Proxy Support: Integrated into the connection logic via thon.proxy.
• Zero CLI: The project does not provide a CLI entry point by design.

---

Important Notes

• The library uses a hardcoded api_id and api_hash in Converter for internal session string generation, but allows external apps to use their own via session data.
• Banned sessions are moved to a banned subfolder relative to the sessions directory by default.