aiogram-tool 1.2.2__tar.gz

aiogram_tool-1.2.2/.github/workflows/main.yml

@@ -0,0 +1,66 @@
+name: Run Tests
+
+on: 
+  push:
+    branches: ["master", "feature"]
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.11', '3.12']
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v5
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v10.0.1
+      with:
+        enable-cache: true
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run tests with pytest
+      run: uv run pytest
+
+  lint:
+    name: Ruff linter
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check lint
+        run: uv run ruff check
+
+      - name: Check format
+        run: uv run ruff format --check

aiogram_tool-1.2.2/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Publish release to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: false
+
+      - name: Build
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: false
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        run: uv publish

aiogram_tool-1.2.2/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.venv/
+dist/
+*_test.py
+.pytest_cache/

aiogram_tool-1.2.2/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.2
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

aiogram_tool-1.2.2/.python-version

@@ -0,0 +1 @@
+3.11

aiogram_tool-1.2.2/CONTRIBUTING.md

@@ -0,0 +1,213 @@
+# Contributing to aiogram_tool
+
+First off, thank you for considering contributing to **aiogram_tool**! 🎉
+It's people like you that make this project a great toolkit for the [aiogram 3.x](https://github.com/aiogram/aiogram) community.
+
+This document describes how to set up your development environment, run tests, follow the project's code style, and submit changes.
+
+## Table of Contents
+
+- [Ways to Contribute](#ways-to-contribute)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Enhancements](#suggesting-enhancements)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Running Tests](#running-tests)
+- [Code Style & Linting](#code-style--linting)
+- [Making Changes](#making-changes)
+- [Pull Request Guidelines](#pull-request-guidelines)
+- [Commit Messages](#commit-messages)
+- [Documentation](#documentation)
+- [License](#license)
+
+## Ways to Contribute
+
+You can help the project in many ways:
+
+- 🐛 Report bugs
+- 💡 Suggest new features or improvements
+- 📖 Improve or translate documentation (`docs/en/`, `docs/ru/`)
+- ✍️ Write or improve examples in `examples/`
+- 🧪 Add tests or increase test coverage
+- 🔧 Fix issues and submit pull requests
+
+## Reporting Bugs
+
+Before opening a bug report, please [search existing issues](https://github.com/shayzi3/aiotool/issues) to avoid duplicates.
+
+When creating a bug report, include:
+
+- A clear, descriptive title
+- Your Python version, aiogram version, and `aiogram_tool` version
+- Steps to reproduce the problem (a minimal code example is best)
+- Expected behavior vs. actual behavior
+- Full traceback, if applicable
+
+## Suggesting Enhancements
+
+Feature requests are welcome! Please open an issue and describe:
+
+- The problem you're trying to solve
+- Your proposed solution or API design
+- Any alternatives you've considered
+- Whether it fits the scope of the project (tools and utilities for aiogram 3.x)
+
+## Development Setup
+
+### Prerequisites
+
+- **Python 3.11+**
+- [**uv**](https://docs.astral.sh/uv/) — the package manager used by this project
+- **Git**
+- **Redis** (optional, but recommended — some tests use a Redis backend)
+
+### Getting Started
+
+1. Fork the repository and clone your fork:
+
+   ```bash
+   git clone https://github.com/<your-username>/aiotool.git
+   cd aiotool
+   ```
+
+2. Install dependencies (including dev tools):
+
+   ```bash
+   uv sync --all-extras --dev
+   ```
+
+3. Install the pre-commit hooks:
+
+   ```bash
+   uv run pre-commit install
+   ```
+
+   This ensures `ruff check --fix` and `ruff format` run automatically before each commit.
+
+## Project Structure
+
+```
+aiogram_tool/
+├── aiogram_tool/          # Main package source code
+│   ├── types.py           # Shared type definitions
+│   ├── storage/           # Storage backends (Memory, Redis, File)
+│   └── tools/             # Tools (depend, limit, callback_data, setup)
+├── docs/                  # Documentation (en/ and ru/)
+├── examples/              # Ready-to-run usage examples
+├── tests/                 # Test suite (pytest)
+├── pyproject.toml         # Project metadata and tool configuration
+└── .pre-commit-config.yaml
+```
+
+## Running Tests
+
+The test suite uses [pytest](https://docs.pytest.org/) with `pytest-asyncio` (asyncio mode is set to `auto`).
+
+```bash
+uv run pytest
+```
+
+Notes:
+
+- Some tests require a **Redis** instance available at `localhost:6379`. In CI, a Redis 7 service container is started automatically. Locally, you can run one with Docker:
+
+  ```bash
+  docker run -d -p 6379:6379 redis:7-alpine
+  ```
+
+- To run a specific test module or directory:
+
+  ```bash
+  uv run pytest tests/limit/
+  ```
+
+When adding new features, please add corresponding tests under `tests/`, mirroring the package structure.
+
+## Code Style & Linting
+
+This project uses [**ruff**](https://docs.astral.sh/ruff/) for both linting and formatting.
+
+Configuration highlights (see `pyproject.toml`):
+
+- Line length: **88**
+- Target version: **Python 3.11**
+- Quote style: **double quotes**
+- Enabled rule sets: `E4`, `E7`, `E9`, `F`, `I` (isort), `B` (bugbear), `UP` (pyupgrade)
+
+Run the linter and formatter manually:
+
+```bash
+uv run ruff check --fix
+uv run ruff format
+```
+
+Or verify without modifying files (as CI does):
+
+```bash
+uv run ruff check
+uv run ruff format --check
+```
+
+CI runs both a **test job** (Python 3.11 and 3.12) and a **lint job**, so please make sure both pass locally before opening a pull request.
+
+## Making Changes
+
+1. Create a new branch for your work:
+
+   ```bash
+   git checkout -b feature/my-feature
+   # or
+   git checkout -b fix/issue-123
+   ```
+
+2. Make your changes.
+3. Add or update tests for your changes.
+4. Update documentation (`docs/en/` and `docs/ru/`) and, if relevant, add an example in `examples/`.
+5. Run the linter, formatter, and tests:
+
+   ```bash
+   uv run ruff check
+   uv run ruff format --check
+   uv run pytest
+   ```
+
+6. Commit your changes (pre-commit hooks will run automatically) and push your branch.
+7. Open a pull request against the `master` branch.
+
+## Pull Request Guidelines
+
+- Keep pull requests focused — one feature or fix per PR.
+- Describe **what** you changed and **why**.
+- Reference related issues (e.g., `Fixes #123`).
+- Make sure all CI checks pass.
+- New public APIs should be documented and covered by tests.
+- Follow the existing code style and project structure.
+
+## Commit Messages
+
+Write clear, concise commit messages. We recommend the [Conventional Commits](https://www.conventionalcommits.org/) style:
+
+```
+feat: add token bucket rate limit option
+fix: handle empty callback data in LongCallbackData
+docs: update rate limiter documentation
+test: add tests for Redis storage backend
+refactor: simplify dependency resolution logic
+```
+
+## Documentation
+
+Documentation lives in `docs/` and is available in two languages:
+
+- `docs/en/` — English
+- `docs/ru/` — Russian
+
+If you add or change a feature, please update the documentation in **both** languages when possible. Runnable examples belong in `examples/`, organized by tool.
+
+## License
+
+By contributing to `aiogram_tool`, you agree that your contributions will be licensed under the same license as the project — see [LICENSE.md](LICENSE.md).
+
+---
+
+Thank you again for contributing! 💙

aiogram_tool-1.2.2/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dyadchenko Vladislav Sergeevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiogram_tool-1.2.2/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: aiogram-tool
+Version: 1.2.2
+Summary: Tools which doing work with aiogram simple
+Project-URL: Repository, https://github.com/shayzi3/aiogram_tool
+Project-URL: Contributing, https://github.com/shayzi3/aiogram_tool/blob/master/CONTRIBUTING.md
+Author-email: Vlad_shayzi1 <tecnomega@mail.ru>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: DI,aiogram,callback,cooldown,data,delay,dependency-injection,depends,limit,long,rate,throttling
+Requires-Python: >=3.11
+Requires-Dist: aiogram==3.29.1
+Requires-Dist: redis>=8.0.0
+Description-Content-Type: text/markdown
+
+# aiogram_tool
+
+A collection of powerful tools and utilities for [aiogram 3.x](https://github.com/aiogram/aiogram) — dependency injection, rate limiting, and long callback data support.
+
+## ✨ Features
+
+- **Dependency Injection** — inject dependencies into handlers with `Depends()`, similar to FastAPI. Supports classes, functions, scopes (`SINGLETON`, `REQUEST`, `TRANSIENT`), nested dependencies, and more.
+- **Rate Limiter** — limit how often handlers can be called. Three built-in algorithms: Fixed Window, Sliding Window, and Token Bucket. Works per-user or globally.
+- **Long Callback Data** — bypass Telegram's 64-byte `callback_data` limit. Pack large payloads into inline keyboard buttons transparently.
+- **Pluggable Storage** — Memory, Redis, and File storage backends for persisting rate-limit and callback data state.
+
+## 📦 Installation
+
+Requires **Python 3.11+** and **aiogram 3.x**.
+
+### pip
+
+```bash
+pip install aiogram_tool
+```
+
+### Poetry
+
+```bash
+poetry add aiogram_tool
+```
+
+### uv
+
+```bash
+uv add aiogram_tool
+```
+
+## 🚀 Quick Start
+
+Register tools on your dispatcher with `aiogram_tool_setup`:
+
+```python
+from aiogram import Bot, Dispatcher
+from aiogram_tool.tools.setup import aiogram_tool_setup
+from aiogram_tool.tools.depend import DependTool
+from aiogram_tool.tools.limit import RateLimitTool
+
+bot = Bot("YOUR_TOKEN_HERE")
+dp = Dispatcher()
+
+aiogram_tool_setup(dp, [DependTool(), RateLimitTool()])
+
+await dp.start_polling(bot)
+```
+
+## 🧰 Tools
+
+### Dependency Injection
+
+Inject dependencies into handlers via default argument values — no middleware boilerplate required.
+
+```python
+from aiogram_tool.tools.setup import aiogram_tool_setup
+from aiogram_tool.tools.depend import Depends, DependTool, ScopeRegistry, Scope
+
+scope_registry = ScopeRegistry()
+
+
+class CounterService:
+    def __init__(self) -> None:
+        self.count = 0
+
+    async def __call__(self, context) -> dict:
+        self.count += 1
+        return {"current_count": self.count}
+
+
+counter = CounterService()
+scope_registry.register(counter, Scope.REQUEST)
+
+# Pass the registry to the tool during setup
+aiogram_tool_setup(dp, [DependTool(scope_registry=scope_registry)])
+
+
+@dp.message(CommandStart())
+async def start_handler(message: Message, stats: dict = Depends(counter)):
+    await message.answer(f"Pressed: {stats['current_count']} times")
+```
+
+Highlights:
+
+- Works with functions, class-functors, and `__init__` methods
+- Scopes: `SINGLETON`, `REQUEST`, `TRANSIENT` (via `ScopeRegistry`)
+- Nested dependencies (`subdepends`), `From` extractor, `DependFilter`, and `DependExit`
+
+📖 Full documentation: [EN](docs/en/depend.md) | [RU](docs/ru/depend.md)
+
+### Rate Limiter
+
+Limit handler calls with three built-in algorithms:
+
+```python
+from datetime import timedelta
+from aiogram_tool.tools.limit import RateLimitTool, RateLimitFilter
+from aiogram_tool.tools.limit.rate_limit import SlidingWindowRateLimit
+
+
+@dp.message(
+    Command("ping"),
+    # 3 requests per 10 seconds per user
+    RateLimitFilter(
+        rate_limit=SlidingWindowRateLimit(
+            requests=3,
+            time=timedelta(seconds=10),
+        )
+    ),
+)
+async def ping_handler(message: Message):
+    await message.answer("Pong!")
+```
+
+Available algorithms:
+
+| Algorithm | Description |
+|---|---|
+| `FixedWindowRateLimit` | N requests per fixed time window |
+| `SlidingWindowRateLimit` | More accurate; prevents bursts at window edges |
+| `TokenBucketRateLimit` | Bucket of tokens that refills over time |
+
+Extras:
+
+- `all_users=True` — apply the limit globally instead of per-user
+- `key="..."` — custom rate-limit key
+- Custom `RateLimitAnswer` — control the response when the limit is exceeded
+- Redis storage — share limits across bot restarts and multiple instances
+
+📖 Full documentation: [EN](docs/en/limit.md) | [RU](docs/ru/limit.md)
+
+### Long Callback Data
+
+Telegram limits `callback_data` to **64 bytes**. `LongCallbackData` automatically stores oversized payloads and restores them when the callback arrives — with the same familiar aiogram API.
+
+```python
+from aiogram import Bot, Dispatcher, F
+from aiogram.filters import CommandStart
+from aiogram.types import (
+    CallbackQuery,
+    InlineKeyboardButton,
+    InlineKeyboardMarkup,
+    Message,
+)
+from aiogram_tool.tools.callback_data import LongCallbackData
+
+bot = Bot("YOUR_TOKEN_HERE")
+dp = Dispatcher()
+
+
+class MyData(LongCallbackData, prefix="mydata"):
+    mode: str
+    payload: str
+
+
+@dp.message(CommandStart())
+async def start_handler(message: Message):
+    # Short data is packed as usual; long data is stored transparently
+    short_cb = await MyData(mode="short", payload="Hello!").pack_long()
+    long_cb = await MyData(mode="long", payload="A" * 200).pack_long()
+
+    await message.answer(
+        "Choose an action:",
+        reply_markup=InlineKeyboardMarkup(
+            inline_keyboard=[
+                [InlineKeyboardButton(text="Short data", callback_data=short_cb)],
+                [InlineKeyboardButton(text="Long data", callback_data=long_cb)],
+            ]
+        ),
+    )
+
+
+# Filter exactly like standard aiogram CallbackData
+@dp.callback_query(MyData.filter(F.mode == "long"))
+async def handler(query: CallbackQuery, callback_data: MyData):
+    # Original data is fully available despite the 64-byte limit
+    await query.answer(text=f"Received: {callback_data.payload}")
+```
+
+By default data is kept in in-memory storage. Use Redis to persist it across restarts:
+
+```python
+from redis.asyncio import Redis as AsyncRedis
+from aiogram_tool.storage import AsyncRedisLockStorage
+
+
+class PersistentData(LongCallbackData, prefix="redis"):
+    _storage = AsyncRedisLockStorage(redis=AsyncRedis(), expire=3600)
+    user_id: int
+    big_context: str
+```
+
+📖 Full documentation: [EN](docs/en/callback_data.md) | [RU](docs/ru/callback_data.md)
+
+## 💾 Storage Backends
+
+| Storage | Persistence | Lock support |
+|---|---|---|
+| `MemoryStorage` / `MemoryLockStorage` | In-memory | ✅ |
+| `AsyncRedisStorage` / `AsyncRedisLockStorage` | Redis (survives restarts) | ✅ |
+| `FileStorage` / `FileLockStorage` | Local files | ✅ |
+
+## 📁 Examples
+
+Ready-to-run examples are available in the [`examples/`](examples/) directory:
+
+- [Dependency Injection](examples/depend/) — classes, scopes, overrides, sub-dependencies
+- [Rate Limiting](examples/limit/) — basic usage, algorithms, advanced configuration
+- [Callback Data](examples/callback_data/) — basic usage, custom answers, Redis storage
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## 📄 License
+
+This project is licensed under the terms of the [LICENSE.md](LICENSE.md).