matele 0.1.0__py3-none-any.whl

matele/__init__.py

@@ -0,0 +1,96 @@
+"""matele: one bot, two messengers (MAX and Telegram)."""
+
+from matele.callbacks import CallbackData, CallbackError, CallbackRegistry, action, callback, parse
+from matele.dispatch import (
+	ChatType,
+	Context,
+	Dispatcher,
+	Filter,
+	HasAttachment,
+	OnPlatform,
+	Regex,
+	Router,
+	Text,
+	as_filter,
+)
+from matele.errors import (
+	BotApiError,
+	BotForbiddenError,
+	BotUnavailableError,
+	ConnectionGuard,
+	is_unreachable,
+	platform_title,
+)
+from matele.fsm import ANY_STATE, FSMContext, MemoryStorage, State, StatesGroup, Storage, StorageKey
+from matele.types import (
+	GROUP,
+	MAX,
+	PRIVATE,
+	TELEGRAM,
+	Attachment,
+	BotClient,
+	Button,
+	CallbackQuery,
+	ChatMemberUpdate,
+	ChatStatus,
+	Event,
+	FileKind,
+	FileSource,
+	IncomingEvent,
+	Keyboard,
+	Message,
+	User,
+	escape,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+	"ANY_STATE",
+	"GROUP",
+	"MAX",
+	"PRIVATE",
+	"TELEGRAM",
+	"Attachment",
+	"BotApiError",
+	"BotClient",
+	"BotForbiddenError",
+	"BotUnavailableError",
+	"Button",
+	"CallbackData",
+	"CallbackError",
+	"CallbackQuery",
+	"CallbackRegistry",
+	"ChatMemberUpdate",
+	"ChatStatus",
+	"ChatType",
+	"ConnectionGuard",
+	"Context",
+	"Dispatcher",
+	"Event",
+	"FileKind",
+	"FileSource",
+	"FSMContext",
+	"Filter",
+	"HasAttachment",
+	"IncomingEvent",
+	"Keyboard",
+	"MemoryStorage",
+	"Message",
+	"OnPlatform",
+	"Regex",
+	"Router",
+	"State",
+	"StatesGroup",
+	"Storage",
+	"StorageKey",
+	"Text",
+	"User",
+	"action",
+	"as_filter",
+	"callback",
+	"escape",
+	"is_unreachable",
+	"parse",
+	"platform_title",
+]

matele/_http.py

@@ -0,0 +1,39 @@
+"""HTTP helpers shared by the transports."""
+
+from __future__ import annotations
+
+import httpx
+
+# Files people send are downloaded into memory, so their size is capped:
+# without a cap one huge file would take the whole process down.
+DEFAULT_MAX_DOWNLOAD = 50 * 1024 * 1024
+
+
+def is_connection_failure(exc: Exception) -> bool:
+	"""Does this failure say the API can't be reached (refused, reset or
+	timed-out connection, DNS, proxy)? A timeout while reading, writing or
+	waiting for a free connection doesn't: the API was reached, this one
+	call was slow or the client is busy."""
+	return isinstance(exc, httpx.TransportError) and not isinstance(
+		exc, httpx.ReadTimeout | httpx.WriteTimeout | httpx.PoolTimeout
+	)
+
+
+class TooLargeError(Exception):
+	"""The body is bigger than the limit."""
+
+
+async def read_limited(resp: httpx.Response, limit: int | None) -> bytes:
+	"""Reads a streamed response, giving up as soon as it is over `limit`
+	bytes (None: no limit). Raises TooLargeError."""
+	declared = resp.headers.get("content-length", "")
+	if limit is not None and declared.isdigit() and int(declared) > limit:
+		raise TooLargeError
+	chunks: list[bytes] = []
+	size = 0
+	async for chunk in resp.aiter_bytes():
+		size += len(chunk)
+		if limit is not None and size > limit:
+			raise TooLargeError
+		chunks.append(chunk)
+	return b"".join(chunks)

matele/callbacks.py

