itisFarzinBot

A lightweight, modular, strictly-typed asynchronous Telegram bot framework built for the modern Python ecosystem.

Core Architecture

• Async-First: Built from the ground up leveraging concurrent, non-blocking I/O operations.
• Plug & Play Extensibility: Decoupled core logic supporting dynamic module loading. Seamlessly integrates with the official itisFarzinBotPlugins ecosystem.
• Strictly Typed: Type-hinted codebase passing strict pyrefly checks and ruff linting.

Getting Started

Prerequisites

• Python 3.10+
• uv package manager
• Telegram API credentials (api_id and api_hash)
• A bot token from @BotFather

Manual Installation

1. Clone the repository:

git clone https://github.com/6AMStuff/itisFarzinBot.git
cd itisFarzinBot

2. Install dependencies:

uv sync --locked

For faster MTProto encryption, include the full extra: uv sync --locked --extra full

3. Configure the bot (see Configuration).
4. Run the bot:

uv run -m bot

Docker Setup

Run the bot container:

docker run -d \
  --name itisfarzinbot \
  -v ./config:/app/config \
  -v ./plugins:/app/plugins \
  ghcr.io/6amstuff/itisfarzinbot:latest

Configuration

The bot reads its settings from config/config.yaml. Start from the bundled sample:

cp config/config.sample.yaml config/config.yaml

Then edit config/config.yaml. At minimum, set api_id, api_hash, and bot_token.

Option	Description
client_name	Session name for the Telegram client.
api_id / api_hash	Telegram API credentials from my.telegram.org.
bot_token	Bot token from @BotFather.
in_memory	Keep the session in memory instead of writing it to disk.
plugins_folder	Directory plugins are loaded from.
log_level	Logging level as a Python numeric level (e.g. 20 = INFO).
log_max_size_mb	Maximum size of a log file before it rotates.
log_backup_count	Number of rotated log files to keep.
admins	Space-separated list of admin usernames.
tz	Timezone as an IANA name (e.g. Europe/London).
proxy	Proxy URL for the client (e.g. socks5://127.0.0.1:8080).
use_system_proxy	Fall back to the system proxy when proxy is unset.
cmd_prefixes	Space-separated command prefixes (e.g. . /).
db_uri	SQLAlchemy database URI.
plugins_repo	Git repository used to fetch plugins.

Plugins

Users can expand their bot's functionality by obtaining plugins from the official repository: itisFarzinBotPlugins.

Development

Install the development dependencies and run the same checks as CI:

uv sync --locked --extra dev
uv run ruff check        # lint
uv run pyrefly check     # type check

Enable the git hooks once to run ruff, pyrefly, and commit-message checks automatically:

uv run pre-commit install

Commits follow the Conventional Commits style, enforced on commit by commitizen.

Contributing

Contributions to the main bot framework are welcome! Please open issues or submit pull requests for enhancements or bug fixes. For plugin development, please refer to the plugins repository.

License

This project is licensed under the MIT License. See LICENSE for details.