puragram 1.0.0__tar.gz

puragram-1.0.0/LICENSE

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

puragram-1.0.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: puragram
+Version: 1.0.0
+Summary: Fast, dependency-light Telegram Bot API framework built on urllib3
+Author-email: Maxim Zhovner <zovnercukmaksim197@gmail.com>
+License: MIT
+Keywords: telegram,bot,api,urllib3,framework
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# puragram
+
+A fast, dependency-light Telegram Bot API framework for Python.
+Built on urllib3 — no aiohttp, no requests, no httpx.
+
+## Install
+
+```bash
+pip install puragram
+```
+
+## Quick start
+
+```python
+from puragram import Bot
+
+bot = Bot("YOUR_TOKEN", parse_mode="HTML")
+
+@bot.message_handler(commands=["start"])
+def start(msg):
+    bot.send_message(msg.chat.id, f"Hi, <b>{msg.from_user.first_name}</b>!")
+
+@bot.message_handler(content_types=["text"])
+def echo(msg):
+    bot.send_message(msg.chat.id, f"You said: <b>{msg.text}</b>")
+
+if __name__ == "__main__":
+    bot.run_polling()
+```
+
+## Features
+
+- Fast: direct urllib3 pool, JSON bodies, keep-alive
+- Built-in FSM: State, StatesGroup, MemoryStorage, FileStorage, SQLiteStorage
+- Middleware: logging, throttling, timing
+- Filters: Command, Text, Regexp, ContentTypes, ChatType, ChatId, UserId, CallbackData, Func
+- Webhook server on stdlib http.server
+- Secure: path traversal guard, size limits, ReDoS filter, webhook secret, token redaction, dedup
+- Zero dependencies except urllib3
+
+## FSM example
+
+```python
+from puragram import Bot, State, StatesGroup
+
+bot = Bot("YOUR_TOKEN")
+
+class Form(StatesGroup):
+    name = State()
+
+@bot.message_handler(commands=["start"])
+def start(msg, data):
+    data["state"].set_state(Form.name)
+    bot.send_message(msg.chat.id, "Your name?")
+
+@bot.message_handler(state=Form.name)
+def on_name(msg, data):
+    data["state"].update_data(name=msg.text)
+    data["state"].clear()
+    bot.send_message(msg.chat.id, f"Hi, {msg.text}!")
+
+bot.run_polling()
+```
+
+## License
+
+MIT — see LICENSE.

puragram-1.0.0/README.md

@@ -0,0 +1,67 @@
+# puragram
+
+A fast, dependency-light Telegram Bot API framework for Python.
+Built on urllib3 — no aiohttp, no requests, no httpx.
+
+## Install
+
+```bash
+pip install puragram
+```
+
+## Quick start
+
+```python
+from puragram import Bot
+
+bot = Bot("YOUR_TOKEN", parse_mode="HTML")
+
+@bot.message_handler(commands=["start"])
+def start(msg):
+    bot.send_message(msg.chat.id, f"Hi, <b>{msg.from_user.first_name}</b>!")
+
+@bot.message_handler(content_types=["text"])
+def echo(msg):
+    bot.send_message(msg.chat.id, f"You said: <b>{msg.text}</b>")
+
+if __name__ == "__main__":
+    bot.run_polling()
+```
+
+## Features
+
+- Fast: direct urllib3 pool, JSON bodies, keep-alive
+- Built-in FSM: State, StatesGroup, MemoryStorage, FileStorage, SQLiteStorage
+- Middleware: logging, throttling, timing
+- Filters: Command, Text, Regexp, ContentTypes, ChatType, ChatId, UserId, CallbackData, Func
+- Webhook server on stdlib http.server
+- Secure: path traversal guard, size limits, ReDoS filter, webhook secret, token redaction, dedup
+- Zero dependencies except urllib3
+
+## FSM example
+
+```python
+from puragram import Bot, State, StatesGroup
+
+bot = Bot("YOUR_TOKEN")
+
+class Form(StatesGroup):
+    name = State()
+
+@bot.message_handler(commands=["start"])
+def start(msg, data):
+    data["state"].set_state(Form.name)
+    bot.send_message(msg.chat.id, "Your name?")
+
+@bot.message_handler(state=Form.name)
+def on_name(msg, data):
+    data["state"].update_data(name=msg.text)
+    data["state"].clear()
+    bot.send_message(msg.chat.id, f"Hi, {msg.text}!")
+
+bot.run_polling()
+```
+
+## License
+
+MIT — see LICENSE.

