diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..ff7535b --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,59 @@ +# 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: +```bash +pip install git+https://github.com/your-username/thon.git +``` + +### Core Pattern +The library is designed around the `async for` pattern: +```python +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. \ No newline at end of file diff --git a/README.md b/README.md index e69de29..0d43c35 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,110 @@ +# Thon ⚡️ + +**Thon** is a lightweight, extensible Python library designed for processing Telegram sessions. It provides a clean, asynchronous interface to handle session conversion and automated processing tasks. + +--- + +## 📥 Installation + +Install the library directly from the repository: + +```bash +pip install git+https://github.com/your-username/thon.git +``` + +--- + +## 🛠 Usage Examples + +### 1. Basic Session Iteration +Iterate through your `.session` files automatically. Thon converts them on the fly and provides an authorized `telethon` client for each. + +```python +import asyncio +from pathlib import Path +from thon import Thon +from thon.models.options import ThonOptions + +async def main(): + # Folder containing your .session files + sessions_path = Path("my_sessions") + + # Basic options + options = ThonOptions(retries=5, timeout=15) + + async for thon_session in Thon(options, sessions_folder=sessions_path): + # thon_session.thon is an active ProcessThon instance + # thon_session.session contains session metadata + + me = thon_session.thon.me + print(f"Logged in as: {me.first_name} (@{me.username})") + + # Access the underlying Telethon client + client = thon_session.thon.client + await client.send_message('me', 'Hello from Thon!') + +asyncio.run(main()) +``` + +### 2. Searching for Verification Codes +A common task is waiting for a verification code (e.g., from Telegram or a bot). Thon has built-in support for this. + +```python +from thon.models.misc import ThonSearchCodeOptions + +async def wait_for_code(thon_instance): + search_options = ThonSearchCodeOptions( + wait_time=60, # How long to wait for the message (seconds) + date_delta=300, # Only look at messages from the last 5 minutes + regexp=r'\d{5}' # Custom regex for the code + ) + + code = await thon_instance.search_code(search_options) + if code: + print(f"Found code: {code}") + else: + print("Code not found.") +``` + +### 3. Handling Banned Sessions and Errors +You can provide a callback to handle errors and automatically move banned sessions to a separate folder. + +```python +def on_error(): + print("An error occurred with a session!") + +async def process_with_safety(): + options = ThonOptions() + bot = Thon( + options, + sessions_folder=Path("sessions"), + move_banned_folder=True, # Automatically moves banned sessions to sessions/banned/ + callback_error=on_error + ) + + async for thon_session in bot: + # Only valid, unbanned sessions reach here + pass +``` + +--- + +## 📁 Project Structure + +```text +thon/ +├── thon/ # Core package directory +│ ├── __init__.py # Library entry point (Thon class) +│ ├── converter.py # Session conversion logic +│ ├── process.py # Main processing logic (ProcessThon) +│ ├── models/ # Data models and options +│ └── utils.py # Utility functions +├── pyproject.toml # Build system and metadata +└── README.md # Documentation +``` + +--- + +## 📜 License + +This project is licensed under the MIT License. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 85e747f..fa9fd72 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,9 +11,6 @@ dependencies = [ "telethon>=1.42.0", ] -[project.scripts] -thon = "thon:main" - [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta"