tgwidget 0.1.0__py3-none-any.whl

tgwidget/__init__.py

@@ -0,0 +1,5 @@
+from .builder import TgWidget
+from .parser import parse_date, parse_color, parse_schedule
+
+__all__ = ["TgWidget", "parse_date", "parse_color", "parse_schedule"]
+__version__ = "0.1.0"

tgwidget/builder.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+import re
+from base64 import b64encode
+from typing import Any, Optional
+
+from .types import (
+    VALID_COLOR_FORMATS,
+    VALID_COLOR_SCHEMES,
+    VALID_DATE_FORMATS,
+    VALID_DATE_MODES,
+    VALID_DATE_ORDERS,
+    ColorFormat,
+    ColorScheme,
+    DateFormat,
+    DateMode,
+    DateOrder,
+)
+
+BASE_URL = "https://tgwidget.github.io/"
+
+_HEX_RE = re.compile(r"^#?[0-9A-Fa-f]{6}$")
+
+
+def _validate_hex(color: str, name: str) -> str:
+    if not _HEX_RE.match(color):
+        raise ValueError(f"{name} must be a valid hex color (e.g. '#FF0000'), got '{color}'")
+    return color if color.startswith("#") else f"#{color}"
+
+
+class TgWidget:
+    """Builder for TeleWidget URLs."""
+
+    def __init__(self, bot_username: str) -> None:
+        if not bot_username:
+            raise ValueError("bot_username is required")
+        self._bot_username = bot_username
+        self._widget: Optional[str] = None
+        self._payload: dict[str, Any] = {}
+        self._style: dict[str, Any] = {}
+
+    def date(
+        self,
+        mode: DateMode = "date",
+        format: DateFormat = "default",
+        order: DateOrder = "ymd",
+    ) -> TgWidget:
+        if mode not in VALID_DATE_MODES:
+            raise ValueError(f"Invalid date mode '{mode}'. Must be one of: {VALID_DATE_MODES}")
+        if format not in VALID_DATE_FORMATS:
+            raise ValueError(f"Invalid date format '{format}'. Must be one of: {VALID_DATE_FORMATS}")
+        if order not in VALID_DATE_ORDERS:
+            raise ValueError(f"Invalid date order '{order}'. Must be one of: {VALID_DATE_ORDERS}")
+        self._widget = "date"
+        self._payload = {"mode": mode, "format": format, "order": order}
+        return self
+
+    def color(self, format: ColorFormat = "hex") -> TgWidget:
+        if format not in VALID_COLOR_FORMATS:
+            raise ValueError(f"Invalid color format '{format}'. Must be one of: {VALID_COLOR_FORMATS}")
+        self._widget = "color"
+        self._payload = {"format": format}
+        return self
+
+    def schedule(self) -> TgWidget:
+        self._widget = "schedule"
+        self._payload = {"format": "bunch"}
+        return self
+
+    def style(
+        self,
+        *,
+        color_scheme: ColorScheme = "light",
+        accent: Optional[str] = None,
+        tint: Optional[str] = None,
+        liquid_glass: bool = False,
+        adapt_tg_theme: bool = False,
+        adopt_tg_palette: bool = False,
+    ) -> TgWidget:
+        if color_scheme not in VALID_COLOR_SCHEMES:
+            raise ValueError(f"Invalid color_scheme '{color_scheme}'. Must be one of: {VALID_COLOR_SCHEMES}")
+        self._style = {
+            "colorScheme": color_scheme,
+            "liquidGlass": liquid_glass,
+            "adaptTgTheme": adapt_tg_theme,
+            "adoptTgPalette": adopt_tg_palette,
+        }
+        if accent:
+            self._style["accent"] = _validate_hex(accent, "accent")
+        if tint:
+            self._style["tint"] = _validate_hex(tint, "tint")
+        return self
+
+    def _build_payload(self) -> dict[str, Any]:
+        if not self._widget:
+            raise ValueError("No widget type set. Call .date(), .color(), or .schedule() first.")
+        payload: dict[str, Any] = {
+            "widget": self._widget,
+            "bot_username": self._bot_username,
+            **self._payload,
+        }
+        if self._style:
+            payload["style"] = self._style
+        return payload
+
+    def url(self, base_url: str = BASE_URL) -> str:
+        payload = self._build_payload()
+        encoded = b64encode(json.dumps(payload, separators=(",", ":")).encode()).decode()
+        return f"{base_url}?p={encoded}"
+
+    def payload(self) -> dict[str, Any]:
+        return self._build_payload()

