moonlygram 0.1.0__tar.gz

moonlygram-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests codegen
+      - name: Type-check
+        run: mypy
+      - name: Test
+        run: pytest -q
+
+  codegen-fresh:
+    # Fails if _types_generated.py was hand-edited or left stale after a spec or
+    # overrides change — the generator output must always be committed.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Regenerate types
+        run: python codegen/gen_types.py
+      - name: Verify no drift
+        run: git diff --exit-code -- src/moonlygram/_types_generated.py

moonlygram-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[docs]"
+      - name: Build and deploy
+        run: mkdocs gh-deploy --force --strict

moonlygram-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed. Uses PyPI trusted publishing
+# (OIDC) — no API token needed once the project is configured on PyPI; see
+# https://docs.pypi.org/trusted-publishers/. Configure the publisher to point at
+# this repository and the "pypi" environment below.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

moonlygram-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Docs build
+site/
+
+# Editor / tooling local settings
+.claude/settings.local.json
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

moonlygram-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+First public release.
+
+### Added
+- Async `Bot` covering the common Bot API surface: messaging and editing,
+  media, chat and member management, bot configuration, forum topics, stickers,
+  inline mode, and the remaining update types.
+- `moonlygram.ext`: `Application` + `ApplicationBuilder`, handler groups,
+  filters, `ConversationHandler` (timeouts, nesting, persistence), `JobQueue`,
+  rate limiting, arbitrary callback data, and concurrent dispatch.
+- Rich messages (Bot API 10.1): the `RichMessage` builder, inline helpers, and
+  `markdown_to_rich`.
+- A typed error hierarchy, builder lifecycle hooks, a `helpers` module, and
+  `ContextTypes`.
+- Spec-driven type generation (`codegen/`) producing the received data types
+  with full field coverage, guarded by drift tests.
+- `py.typed`: the package ships type information and passes `mypy --strict`.

moonlygram-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for your interest in Moonlygram. This guide covers the local workflow and
+the one piece that is unusual: the type generator.
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the checks the way CI does:
+
+```bash
+ruff check src tests codegen
+mypy
+pytest -q
+```
+
+All three must pass. Tests are offline (no network, no real bot token).
+
+## House style
+
+- Docstrings and comments are **plain prose** — no Sphinx cross-references
+  (`:class:`, `:meth:`), and no formal Args/Returns blocks beyond the few that
+  already exist. Explain the *why* of a non-obvious choice in a short comment.
+- Public API is re-exported through the package `__init__` files, each with an
+  explicit `__all__`.
+- The package ships `py.typed` and must stay `mypy --strict` clean.
+
+## The type generator (important)
+
+The data-only Bot API *received* types in `src/moonlygram/_types_generated.py`
+are **generated** from a vendored copy of the Bot API spec. **Do not edit that
+file by hand** — CI regenerates it and fails if it differs.
+
+To change what is modelled:
+
+1. Edit `codegen/overrides.py` (the allowlist, flat unions, and per-field
+   overrides) — and, for a new API version, refresh the spec:
+   ```bash
+   python codegen/refresh.py
+   ```
+2. Regenerate:
+   ```bash
+   python codegen/gen_types.py
+   ```
+3. Run the suite. The drift guards in `tests/test_codegen.py` check that every
+   generated type matches the spec and that the file is up to date.
+
+Behavior-bearing types (those with shortcut methods or custom binding, such as
+`Message`, `Chat`, `User`) and the *sent* types (keyboards, input media, inline
+query results) stay hand-written in `src/moonlygram/types.py`.
+
+## Docs
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+The API reference is generated from docstrings by `mkdocstrings`, so keeping
+docstrings accurate keeps the docs accurate.

moonlygram-0.1.0/LICENSE

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

