vitrine-tg 0.1.0__tar.gz

vitrine_tg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 target111
+
+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.

vitrine_tg-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: vitrine-tg
+Version: 0.1.0
+Summary: A batteries-included framework on top of python-telegram-bot: typed callbacks, screens, DI, auth, conversations, and supervised workers.
+Keywords: telegram,bot,framework,python-telegram-bot,asyncio
+Author: target111
+Author-email: target111 <target111@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-telegram-bot[job-queue]>=22.8
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/target111/vitrine
+Project-URL: Repository, https://github.com/target111/vitrine
+Project-URL: Issues, https://github.com/target111/vitrine/issues
+Project-URL: Changelog, https://github.com/target111/vitrine/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# vitrine
+
+[![CI](https://github.com/target111/vitrine/actions/workflows/ci.yml/badge.svg)](https://github.com/target111/vitrine/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vitrine-tg)](https://pypi.org/project/vitrine-tg/)
+
+A framework for building Telegram bots with [python-telegram-bot](https://python-telegram-bot.org/) that doesn't get in your way.
+
+Handlers are just async functions. You get dependency injection, auth, robust message delivery, background workers, typed callbacks, rate limiting, and decent error handling -- the stuff every real bot needs. Everything from PTB stays accessible.
+
+```python
+from vitrine import Bot, Button, CallbackData, Screen
+
+bot = Bot(token="...")
+
+class MenuCB(CallbackData, prefix="menu"):
+    section: str
+
+@bot.command("start", description="Open the menu")
+async def start(update):
+    return Screen(text="Welcome!", keyboard=[[Button("Shop", callback=MenuCB(section="shop"))]])
+
+@bot.callback(MenuCB)
+async def menu(data: MenuCB):          # decoded, validated payload injected
+    return Screen(text=f"Section: {data.section}")
+
+bot.run()
+```
+
+## Install
+
+```bash
+uv add vitrine-tg
+# or
+pip install vitrine-tg
+```
+
+The distribution is named `vitrine-tg`; the import name is `vitrine`.
+
+## Local development
+
+```bash
+uv sync                                   # install deps (PTB 22, pydantic 2)
+uv run pytest                             # run tests
+BOT_TOKEN=... uv run python examples/small_bot.py
+BOT_TOKEN=... uv run python examples/launcher_bot.py
+BOT_TOKEN=... ADMIN_IDS=123 uv run python examples/shop/main.py
+```
+
+## Core features
+
+### Dependency injection (`vitrine.injection`)
+
+Handlers declare what they need by parameter name; the framework supplies it. Framework values (`update`, `context`, `bot`, `data`, `state`, `event`, `delivery`), your registered providers, command args, and middleware extras all live in one namespace:
+
+```python
+bot.provide_value("orders", OrderService(...))     # constants / singletons
+
+@bot.provide("session")                            # factories; may be async
+async def session(db):                             # ...and depend on each other
+    async with db.begin() as s:
+        yield s                                    # cleanup after handler
+
+@bot.callback(OrderCB)
+async def view_order(data: OrderCB, user: User, orders: OrderService, session):
+    ...
+```
+
+Dependencies are resolved once per handler call. Bad parameter names fail at startup, not production. `Depends(fn)` is available for explicit one-offs.
+
+### Identity & auth (`vitrine.auth`)
+
+You define the principal type. The framework handles resolve-once-per-update, caching, injection, and guards:
+
+```python
+auth = Auth(resolve_user, name="user",
+            roles=lambda u: u.roles, is_banned=lambda u: u.banned)
+bot = Bot(token, auth=auth)
+
+@bot.command("refund", scope="admin")
+@requires("support")          # or @admin_only
+async def refund(user: User, order_id: int): ...
+
+@bot.command("profile")
+@requires_principal          # resolver returned None? -> "not registered" UX
+async def profile(user: User): ...
+```
+
+Bans are enforced bot-wide. Guard failures turn into friendly error messages: a caller with no resolvable principal gets `NotRegisteredError` (point them at /start), one missing a role gets `NotAuthorizedError`. Any handler asking for `user` gets the same instance -- no re-fetching during an update.
+
+### Screens & delivery (`vitrine.screens`)
+
+A `Screen` is a value object (text + keyboard + media + options) that doesn't need an `Update` -- unit-test your views by just calling them. `Delivery` sends it three ways: reply, edit, or proactively to any chat. It handles the annoying stuff:
+
+- text↔media transitions send the new message first, then delete the old one
+- all media types are detected (photo/video/animation/document/audio/voice/video-note/sticker)
+- uploads are cached by content hash and re-sent as `file_id`; rejected IDs trigger exactly one retry
+- "message is not modified" errors are silently skipped; `fresh=True` forces a new message anyway
+
+Return a `Screen` from a handler and it renders automatically (edit for buttons, reply for commands). Or call `screen.render(update, context)` and `delivery.send(chat_id, screen)` manually.
+
+Screens can also carry a **persistent reply keyboard** — the launcher pattern:
+
+```python
+LAUNCHER = ReplyKeyboard([["🛍 Shop", "ℹ️ Help"]])          # persistent by default
+
+@bot.command("start")
+async def start():
+    return Screen(text="Welcome!", reply_keyboard=LAUNCHER)  # set once, sticks around
+
+@bot.reply_button("🛍 Shop")                                 # presses route like messages
+async def shop():
+    return shop_screen()                                     # jump here from anywhere
+```
+
+A message carries an inline *or* a reply keyboard, never both, and Telegram can't attach reply keyboards to edits — `Delivery` turns such edits into replaces automatically. `Screen(reply_keyboard=REMOVE_REPLY_KEYBOARD)` takes the keyboard away. See `examples/launcher_bot.py`.
+
+### Lifecycle & workers (`vitrine.workers`)
+
+```python
+@bot.on_startup
+async def warmup(delivery): ...
+
+@bot.worker(every=30)
+async def reconcile(orders, delivery):
+    for o in await orders.confirmed():
+        await delivery.send(o.chat_id, receipt_screen(o))
+
+@bot.worker()
+async def chain_watcher(feed): ...
+```
+
+Workers get DI, start after init, and shut down gracefully. Crashes restart automatically with exponential backoff -- no manual task supervision needed.
+
+## Features
+
+| Feature | Module | Details |
+|---|---|---|
+| Typed callbacks | `callbacks` | Pydantic models with a prefix. Stale/corrupt data returns "button expired" instead of crashing. Keyed encoding (`keyed=True`) uses query strings and tolerates schema changes; `unpack()` auto-detects either format so live buttons survive upgrades. |
+| Reply keyboards | `screens` | `ReplyKeyboard` value object (persistent + resized by default), `@bot.reply_button("label")` routes presses through the full pipeline, `REMOVE_REPLY_KEYBOARD` clears it. |
+| Markdown builder | `markdown` | Composable/nestable nodes, safe escaping for V1+V2, `raw()` escape hatch. |
+| Routers | `routing` | `@router.command/callback/message`, sub-routers, `router.raw()` for plain PTB handlers. |
+| Command args | `args` | Typed params from the signature; required/optional/`Greedy`; auto usage messages. |
+| Pagination | `pagination` | Implement `count()`/`fetch(offset, limit)`, use `Paginator` and `nav_row()` buttons. |
+| Conversations | `conversations` | Dataclass state per run, string transitions, timeout, `on_exit(reason)` hooks. Full DI/middleware/principal interop. |
+| Files/media | `media` | `download()` with timeout and cleanup; content-hash `file_id` cache shared with Screen rendering. |
+| Rate limiting | `ratelimit` | `@throttle(3, per=60)`, custom keys and custom behavior on limits. |
+| Logging | `logging` | Key=value format, one line per update, `audit()` convention. |
+| Errors | `errors` | `@bot.on_error(Type)` registry dispatched by MRO. Handlers can return a `Screen` to render into the current message. |
+| Command discovery | `commands` | Auto `/help` filtered by caller's scopes. `set_my_commands()` per scope. `hidden=True` for internal handlers. |
+| Middleware | `middleware` | `async def mw(event, call_next)` at bot or router scope. `event.extras` values become injectable. |
+
+## Example: scaled mode
+
+`examples/shop/` is a full app: a storefront with a **domain layer that never touches the bot layer** (`domain/`), views as pure functions (`domain -> Screen`), services injected into handlers, a `User` principal for guards and menus, a purchase conversation, admin commands, and a reconciler worker that messages buyers. Only `main.py` knows all the layers.
+
+## Escape hatches
+
+Not a fork or parallel dispatcher. `bot.build()` returns the PTB `Application` for webhooks. `router.raw(handler, group=...)` registers plain PTB handlers. `Screen.extra` passes kwargs to PTB's send methods. Everything from PTB stays accessible.
+
+## Testing
+
+Views are pure functions -- test them without a live bot. `Screen.content()`/`markup()` show what would be sent. `Delivery` accepts any object with `send`/`edit` methods (see `tests/conftest.py` for a mock). This repo has 102 tests that exercise dispatch and conversations the same way you can.

vitrine_tg-0.1.0/README.md

@@ -0,0 +1,162 @@
+# vitrine
+
+[![CI](https://github.com/target111/vitrine/actions/workflows/ci.yml/badge.svg)](https://github.com/target111/vitrine/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vitrine-tg)](https://pypi.org/project/vitrine-tg/)
+
+A framework for building Telegram bots with [python-telegram-bot](https://python-telegram-bot.org/) that doesn't get in your way.
+
+Handlers are just async functions. You get dependency injection, auth, robust message delivery, background workers, typed callbacks, rate limiting, and decent error handling -- the stuff every real bot needs. Everything from PTB stays accessible.
+
+```python
+from vitrine import Bot, Button, CallbackData, Screen
+
+bot = Bot(token="...")
+
+class MenuCB(CallbackData, prefix="menu"):
+    section: str
+
+@bot.command("start", description="Open the menu")
+async def start(update):
+    return Screen(text="Welcome!", keyboard=[[Button("Shop", callback=MenuCB(section="shop"))]])
+
+@bot.callback(MenuCB)
+async def menu(data: MenuCB):          # decoded, validated payload injected
+    return Screen(text=f"Section: {data.section}")
+
+bot.run()
+```
+
+## Install
+
+```bash
+uv add vitrine-tg
+# or
+pip install vitrine-tg
+```
+
+The distribution is named `vitrine-tg`; the import name is `vitrine`.
+
+## Local development
+
+```bash
+uv sync                                   # install deps (PTB 22, pydantic 2)
+uv run pytest                             # run tests
+BOT_TOKEN=... uv run python examples/small_bot.py
+BOT_TOKEN=... uv run python examples/launcher_bot.py
+BOT_TOKEN=... ADMIN_IDS=123 uv run python examples/shop/main.py
+```
+
+## Core features
+
+### Dependency injection (`vitrine.injection`)
+
+Handlers declare what they need by parameter name; the framework supplies it. Framework values (`update`, `context`, `bot`, `data`, `state`, `event`, `delivery`), your registered providers, command args, and middleware extras all live in one namespace:
+
+```python
+bot.provide_value("orders", OrderService(...))     # constants / singletons
+
+@bot.provide("session")                            # factories; may be async
+async def session(db):                             # ...and depend on each other
+    async with db.begin() as s:
+        yield s                                    # cleanup after handler
+
+@bot.callback(OrderCB)
+async def view_order(data: OrderCB, user: User, orders: OrderService, session):
+    ...
+```
+
+Dependencies are resolved once per handler call. Bad parameter names fail at startup, not production. `Depends(fn)` is available for explicit one-offs.
+
+### Identity & auth (`vitrine.auth`)
+
+You define the principal type. The framework handles resolve-once-per-update, caching, injection, and guards:
+
+```python
+auth = Auth(resolve_user, name="user",
+            roles=lambda u: u.roles, is_banned=lambda u: u.banned)
+bot = Bot(token, auth=auth)
+
+@bot.command("refund", scope="admin")
+@requires("support")          # or @admin_only
+async def refund(user: User, order_id: int): ...
+
+@bot.command("profile")
+@requires_principal          # resolver returned None? -> "not registered" UX
+async def profile(user: User): ...
+```
+
+Bans are enforced bot-wide. Guard failures turn into friendly error messages: a caller with no resolvable principal gets `NotRegisteredError` (point them at /start), one missing a role gets `NotAuthorizedError`. Any handler asking for `user` gets the same instance -- no re-fetching during an update.
+
+### Screens & delivery (`vitrine.screens`)
+
+A `Screen` is a value object (text + keyboard + media + options) that doesn't need an `Update` -- unit-test your views by just calling them. `Delivery` sends it three ways: reply, edit, or proactively to any chat. It handles the annoying stuff:
+
+- text↔media transitions send the new message first, then delete the old one
+- all media types are detected (photo/video/animation/document/audio/voice/video-note/sticker)
+- uploads are cached by content hash and re-sent as `file_id`; rejected IDs trigger exactly one retry
+- "message is not modified" errors are silently skipped; `fresh=True` forces a new message anyway
+
+Return a `Screen` from a handler and it renders automatically (edit for buttons, reply for commands). Or call `screen.render(update, context)` and `delivery.send(chat_id, screen)` manually.
+
+Screens can also carry a **persistent reply keyboard** — the launcher pattern:
+
+```python
+LAUNCHER = ReplyKeyboard([["🛍 Shop", "ℹ️ Help"]])          # persistent by default
+
+@bot.command("start")
+async def start():
+    return Screen(text="Welcome!", reply_keyboard=LAUNCHER)  # set once, sticks around
+
+@bot.reply_button("🛍 Shop")                                 # presses route like messages
+async def shop():
+    return shop_screen()                                     # jump here from anywhere
+```
+
+A message carries an inline *or* a reply keyboard, never both, and Telegram can't attach reply keyboards to edits — `Delivery` turns such edits into replaces automatically. `Screen(reply_keyboard=REMOVE_REPLY_KEYBOARD)` takes the keyboard away. See `examples/launcher_bot.py`.
+
+### Lifecycle & workers (`vitrine.workers`)
+
+```python
+@bot.on_startup
+async def warmup(delivery): ...
+
+@bot.worker(every=30)
+async def reconcile(orders, delivery):
+    for o in await orders.confirmed():
+        await delivery.send(o.chat_id, receipt_screen(o))
+
+@bot.worker()
+async def chain_watcher(feed): ...
+```
+
+Workers get DI, start after init, and shut down gracefully. Crashes restart automatically with exponential backoff -- no manual task supervision needed.
+
+## Features
+
+| Feature | Module | Details |
+|---|---|---|
+| Typed callbacks | `callbacks` | Pydantic models with a prefix. Stale/corrupt data returns "button expired" instead of crashing. Keyed encoding (`keyed=True`) uses query strings and tolerates schema changes; `unpack()` auto-detects either format so live buttons survive upgrades. |
+| Reply keyboards | `screens` | `ReplyKeyboard` value object (persistent + resized by default), `@bot.reply_button("label")` routes presses through the full pipeline, `REMOVE_REPLY_KEYBOARD` clears it. |
+| Markdown builder | `markdown` | Composable/nestable nodes, safe escaping for V1+V2, `raw()` escape hatch. |
+| Routers | `routing` | `@router.command/callback/message`, sub-routers, `router.raw()` for plain PTB handlers. |
+| Command args | `args` | Typed params from the signature; required/optional/`Greedy`; auto usage messages. |
+| Pagination | `pagination` | Implement `count()`/`fetch(offset, limit)`, use `Paginator` and `nav_row()` buttons. |
+| Conversations | `conversations` | Dataclass state per run, string transitions, timeout, `on_exit(reason)` hooks. Full DI/middleware/principal interop. |
+| Files/media | `media` | `download()` with timeout and cleanup; content-hash `file_id` cache shared with Screen rendering. |
+| Rate limiting | `ratelimit` | `@throttle(3, per=60)`, custom keys and custom behavior on limits. |
+| Logging | `logging` | Key=value format, one line per update, `audit()` convention. |
+| Errors | `errors` | `@bot.on_error(Type)` registry dispatched by MRO. Handlers can return a `Screen` to render into the current message. |
+| Command discovery | `commands` | Auto `/help` filtered by caller's scopes. `set_my_commands()` per scope. `hidden=True` for internal handlers. |
+| Middleware | `middleware` | `async def mw(event, call_next)` at bot or router scope. `event.extras` values become injectable. |
+
+## Example: scaled mode
+
+`examples/shop/` is a full app: a storefront with a **domain layer that never touches the bot layer** (`domain/`), views as pure functions (`domain -> Screen`), services injected into handlers, a `User` principal for guards and menus, a purchase conversation, admin commands, and a reconciler worker that messages buyers. Only `main.py` knows all the layers.
+
+## Escape hatches
+
+Not a fork or parallel dispatcher. `bot.build()` returns the PTB `Application` for webhooks. `router.raw(handler, group=...)` registers plain PTB handlers. `Screen.extra` passes kwargs to PTB's send methods. Everything from PTB stays accessible.
+
+## Testing
+
+Views are pure functions -- test them without a live bot. `Screen.content()`/`markup()` show what would be sent. `Delivery` accepts any object with `send`/`edit` methods (see `tests/conftest.py` for a mock). This repo has 102 tests that exercise dispatch and conversations the same way you can.

vitrine_tg-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "vitrine-tg"
+version = "0.1.0"
+description = "A batteries-included framework on top of python-telegram-bot: typed callbacks, screens, DI, auth, conversations, and supervised workers."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "target111", email = "target111@protonmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["telegram", "bot", "framework", "python-telegram-bot", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.13.4",
+    "python-telegram-bot[job-queue]>=22.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/target111/vitrine"
+Repository = "https://github.com/target111/vitrine"
+Issues = "https://github.com/target111/vitrine/issues"
+Changelog = "https://github.com/target111/vitrine/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "vitrine"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.14.4",
+]
+
+[tool.ruff]
+line-length = 92
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::telegram.warnings.PTBUserWarning",
+]

vitrine_tg-0.1.0/src/vitrine/__init__.py

@@ -0,0 +1,106 @@
+"""vitrine — a batteries-included foundation on top of python-telegram-bot.
+
+Thin in ceremony, deep in capability: typed callback routing, screens with
+robust delivery, dependency injection, an app-defined principal, guided
+conversations, supervised workers, rate limiting, structured logging, and
+typed error UX — while PTB's dispatcher, handlers, and filters stay fully
+reachable underneath.
+"""
+
+from .app import Bot, VitrineContext
+from .args import Greedy
+from .auth import Auth, admin_only, requires, requires_principal
+from .callbacks import CallbackData
+from .conversations import END, Conversation, ExitReason
+from .exceptions import (
+    AuthError,
+    BannedError,
+    CallbackDataError,
+    ConfigurationError,
+    FrameworkError,
+    InjectionError,
+    NotAuthorizedError,
+    NotRegisteredError,
+    RateLimitedError,
+    UsageError,
+    UserFacingError,
+)
+from .injection import Depends, Invocation, Providers
+from .logging import audit, log_event, setup_logging
+from .media import FileIdCache, InMemoryFileIdCache, download
+from .middleware import Event
+from .pagination import ListSource, Page, PageSource, Paginator, nav_row
+from .ratelimit import throttle
+from .routing import Router
+from .screens import (
+    REMOVE_REPLY_KEYBOARD,
+    Animation,
+    Audio,
+    Button,
+    ButtonStyle,
+    Delivery,
+    Document,
+    Media,
+    Photo,
+    ReplyButton,
+    ReplyKeyboard,
+    Screen,
+    Video,
+    Voice,
+)
+
+__all__ = [
+    "Animation",
+    "Audio",
+    "Auth",
+    "AuthError",
+    "BannedError",
+    "Bot",
+    "Button",
+    "ButtonStyle",
+    "CallbackData",
+    "CallbackDataError",
+    "ConfigurationError",
+    "Conversation",
+    "Delivery",
+    "Depends",
+    "Document",
+    "END",
+    "Event",
+    "ExitReason",
+    "VitrineContext",
+    "FileIdCache",
+    "FrameworkError",
+    "Greedy",
+    "InMemoryFileIdCache",
+    "InjectionError",
+    "Invocation",
+    "ListSource",
+    "Media",
+    "NotAuthorizedError",
+    "NotRegisteredError",
+    "Page",
+    "PageSource",
+    "Paginator",
+    "Photo",
+    "Providers",
+    "REMOVE_REPLY_KEYBOARD",
+    "RateLimitedError",
+    "ReplyButton",
+    "ReplyKeyboard",
+    "Router",
+    "Screen",
+    "UsageError",
+    "UserFacingError",
+    "Video",
+    "Voice",
+    "admin_only",
+    "audit",
+    "download",
+    "log_event",
+    "nav_row",
+    "requires",
+    "requires_principal",
+    "setup_logging",
+    "throttle",
+]