trojvn
0761e8ff94
Add comprehensive documentation for the Thon project, including project overview, architecture, usage examples, and development conventions. Update the README.md file to provide clear installation instructions, usage examples, and project structure. Remove the unused CLI entry point from pyproject.toml.
59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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. |