moonlygram-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: moonlygram
+Version: 0.1.0
+Summary: An async Telegram Bot API client with built-in rich-message support.
+Project-URL: Homepage, https://github.com/AtarixiaFamine/Moonlygram
+Project-URL: Repository, https://github.com/AtarixiaFamine/Moonlygram
+Project-URL: Issues, https://github.com/AtarixiaFamine/Moonlygram/issues
+Project-URL: Changelog, https://github.com/AtarixiaFamine/Moonlygram/blob/main/CHANGELOG.md
+Author: AtarixiaFamine
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,bot,bot-api,rich-messages,telegram
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<h1 align="center">Moonlygram</h1>
+
+<p align="center">
+  <b>A modern, async Python framework for the Telegram Bot API, with built-in rich messages.</b>
+  <br>
+  Pure HTTP. No MTProto. No native dependencies.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/moonlygram/"><img src="https://img.shields.io/pypi/v/moonlygram.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/moonlygram.svg" alt="Python versions">
+  <img src="https://img.shields.io/badge/mypy-strict-blue.svg" alt="mypy strict">
+  <img src="https://img.shields.io/badge/Bot%20API-10.1-2CA5E0.svg" alt="Bot API 10.1">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+</p>
+
+---
+
+## Description
+
+**Moonlygram** is an asynchronous framework for the Telegram **Bot API**. A `Bot` holds the API
+methods and an `Application` (`moonlygram.ext`) registers handlers and runs the update loop, so
+the shape feels familiar if you have used [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot).
+On top of that, it adds something no other library has: **rich messages** (Bot API 10.1).
+
+## Installation
+
+```bash
+pip install moonlygram
+```
+
+Requires Python 3.10 or newer.
+
+## Usage
+
+```python
+from moonlygram import InlineKeyboardButton, InlineKeyboardMarkup
+from moonlygram.ext import Application, CallbackQueryHandler, CommandHandler
+
+
+async def start(update, context):
+    keyboard = InlineKeyboardMarkup([[InlineKeyboardButton("Tap me", callback_data="tapped")]])
+    await update.message.reply_text("Hello from Moonlygram!", reply_markup=keyboard)
+
+
+async def on_tap(update, context):
+    await update.callback_query.answer("You tapped it!")
+
+
+app = Application.builder().token("YOUR_BOT_TOKEN").build()
+app.add_handler(CommandHandler("start", start))
+app.add_handler(CallbackQueryHandler(on_tap, pattern="^tapped$"))
+app.run_polling()
+```
+
+## Features
+
+- **Familiar:** a python-telegram-bot-style API: `Application`, handlers, filters, and
+  `(update, context)` callbacks. Existing bots port with little more than renamed imports.
+- **Async:** receiving and dispatch run concurrently, so a slow handler never stalls the next
+  update.
+- **Performant:** a non-blocking poll loop, optional parallel dispatch, a built-in rate limiter,
+  and a dependency-free `JobQueue`.
+- **Rich:** send Bot API 10.1 rich messages (headings, tables, collapsibles, math) with a
+  composable, auto-escaping builder, or convert Markdown in one call. No other library has this.
+- **Type-hinted:** ships `py.typed` and passes `mypy --strict`. The received types are generated
+  from the Bot API schema, so they cannot silently drift.
+- **Lightweight:** one dependency (`httpx`). Pure HTTP, with no MTProto, no `api_id`/`api_hash`,
+  and no C extensions.
+- **Batteries included:** conversations, persistence, scheduled jobs, arbitrary callback data,
+  and both polling and webhooks.
+
+## Resources
+
+- **Documentation:** https://atarixiafamine.github.io/Moonlygram/
+- **Migrating from python-telegram-bot:** https://atarixiafamine.github.io/Moonlygram/migrating/
+- **Examples:** [`examples/`](examples/)
+- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+
+## Roadmap
+
+Core messaging, media, chat and member administration, bot configuration, forum topics,
+stickers, and inline mode are all covered. Still in progress: the niche Bot API domains of
+payments / Telegram Stars, business accounts, games, and passport / giveaways / paid media.
+
+## Contributing
+
+Contributions are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md); it covers the spec-driven
+codegen workflow for data types (edit the spec or overrides, regenerate, then test).
+
+## License
+
+Released under the **MIT License**. See [`LICENSE`](LICENSE). Copyright © 2026 AtarixiaFamine.

moonlygram-0.1.0/README.md