puragram-1.0.0/puragram/__init__.py

@@ -0,0 +1,67 @@
+from .api import TelegramAPI
+from .bot import Bot
+from .exceptions import (
+    TelegramError, GrambotError, SecurityError,
+    ValidationError, WebhookError,
+)
+from .logger import get_logger, setup_logging, quiet
+
+from .types import (
+    CallbackQuery, Chat, Message, Update, User,
+)
+from .keyboards import (
+    ForceReply, InlineKeyboardBuilder, InlineKeyboardButton,
+    InlineKeyboardMarkup, KeyboardButton, RemoveKeyboard,
+    ReplyKeyboardMarkup,
+)
+from .filters import (
+    BaseFilter, CallbackData, ChatId, ChatType, Command,
+    ContentTypes, Func, Regexp, Text, UserId,
+)
+from .fsm import (
+    BaseStorage, FileStorage, FSMContext, MemoryStorage,
+    SQLiteStorage, State, StatesGroup,
+)
+from .middleware import (
+    BaseMiddleware, LoggingMiddleware, ThrottlingMiddleware,
+    TimingMiddleware,
+)
+from .webhook import WebhookServer
+from .utils import (
+    chunked, escape_html, escape_markdown, safe_text,
+    split_message, truncate, user_mention,
+)
+from .security import (
+    constant_time_eq, mask_token, redact, safe_filename,
+    safe_path, validate_callback_data, validate_text,
+    compile_safe_regex, check_size,
+    MAX_MESSAGE_LEN, MAX_CAPTION_LEN, MAX_CALLBACK_DATA,
+    MAX_UPLOAD_BYTES, MAX_WEBHOOK_BYTES, MAX_REGEX_LEN,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Bot", "TelegramAPI",
+    "GrambotError", "TelegramError", "SecurityError",
+    "ValidationError", "WebhookError",
+    "Update", "Message", "Chat", "User", "CallbackQuery",
+    "InlineKeyboardMarkup", "InlineKeyboardButton",
+    "ReplyKeyboardMarkup", "KeyboardButton",
+    "ForceReply", "RemoveKeyboard", "InlineKeyboardBuilder",
+    "BaseFilter", "Func", "Command", "Text", "ContentTypes",
+    "ChatType", "ChatId", "UserId", "Regexp", "CallbackData",
+    "FSMContext", "State", "StatesGroup",
+    "BaseStorage", "MemoryStorage", "FileStorage", "SQLiteStorage",
+    "BaseMiddleware", "LoggingMiddleware", "ThrottlingMiddleware",
+    "TimingMiddleware",
+    "WebhookServer",
+    "escape_html", "escape_markdown", "safe_text",
+    "split_message", "chunked", "user_mention", "truncate",
+    "redact", "mask_token", "safe_path", "safe_filename",
+    "validate_callback_data", "validate_text",
+    "compile_safe_regex", "check_size", "constant_time_eq",
+    "MAX_MESSAGE_LEN", "MAX_CAPTION_LEN", "MAX_CALLBACK_DATA",
+    "MAX_UPLOAD_BYTES", "MAX_WEBHOOK_BYTES", "MAX_REGEX_LEN",
+    "get_logger", "setup_logging", "quiet",
+]

puragram-1.0.0/puragram/api.py