@@ -0,0 +1,225 @@
+"""Typed callback data: every button payload is a small frozen dataclass
+with a fixed prefix, packed to "prefix:field:field…" and parsed back by
+the dispatcher, so handlers never split strings.
+
+	@callback("order:set")
+	class SetStatus(CallbackData):
+		order_id: int
+		status: Literal["paid", "shipped"]
+		note: str = ""
+
+	Button("✅ Оплачен", SetStatus(42, "paid").pack())
+
+Fields may be int, str, bool, datetime.date or a Literal of strings.
+Trailing fields equal to their defaults are left out when packing and get
+their defaults back when parsing, so a field with a default can be added
+to an existing payload without breaking buttons already sent. Only the
+last field may be a str containing ":".
+
+Payloads without fields are `action("menu:home")` instances.
+
+Keep payloads short (ids, not names): Telegram allows 64 bytes.
+
+Prefixes are unique within a registry: declaring the same one twice is an
+error at import time, so two features can never fight over a button.
+`callback()` and `parse()` use the default registry unless given another
+(tests and plugins may want their own).
+
+Button data comes back from the person's client, and a modified client
+can send any string: `order:view:43` for an order that was never shown
+to them. Give the bots a `callback_secret` and every payload is sent
+with a signature (`sign()`); data that doesn't carry a valid one reaches
+the handlers as an outdated button, not as a payload. A person can then
+only press buttons the bot really made, though still any of them they
+have seen (in a group, other people's too): who may do what is for the
+handler to check.
+"""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import datetime as dt
+import hashlib
+import hmac
+import typing
+from collections.abc import Callable
+from typing import Any, ClassVar, Literal, Self, TypeVar, cast, dataclass_transform
+
+SEP = ":"
+
+T = TypeVar("T")
+
+
+SIGN_SEP = "#"
+SIGNATURE_LENGTH = 10  # base64 characters: 60 bits of an HMAC-SHA256
+
+
+def _signature(data: str, secret: str) -> str:
+	digest = hmac.new(secret.encode(), data.encode(), hashlib.sha256).digest()
+	return base64.urlsafe_b64encode(digest).decode()[:SIGNATURE_LENGTH]
+
+
+def sign(data: str, secret: str) -> str:
+	"""`data` with a signature only the holder of `secret` can make."""
+	return f"{data}{SIGN_SEP}{_signature(data, secret)}"
+
+
+def unsign(signed: str, secret: str) -> str | None:
+	"""The data `sign()` was given; None if the signature is missing or wrong."""
+	data, sep, given = signed.rpartition(SIGN_SEP)
+	if not sep or not hmac.compare_digest(given.encode(), _signature(data, secret).encode()):
+		return None
+	return data
+
+
+class CallbackError(ValueError):
+	"""Payload that doesn't parse: a stale button from an older version, or forged."""
+
+
+class CallbackData:
+	prefix: ClassVar[str]
+	_fields: ClassVar[tuple[tuple[str, Any, Any], ...]]  # (name, type, default or MISSING)
+
+	def pack(self) -> str:
+		values = [_dump(getattr(self, name)) for name, _, _ in self._fields]
+		for i, value in enumerate(values[:-1]):
+			if SEP in value:
+				raise ValueError(f"{type(self).__name__}.{self._fields[i][0]}: only the last field may contain {SEP!r}")
+		# drop trailing defaults, so optional fields don't widen old payloads
+		n = len(values)
+		while (
+			n
+			and self._fields[n - 1][2] is not dataclasses.MISSING
+			and getattr(self, self._fields[n - 1][0]) == self._fields[n - 1][2]
+		):
+			n -= 1
+		return SEP.join([self.prefix, *values[:n]])
+
+	@classmethod
+	def unpack(cls, data: str) -> Self:
+		if data == cls.prefix:
+			raw: list[str] = []
+		elif data.startswith(cls.prefix + SEP):
+			rest = data[len(cls.prefix) + 1 :]
+			raw = rest.split(SEP, max(len(cls._fields) - 1, 0)) if cls._fields else [rest]
+		else:
+			raise CallbackError(f"not a {cls.__name__}: {data!r}")
+		if len(raw) > len(cls._fields):
+			raise CallbackError(f"too many fields for {cls.__name__}: {data!r}")
+		kwargs = {}
+		for i, (name, tp, default) in enumerate(cls._fields):
+			if i < len(raw):
+				kwargs[name] = _load(raw[i], tp)
+			elif default is dataclasses.MISSING:
+				raise CallbackError(f"{cls.__name__}.{name} missing: {data!r}")
+		return cast(Callable[..., Self], cls)(**kwargs)
+
+
+class CallbackRegistry:
+	"""Prefix -> payload class. The longest registered prefix wins."""
+
+	def __init__(self) -> None:
+		self._classes: dict[str, type[CallbackData]] = {}
+
+	def check_free(self, prefix: str) -> None:
+		existing = self._classes.get(prefix)
+		if existing is not None:
+			raise ValueError(f"callback prefix {prefix!r} is already used by {existing.__qualname__}")
+
+	def register(self, cls: type[CallbackData]) -> None:
+		self.check_free(cls.prefix)
+		self._classes[cls.prefix] = cls
+
+	def parse(self, data: str) -> CallbackData:
+		parts = data.split(SEP)
+		for n in range(len(parts), 0, -1):
+			cls = self._classes.get(SEP.join(parts[:n]))
+			if cls is not None:
+				return cls.unpack(data)
+		raise CallbackError(f"unknown callback {data!r}")
+
+
+default_registry = CallbackRegistry()
+
+
+@dataclass_transform(frozen_default=True)
+def callback(prefix: str, *, registry: CallbackRegistry | None = None) -> Callable[[type[T]], type[T]]:
+	"""Class decorator: makes a frozen dataclass and registers its prefix."""
+	if not prefix or prefix.startswith(SEP) or prefix.endswith(SEP):
+		raise ValueError(f"bad callback prefix {prefix!r}")
+	target = registry if registry is not None else default_registry
+
+	def decorate(cls: type[T]) -> type[T]:
+		target.check_free(prefix)
+		base = dataclasses.dataclass(frozen=True)(cls)
+		bases: tuple[type, ...] = (base,) if issubclass(base, CallbackData) else (base, CallbackData)
+		dc = cast(Callable[..., type[CallbackData]], type)(
+			cls.__name__,
+			bases,
+			{"__module__": cls.__module__, "__qualname__": cls.__qualname__, "__doc__": cls.__doc__},
+		)
+		hints = typing.get_type_hints(cls)
+		dc.prefix = prefix
+		dc._fields = tuple((f.name, hints[f.name], f.default) for f in dataclasses.fields(cast(Any, dc)))
+		for name, tp, _ in dc._fields:
+			_check_type(dc, name, tp)
+		target.register(dc)
+		return cast(type[T], dc)
+
+	return decorate
+
+
+def action(prefix: str, *, registry: CallbackRegistry | None = None) -> CallbackData:
+	"""A payload without fields, ready to put on a button."""
+	cls = callback(prefix, registry=registry)(type(_class_name(prefix), (), {"__module__": __name__}))
+	return cast(type[CallbackData], cls)()
+
+
+def parse(data: str, *, registry: CallbackRegistry | None = None) -> CallbackData:
+	"""The payload for raw callback data; the longest registered prefix wins."""
+	return (registry if registry is not None else default_registry).parse(data)
+
+
+def as_class(target: type[CallbackData] | CallbackData) -> type[CallbackData]:
+	return target if isinstance(target, type) else type(target)
+
+
+# ----------------------------------------------------------------------
+def _class_name(prefix: str) -> str:
+	return "".join(p.capitalize() for p in prefix.replace("-", "_").replace(SEP, "_").split("_")) or "Action"
+
+
+def _check_type(cls: type, name: str, tp: Any) -> None:
+	if tp in (int, str, bool, dt.date):
+		return
+	if typing.get_origin(tp) is Literal and all(isinstance(a, str) for a in typing.get_args(tp)):
+		return
+	raise TypeError(f"{cls.__qualname__}.{name}: unsupported callback field type {tp!r}")
+
+
+def _dump(value: Any) -> str:
+	if isinstance(value, bool):
+		return "1" if value else "0"
+	if isinstance(value, dt.date):
+		return value.isoformat()
+	return str(value)
+
+
+def _load(raw: str, tp: Any) -> Any:
+	try:
+		if tp is bool:
+			if raw not in ("0", "1"):
+				raise ValueError(raw)
+			return raw == "1"
+		if tp is int:
+			return int(raw)
+		if tp is dt.date:
+			return dt.date.fromisoformat(raw)
+		if tp is str:
+			return raw
+	except ValueError as exc:
+		raise CallbackError(f"bad {tp.__name__} {raw!r}") from exc
+	if raw not in typing.get_args(tp):  # Literal
+		raise CallbackError(f"{raw!r} not one of {typing.get_args(tp)}")
+	return raw