tgwidget/parser.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, time
+from typing import Optional
+
+from .types import ColorFormat, DateFormat, DateMode, DateOrder
+
+
+@dataclass
+class DateResult:
+    date: Optional[str] = None
+    time: Optional[str] = None
+    date_end: Optional[str] = None
+    time_end: Optional[str] = None
+    timestamp: Optional[int] = None
+    timestamp_end: Optional[int] = None
+
+
+@dataclass
+class ColorResult:
+    raw: str
+    hex: Optional[str] = None
+    rgb: Optional[tuple[int, int, int]] = None
+    hsl: Optional[tuple[int, int, int]] = None
+
+
+@dataclass
+class ScheduleDay:
+    enabled: bool
+    start: Optional[str] = None
+    end: Optional[str] = None
+
+
+@dataclass
+class ScheduleResult:
+    days: list[ScheduleDay]
+
+
+def parse_date(
+    value: str,
+    mode: DateMode = "date",
+    format: DateFormat = "default",
+    order: DateOrder = "ymd",
+) -> DateResult:
+    """Parse date widget result string back into structured data."""
+    result = DateResult()
+
+    if format in ("unix-s", "unix-ms"):
+        parts = value.split("_")
+        div = 1000 if format == "unix-s" else 1
+        ts = int(parts[0]) * div if format == "unix-s" else int(parts[0])
+        result.timestamp = int(parts[0])
+        if len(parts) > 1:
+            result.timestamp_end = int(parts[1])
+        dt = datetime.fromtimestamp(ts / 1000)
+        result.date = dt.strftime("%Y-%m-%d")
+        result.time = dt.strftime("%H:%M")
+        if result.timestamp_end is not None:
+            ts_end = int(parts[1]) * div if format == "unix-s" else int(parts[1])
+            dt_end = datetime.fromtimestamp(ts_end / 1000)
+            result.date_end = dt_end.strftime("%Y-%m-%d")
+            result.time_end = dt_end.strftime("%H:%M")
+        return result
+
+    if mode == "date":
+        result.date = _parse_date_str(value, order)
+    elif mode == "time":
+        h, m = value.split("-")
+        result.time = f"{h}:{m}"
+    elif mode == "datetime":
+        date_part, time_part = value.split("_")
+        result.date = _parse_date_str(date_part, order)
+        h, m = time_part.split("-")
+        result.time = f"{h}:{m}"
+    elif mode == "date-range":
+        parts = value.split("_")
+        result.date = _parse_date_str(parts[0], order)
+        result.date_end = _parse_date_str(parts[1], order)
+    elif mode == "time-range":
+        parts = value.split("_")
+        h1, m1 = parts[0].split("-")
+        h2, m2 = parts[1].split("-")
+        result.time = f"{h1}:{m1}"
+        result.time_end = f"{h2}:{m2}"
+
+    return result
+
+
+def _parse_date_str(value: str, order: DateOrder) -> str:
+    parts = value.split("-")
+    if order == "ymd":
+        return f"{parts[0]}-{parts[1]}-{parts[2]}"
+    elif order == "dmy":
+        return f"{parts[2]}-{parts[1]}-{parts[0]}"
+    else:  # mdy
+        return f"{parts[2]}-{parts[0]}-{parts[1]}"
+
+
+def parse_color(value: str, format: ColorFormat = "hex") -> ColorResult:
+    """Parse color widget result string."""
+    result = ColorResult(raw=value)
+    if format == "hex":
+        result.hex = f"#{value}"
+    elif format == "rgb":
+        parts = value.split("_")
+        result.rgb = (int(parts[0]), int(parts[1]), int(parts[2]))
+    elif format == "hsl":
+        parts = value.split("_")
+        result.hsl = (int(parts[0]), int(parts[1]), int(parts[2]))
+    return result
+
+
+def parse_schedule(value: str) -> ScheduleResult:
+    """Parse schedule widget result (bunch format: 56 chars, 8 per day)."""
+    if len(value) != 56:
+        raise ValueError(f"Schedule bunch format must be 56 chars, got {len(value)}")
+    days: list[ScheduleDay] = []
+    for i in range(7):
+        chunk = value[i * 8 : (i + 1) * 8]
+        if chunk == "00000000":
+            days.append(ScheduleDay(enabled=False))
+        else:
+            start = f"{chunk[0:2]}:{chunk[2:4]}"
+            end = f"{chunk[4:6]}:{chunk[6:8]}"
+            days.append(ScheduleDay(enabled=True, start=start, end=end))
+    return days

tgwidget/types.py