@@ -0,0 +1,93 @@
+<h1 align="center">Moonlygram</h1>
+
+<p align="center">
+  <b>A modern, async Python framework for the Telegram Bot API, with built-in rich messages.</b>
+  <br>
+  Pure HTTP. No MTProto. No native dependencies.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/moonlygram/"><img src="https://img.shields.io/pypi/v/moonlygram.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/moonlygram.svg" alt="Python versions">
+  <img src="https://img.shields.io/badge/mypy-strict-blue.svg" alt="mypy strict">
+  <img src="https://img.shields.io/badge/Bot%20API-10.1-2CA5E0.svg" alt="Bot API 10.1">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+</p>
+
+---
+
+## Description
+
+**Moonlygram** is an asynchronous framework for the Telegram **Bot API**. A `Bot` holds the API
+methods and an `Application` (`moonlygram.ext`) registers handlers and runs the update loop, so
+the shape feels familiar if you have used [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot).
+On top of that, it adds something no other library has: **rich messages** (Bot API 10.1).
+
+## Installation
+
+```bash
+pip install moonlygram
+```
+
+Requires Python 3.10 or newer.
+
+## Usage
+
+```python
+from moonlygram import InlineKeyboardButton, InlineKeyboardMarkup
+from moonlygram.ext import Application, CallbackQueryHandler, CommandHandler
+
+
+async def start(update, context):
+    keyboard = InlineKeyboardMarkup([[InlineKeyboardButton("Tap me", callback_data="tapped")]])
+    await update.message.reply_text("Hello from Moonlygram!", reply_markup=keyboard)
+
+
+async def on_tap(update, context):
+    await update.callback_query.answer("You tapped it!")
+
+
+app = Application.builder().token("YOUR_BOT_TOKEN").build()
+app.add_handler(CommandHandler("start", start))
+app.add_handler(CallbackQueryHandler(on_tap, pattern="^tapped$"))
+app.run_polling()
+```
+
+## Features
+
+- **Familiar:** a python-telegram-bot-style API: `Application`, handlers, filters, and
+  `(update, context)` callbacks. Existing bots port with little more than renamed imports.
+- **Async:** receiving and dispatch run concurrently, so a slow handler never stalls the next
+  update.
+- **Performant:** a non-blocking poll loop, optional parallel dispatch, a built-in rate limiter,
+  and a dependency-free `JobQueue`.
+- **Rich:** send Bot API 10.1 rich messages (headings, tables, collapsibles, math) with a
+  composable, auto-escaping builder, or convert Markdown in one call. No other library has this.
+- **Type-hinted:** ships `py.typed` and passes `mypy --strict`. The received types are generated
+  from the Bot API schema, so they cannot silently drift.
+- **Lightweight:** one dependency (`httpx`). Pure HTTP, with no MTProto, no `api_id`/`api_hash`,
+  and no C extensions.
+- **Batteries included:** conversations, persistence, scheduled jobs, arbitrary callback data,
+  and both polling and webhooks.
+
+## Resources
+
+- **Documentation:** https://atarixiafamine.github.io/Moonlygram/
+- **Migrating from python-telegram-bot:** https://atarixiafamine.github.io/Moonlygram/migrating/
+- **Examples:** [`examples/`](examples/)
+- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
+
+## Roadmap
+
+Core messaging, media, chat and member administration, bot configuration, forum topics,
+stickers, and inline mode are all covered. Still in progress: the niche Bot API domains of
+payments / Telegram Stars, business accounts, games, and passport / giveaways / paid media.
+
+## Contributing
+
+Contributions are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md); it covers the spec-driven
+codegen workflow for data types (edit the spec or overrides, regenerate, then test).
+
+## License
+
+Released under the **MIT License**. See [`LICENSE`](LICENSE). Copyright © 2026 AtarixiaFamine.

moonlygram-0.1.0/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+Moonlygram is pre-1.0; security fixes are released against the latest version only.
+
+| Version    | Supported |
+| ---------- | --------- |
+| latest 0.x | ✅        |
+| older      | ❌        |
+
+## Reporting a Vulnerability
+
+Please **do not open a public issue** for security vulnerabilities.
+
+Report privately through GitHub's [private vulnerability reporting](https://github.com/AtarixiaFamine/Moonlygram/security/advisories/new)
+(the repo's **Security → Report a vulnerability** button). Include:
+
+- a description of the issue and its impact,
+- steps to reproduce (a minimal proof of concept if possible),
+- the affected version(s).
+
+Expect an acknowledgement within a few days. Once confirmed, I'll prepare and
+release a fix and credit you in the advisory unless you'd rather stay anonymous.
+Please allow a reasonable window before any public disclosure.
+
+## Scope
+
+Moonlygram is an HTTP client for the Telegram Bot API. Your **bot token is a
+secret**: keep it out of source control and logs, and set the `secret_token`
+option on webhooks so you can verify requests really come from Telegram. Token
+leakage in your own code is outside this project's scope.