matele/dispatch/__init__.py

@@ -0,0 +1,19 @@
+from matele.dispatch.context import Context
+from matele.dispatch.dispatcher import Command, Dispatcher, parse_command
+from matele.dispatch.filters import ChatType, Filter, HasAttachment, OnPlatform, Regex, Text, as_filter
+from matele.dispatch.router import Router
+
+__all__ = [
+	"ChatType",
+	"Command",
+	"Context",
+	"Dispatcher",
+	"Filter",
+	"HasAttachment",
+	"OnPlatform",
+	"Regex",
+	"Router",
+	"Text",
+	"as_filter",
+	"parse_command",
+]

matele/dispatch/context.py

@@ -0,0 +1,226 @@
+"""Context: the one object every handler, filter and middleware receives.
+
+Subclass it to give handlers typed access to whatever your middleware
+loads, and pass the subclass to the Dispatcher:
+
+	class Ctx(Context):
+		account: Account | None = None
+
+	dp = Dispatcher(context_class=Ctx)
+
+	@dp.middleware
+	async def load_account(ctx: Ctx, call_next):
+		ctx.account = await accounts.find(ctx.platform, ctx.user.id)
+		await call_next()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from matele.callbacks import CallbackData
+from matele.errors import BotApiError
+from matele.fsm import FSMContext
+from matele.types import (
+	PRIVATE,
+	BotClient,
+	CallbackQuery,
+	ChatMemberUpdate,
+	ChatStatus,
+	FileKind,
+	FileSource,
+	IncomingEvent,
+	Keyboard,
+	Message,
+	User,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Context:
+	def __init__(self, event: IncomingEvent, state: FSMContext):
+		self.event = event
+		self.state = state
+		# Free-form storage for middleware and filters.
+		self.data: dict[str, Any] = {}
+		# Set by the dispatcher before filters run:
+		self.payload: CallbackData | None = None  # parsed button payload (None if it didn't parse)
+		self.command: str | None = None  # "start" for "/start abc"
+		self.args: str | None = None  # "abc" for "/start abc"
+		self.match: re.Match[str] | None = None  # set by the Regex filter
+		self.answered = False
+
+	# ------------------------------------------------------------ the event
+	@property
+	def bot(self) -> BotClient:
+		return self.event.bot
+
+	@property
+	def user(self) -> User:
+		return self.event.from_user
+
+	@property
+	def platform(self) -> str:
+		return self.event.from_user.platform
+
+	@property
+	def callback(self) -> CallbackQuery | None:
+		return self.event if isinstance(self.event, CallbackQuery) else None
+
+	@property
+	def is_callback(self) -> bool:
+		return isinstance(self.event, CallbackQuery)
+
+	@property
+	def message(self) -> Message | None:
+		"""The incoming message, or the message a pressed button is on."""
+		if isinstance(self.event, Message):
+			return self.event
+		if isinstance(self.event, CallbackQuery):
+			return self.event.message
+		return None
+
+	@property
+	def chat_status(self) -> ChatStatus | None:
+		return self.event if isinstance(self.event, ChatStatus) else None
+
+	@property
+	def member_update(self) -> ChatMemberUpdate | None:
+		return self.event if isinstance(self.event, ChatMemberUpdate) else None
+
+	@property
+	def chat_type(self) -> str:
+		"""matele.PRIVATE or matele.GROUP: where the event happened."""
+		if isinstance(self.event, ChatMemberUpdate):
+			return self.event.chat_type
+		message = self.message
+		return message.chat_type if message is not None else PRIVATE
+
+	@property
+	def chat_id(self) -> int | None:
+		"""The group the event happened in; None in a private chat."""
+		if isinstance(self.event, ChatMemberUpdate):
+			return self.event.chat_id
+		message = self.message
+		return message.chat_id if message is not None and message.chat_type != PRIVATE else None
+
+	def _target(self) -> dict[str, int]:
+		chat_id = self.chat_id
+		return {"chat_id": chat_id} if chat_id is not None else {"user_id": self.user.id}
+
+	@property
+	def text(self) -> str:
+		"""Text of an incoming message ("" for anything else)."""
+		return (self.event.text or "") if isinstance(self.event, Message) else ""
+
+	# ------------------------------------------------------------ output
+	def _quoted(self, quote: bool) -> str | None:
+		message = self.message
+		return message.message_id if quote and message is not None and message.message_id else None
+
+	async def reply(self, text: str, keyboard: Keyboard | None = None, *, quote: bool = False) -> Message:
+		"""Sends a new message where the event happened: to the group, or to
+		the person's private chat. `quote=True` makes it a reply to the
+		incoming message (or the one the pressed button is on)."""
+		return await self.bot.send_message(text, keyboard=keyboard, reply_to=self._quoted(quote), **self._target())
+
+	async def reply_file(
+		self,
+		source: FileSource,
+		*,
+		kind: FileKind = "file",
+		filename: str | None = None,
+		caption: str | None = None,
+		keyboard: Keyboard | None = None,
+		quote: bool = False,
+	) -> Message:
+		"""Sends a photo (kind="image"), video, audio or file where the event
+		happened. `source`: bytes, a path or a binary file object."""
+		return await self.bot.send_file(
+			source,
+			kind=kind,
+			filename=filename,
+			caption=caption,
+			keyboard=keyboard,
+			reply_to=self._quoted(quote),
+			**self._target(),
+		)
+
+	async def reply_document(self, content: bytes, filename: str, caption: str | None = None) -> Message:
+		return await self.reply_file(content, kind="file", filename=filename, caption=caption)
+
+	@asynccontextmanager
+	async def typing(self, every: float = 4.0) -> AsyncIterator[None]:
+		"""Shows "typing…" while the block runs (renewed every `every` s):
+
+		async with ctx.typing():
+			answer = await slow_thing()
+		"""
+		message = self.message
+		if message is None:
+			yield
+			return
+		chat_id = message.chat_id
+
+		async def keep_typing() -> None:
+			while True:
+				try:
+					await self.bot.send_typing(chat_id)
+				except asyncio.CancelledError:
+					raise
+				except Exception as exc:  # "typing…" is cosmetic: never break the handler
+					logger.debug("send_typing failed: %s", exc)
+				await asyncio.sleep(every)
+
+		task = asyncio.create_task(keep_typing())
+		try:
+			yield
+		finally:
+			task.cancel()
+			await asyncio.gather(task, return_exceptions=True)
+
+	async def show(
+		self, text: str, keyboard: Keyboard | None = None, *, toast: str | None = None, keep_input: bool = False
+	) -> Message | None:
+		"""Shows a screen in the person's single menu message (see
+		matele.dispatch.panel): edits it instead of sending a new one."""
+		from matele.dispatch.panel import show
+
+		return await show(self, text, keyboard, toast=toast, keep_input=keep_input)
+
+	async def send_private(self, text: str, keyboard: Keyboard | None = None) -> Message:
+		"""Sends to the person's private chat with the bot, even from a group
+		(fails if they never started the bot)."""
+		return await self.bot.send_message(text, user_id=self.user.id, keyboard=keyboard)
+
+	async def edit(self, text: str | None, keyboard: Keyboard | None = None) -> None:
+		"""Edits the message the pressed button is on."""
+		target = self.event.message if isinstance(self.event, CallbackQuery) else None
+		if target is None or not target.message_id:
+			raise RuntimeError("edit() needs a pressed button on a message the bot can edit")
+		await self.bot.edit_message(target.message_id, text, keyboard=keyboard)
+
+	async def delete(self) -> None:
+		"""Deletes the incoming message, or the message a pressed button is on."""
+		target = self.message
+		if target is None or not target.message_id:
+			raise RuntimeError("delete() needs a message")
+		await self.bot.delete_message(target.message_id)
+
+	async def answer(self, text: str | None = None, *, alert: bool = False) -> None:
+		"""Answers a button press: stops the spinner, optionally with a toast
+		(or an alert). Only the first call counts; the dispatcher answers
+		silently after the handler if nobody did. No-op for other events."""
+		if not isinstance(self.event, CallbackQuery) or self.answered:
+			return
+		self.answered = True
+		try:
+			await self.bot.answer_callback(self.event.id, text=text, alert=alert)
+		except BotApiError as exc:  # e.g. Telegram's "query is too old"
+			logger.debug("answer_callback failed: %s", exc)