@@ -0,0 +1,123 @@
+import json
+import urllib3
+
+from .exceptions import TelegramError, SecurityError
+from .security import MAX_UPLOAD_BYTES, safe_filename
+from .logger import get_logger
+
+log = get_logger("puragram.api")
+
+
+def _camel(name):
+    head, *tail = name.split("_")
+    return head + "".join(p.capitalize() for p in tail)
+
+
+class TelegramAPI:
+    def __init__(self, token, pool_size=10, timeout=30.0, retries=2):
+        if not token or not isinstance(token, str):
+            raise SecurityError("Token must be a non-empty string")
+        if ":" not in token:
+            raise SecurityError("Token has invalid format")
+        self.token = token
+        self.base_url = f"https://api.telegram.org/bot{token}"
+        self.file_url = f"https://api.telegram.org/file/bot{token}"
+        self._http = urllib3.PoolManager(
+            num_pools=pool_size,
+            maxsize=pool_size,
+            block=False,
+            timeout=urllib3.Timeout(connect=5.0, read=timeout),
+            retries=urllib3.Retry(
+                retries,
+                backoff_factor=0.3,
+                status_forcelist=[500, 502, 503, 504],
+                allowed_methods=frozenset(["GET", "POST"]),
+                raise_on_status=False,
+            ),
+        )
+
+    def call(self, method, files=None, **params):
+        url = f"{self.base_url}/{_camel(method)}"
+        try:
+            if files:
+                fields = self._build_multipart(files, params)
+                resp = self._http.request("POST", url, fields=fields)
+            else:
+                body = json.dumps(
+                    params, ensure_ascii=False, separators=(",", ":")
+                ).encode("utf-8")
+                resp = self._http.request(
+                    "POST", url, body=body,
+                    headers={"Content-Type": "application/json"},
+                )
+        except urllib3.exceptions.HTTPError as e:
+            log.error("HTTP error calling %s: %s", method, e)
+            raise TelegramError(f"HTTP error: {e}") from e
+
+        return self._parse(resp.data)
+
+    def stream_file(self, file_path, chunk_size=64 * 1024):
+        url = f"{self.file_url}/{file_path}"
+        resp = self._http.request("GET", url, preload_content=False)
+        try:
+            while True:
+                chunk = resp.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+        finally:
+            resp.release_conn()
+
+    def close(self):
+        self._http.clear()
+
+    @staticmethod
+    def _parse(raw):
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            raise TelegramError(f"Invalid JSON from Telegram: {raw[:200]!r}")
+        if not payload.get("ok"):
+            raise TelegramError(
+                payload.get("description", "Unknown error"),
+                payload.get("error_code"),
+                payload,
+            )
+        return payload["result"]
+
+    @staticmethod
+    def _build_multipart(files, params):
+        fields = {}
+        for k, v in params.items():
+            if v is None:
+                continue
+            if isinstance(v, (dict, list)):
+                fields[k] = json.dumps(v, ensure_ascii=False)
+            elif isinstance(v, bool):
+                fields[k] = "true" if v else "false"
+            else:
+                fields[k] = str(v)
+
+        for k, v in files.items():
+            if hasattr(v, "read"):
+                data = v.read()
+                if isinstance(data, str):
+                    data = data.encode()
+                if len(data) > MAX_UPLOAD_BYTES:
+                    raise SecurityError(f"File too large: {len(data)} bytes")
+                name = safe_filename(getattr(v, "name", k))
+                fields[k] = (name, data, "application/octet-stream")
+            elif isinstance(v, (bytes, bytearray)):
+                if len(v) > MAX_UPLOAD_BYTES:
+                    raise SecurityError(f"File too large: {len(v)} bytes")
+                fields[k] = (f"{safe_filename(k)}.bin", bytes(v),
+                             "application/octet-stream")
+            elif isinstance(v, str) and v.startswith("https://"):
+                fields[k] = v
+            elif isinstance(v, str) and v.startswith("http://"):
+                raise SecurityError("Only HTTPS URLs allowed")
+            else:
+                raise SecurityError(
+                    f"Unsupported file for {k!r}: {type(v).__name__}"
+                )
+        return fields