@@ -0,0 +1,14 @@
+from typing import Literal
+
+DateMode = Literal["date", "time", "datetime", "date-range", "time-range"]
+DateFormat = Literal["default", "unix-s", "unix-ms"]
+DateOrder = Literal["ymd", "dmy", "mdy"]
+ColorFormat = Literal["hex", "rgb", "hsl"]
+ColorScheme = Literal["light", "dark", "auto"]
+ScheduleFormat = Literal["bunch"]
+
+VALID_DATE_MODES = {"date", "time", "datetime", "date-range", "time-range"}
+VALID_DATE_FORMATS = {"default", "unix-s", "unix-ms"}
+VALID_DATE_ORDERS = {"ymd", "dmy", "mdy"}
+VALID_COLOR_FORMATS = {"hex", "rgb", "hsl"}
+VALID_COLOR_SCHEMES = {"light", "dark", "auto"}

tgwidget-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: tgwidget
+Version: 0.1.0
+Summary: Python SDK for TeleWidget — Telegram Mini App widgets
+Project-URL: Homepage, https://github.com/tgwidget/tgwidget-python
+Project-URL: Repository, https://github.com/tgwidget/tgwidget-python
+Author: tgwidget
+License-Expression: MIT
+Keywords: bot,mini-apps,telegram,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# tgwidget
+
+Python SDK for [TeleWidget](https://tgwidget.github.io/) — beautiful Telegram Mini App widgets for bots.
+
+## Install
+
+```bash
+pip install tgwidget
+```
+
+## Usage
+
+### Generate widget URL
+
+```python
+from tgwidget import TgWidget
+
+# Date picker
+url = TgWidget("your_bot").date(mode="datetime", format="unix-s").url()
+
+# Color picker
+url = TgWidget("your_bot").color(format="hex").url()
+
+# Schedule
+url = TgWidget("your_bot").schedule().url()
+
+# With styling
+url = (
+    TgWidget("your_bot")
+    .date(mode="date")
+    .style(color_scheme="dark", accent="#FF6600", adopt_tg_palette=True)
+    .url()
+)
+```
+
+### Parse results
+
+When a user completes the widget, the result comes back via deep link `t.me/your_bot?start=VALUE`. Parse the value:
+
+```python
+from tgwidget import parse_date, parse_color, parse_schedule
+
+# Date result
+result = parse_date("2025-03-15", mode="date")
+# DateResult(date='2025-03-15', time=None, ...)
+
+# Date range with unix timestamps
+result = parse_date("1710460800_1718236800", mode="date-range", format="unix-s")
+# DateResult(timestamp=1710460800, timestamp_end=1718236800, date='2025-03-15', ...)
+
+# Color result
+result = parse_color("FF6600", format="hex")
+# ColorResult(raw='FF6600', hex='#FF6600')
+
+# Schedule result (56-char bunch format)
+result = parse_schedule("09001800090018000000000009001800090018000000000000000000")
+# [ScheduleDay(enabled=True, start='09:00', end='18:00'), ...]
+```
+
+## API
+
+### `TgWidget(bot_username)`
+
+Create a widget builder.
+
+- `.date(mode, format, order)` — Date/time picker
+- `.color(format)` — Color picker
+- `.schedule()` — Weekly schedule
+- `.style(color_scheme, accent, tint, liquid_glass, adapt_tg_theme, adopt_tg_palette)` — Styling
+- `.url(base_url)` — Generate the final URL
+- `.payload()` — Get the raw payload dict
+
+### Parsers
+
+- `parse_date(value, mode, format, order)` → `DateResult`
+- `parse_color(value, format)` → `ColorResult`
+- `parse_schedule(value)` → `list[ScheduleDay]`

tgwidget-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+tgwidget/__init__.py,sha256=ETyxnugOQSsxCyQ5fgEngBjWxMixQDo2hpSvZ6ouZd8,183
+tgwidget/builder.py,sha256=QVN2_pSk-6UcsSg9ha20DzuSBP6XNMgm2qUzs77DvsU,3753
+tgwidget/parser.py,sha256=6ge6Zhi50xzk8Aopgo3h3ZJxdYhJhz-hBiQwgJaARl8,3980
+tgwidget/types.py,sha256=IE7oF1Qt1w2-k5PSPB8hD6stxqw5baT-5dc1iXTqAig,586
+tgwidget-0.1.0.dist-info/METADATA,sha256=orT3CYbS09gmLiw3j1itR3gbrP2zTJyY-OZoXNrPkgM,2610
+tgwidget-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tgwidget-0.1.0.dist-info/RECORD,,

tgwidget-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any