ferogram 0.5.0b2__tar.gz → 0.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. {ferogram-0.5.0b2 → ferogram-0.5.1}/CHANGELOG.md +102 -5
  2. {ferogram-0.5.0b2 → ferogram-0.5.1}/Cargo.lock +1 -1
  3. {ferogram-0.5.0b2 → ferogram-0.5.1}/Cargo.toml +2 -2
  4. ferogram-0.5.1/PKG-INFO +132 -0
  5. ferogram-0.5.1/README.md +107 -0
  6. ferogram-0.5.1/assets/architecture.svg +130 -0
  7. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/admin_tools.py +5 -4
  8. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/command_bot.py +5 -4
  9. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/echo_bot.py +5 -4
  10. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/group_management.py +5 -4
  11. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/media_bot.py +5 -4
  12. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/raw_invoke.py +6 -5
  13. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/search_bot.py +5 -4
  14. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/send_hi.py +6 -5
  15. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/send_media.py +8 -5
  16. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/send_message.py +5 -4
  17. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/update_handlers.py +6 -5
  18. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/user_management.py +6 -5
  19. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/userbot.py +7 -5
  20. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/__init__.py +5 -4
  21. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/client.py +148 -18
  22. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/filters.py +16 -7
  23. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/keyboards.py +5 -4
  24. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/logging.py +5 -4
  25. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/__init__.py +5 -4
  26. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/api/__init__.py +5 -4
  27. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/api/functions.py +5 -4
  28. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/api/types.py +5 -4
  29. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/codegen.py +10 -8
  30. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/__init__.py +5 -4
  31. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/_tl_schema.py +5 -4
  32. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/__init__.py +5 -4
  33. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/account.py +5 -4
  34. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/aicompose.py +5 -4
  35. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/auth.py +5 -4
  36. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/bots.py +5 -4
  37. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/channels.py +5 -4
  38. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/chatlists.py +5 -4
  39. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/contacts.py +5 -4
  40. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/folders.py +5 -4
  41. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/fragment.py +5 -4
  42. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/help.py +5 -4
  43. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/langpack.py +5 -4
  44. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/messages.py +5 -4
  45. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/payments.py +5 -4
  46. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/phone.py +5 -4
  47. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/photos.py +5 -4
  48. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/premium.py +5 -4
  49. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/smsjobs.py +5 -4
  50. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/stats.py +5 -4
  51. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/stickers.py +5 -4
  52. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/stories.py +5 -4
  53. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/updates.py +5 -4
  54. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/upload.py +5 -4
  55. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/functions/users.py +5 -4
  56. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/__init__.py +5 -4
  57. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/_base.py +5 -4
  58. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/account.py +5 -4
  59. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/aicompose.py +5 -4
  60. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/auth.py +5 -4
  61. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/bots.py +5 -4
  62. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/channels.py +5 -4
  63. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/chatlists.py +5 -4
  64. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/contacts.py +5 -4
  65. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/fragment.py +5 -4
  66. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/help.py +5 -4
  67. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/messages.py +5 -4
  68. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/payments.py +5 -4
  69. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/phone.py +5 -4
  70. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/photos.py +5 -4
  71. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/premium.py +5 -4
  72. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/smsjobs.py +5 -4
  73. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/stats.py +5 -4
  74. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/stickers.py +5 -4
  75. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/storage.py +5 -4
  76. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/stories.py +5 -4
  77. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/updates.py +5 -4
  78. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/upload.py +5 -4
  79. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/generated/types/users.py +5 -4
  80. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/proxy.py +5 -4
  81. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/raw/tl.py +5 -4
  82. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/types.py +87 -6
  83. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/updates.py +170 -22
  84. {ferogram-0.5.0b2 → ferogram-0.5.1}/pyproject.toml +2 -2
  85. ferogram-0.5.0b2/PKG-INFO +0 -152
  86. ferogram-0.5.0b2/README.md +0 -127
  87. {ferogram-0.5.0b2 → ferogram-0.5.1}/.github/workflows/compile-check.yml +0 -0
  88. {ferogram-0.5.0b2 → ferogram-0.5.1}/.github/workflows/publish.yml +0 -0
  89. {ferogram-0.5.0b2 → ferogram-0.5.1}/.gitignore +0 -0
  90. {ferogram-0.5.0b2 → ferogram-0.5.1}/.readthedocs.yaml +0 -0
  91. {ferogram-0.5.0b2 → ferogram-0.5.1}/FEATURES.md +0 -0
  92. {ferogram-0.5.0b2 → ferogram-0.5.1}/LICENSE-APACHE +0 -0
  93. {ferogram-0.5.0b2 → ferogram-0.5.1}/LICENSE-MIT +0 -0
  94. {ferogram-0.5.0b2 → ferogram-0.5.1}/Makefile +0 -0
  95. {ferogram-0.5.0b2 → ferogram-0.5.1}/build.rs +0 -0
  96. {ferogram-0.5.0b2 → ferogram-0.5.1}/examples/rich_message.py +0 -0
  97. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/api.tl +0 -0
  98. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/py.typed +0 -0
  99. {ferogram-0.5.0b2 → ferogram-0.5.1}/ferogram/rich.py +0 -0
  100. {ferogram-0.5.0b2 → ferogram-0.5.1}/src/connection.rs +0 -0
  101. {ferogram-0.5.0b2 → ferogram-0.5.1}/src/lib.rs +0 -0
  102. {ferogram-0.5.0b2 → ferogram-0.5.1}/src/raw.rs +0 -0
  103. {ferogram-0.5.0b2 → ferogram-0.5.1}/src/session.rs +0 -0
  104. {ferogram-0.5.0b2 → ferogram-0.5.1}/src/srp.rs +0 -0
  105. {ferogram-0.5.0b2 → ferogram-0.5.1}/tests/test_rich.py +0 -0
  106. {ferogram-0.5.0b2 → ferogram-0.5.1}/tests/test_tl_roundtrip.py +0 -0
@@ -1,3 +1,104 @@
1
+ ## 0.5.1 (2026-06-29)
2
+
3
+ ## What's Changed
4
+
5
+ ### Message API Improvements
6
+
7
+ - `Message.reply()` now creates a proper quoted reply using `reply_to=self.id`.
8
+ - Added `Message.respond()` for sending messages to the same chat without replying.
9
+ - Added `pin()`, `forward_to()`, `get_sender()`, `get_chat()`, and `get_reply_message()` helpers.
10
+ - Added `reply_photo()` and `reply_document()` convenience methods.
11
+ - Improved `delete()` to correctly handle channels and supergroups.
12
+
13
+ ### Client Enhancements
14
+
15
+ - Added `reply_to` support to `send_message()`, `send_photo()`, and `send_document()`.
16
+ - Added `Client.get_user()` and `Client.get_chat()` helpers.
17
+ - `edit_message()` now accepts `reply_markup`.
18
+ - `pin_message()` now supports a `notify` parameter.
19
+ - Improved `delete_messages_in()` for channel-aware message deletion.
20
+ - Improved sent message extraction fallback behavior with warning logging and preserved context.
21
+
22
+ ### Update Improvements
23
+
24
+ - Added convenience methods to `CallbackQuery`:
25
+ - `respond()`
26
+ - `reply()`
27
+ - `edit_message_text()`
28
+ - `get_sender()`
29
+
30
+ - Added convenience methods to `InlineQuery`:
31
+ - `answer()`
32
+ - `get_sender()`
33
+
34
+ - Added sender/entity helpers for additional update types, including:
35
+ - `InlineSend`
36
+ - `UserStatus`
37
+ - `ChatAction`
38
+ - `JoinRequest`
39
+ - `ParticipantUpdate`
40
+ - `MessageReaction`
41
+ - `ChatBoost`
42
+ - `ShippingQuery`
43
+ - `PreCheckoutQuery`
44
+
45
+ ### Dispatch Improvements
46
+
47
+ - `_dispatch()` now binds `_client` for all update types.
48
+ - Added `_client` support to remaining update wrappers, including `RawUpdate`.
49
+ - Improved sent message extraction fallback handling.
50
+
51
+ ## 0.5.0 (2026-06-28)
52
+
53
+ ### Architecture
54
+
55
+ The Rust dependency has changed from the monolithic `ferogram` crate to five focused crates from the ferogram core:
56
+
57
+ - `ferogram-mtsender` - MTProto sender, message framing, and acknowledgement
58
+ - `ferogram-session` - session storage (file, sqlite, libsql, memory, string)
59
+ - `ferogram-connect` - TCP/TLS transport and DC routing
60
+ - `ferogram-tl-types` - generated TL type definitions
61
+ - `ferogram-crypto` - AES-IGE, Diffie-Hellman, and SHA helpers
62
+
63
+ These five crates form the battle-tested lower layer of ferogram. They change rarely and are stable across minor versions. All high-level logic (message parsing, update dispatch, peer resolution, serialization, deserialization) now lives in Python. This split means the compiled extension is smaller and faster to build, and Python-side behaviour can be updated without recompiling the Rust extension.
64
+
65
+ The compiled extension now uses `abi3-py39` (was `abi3-py313`), so a single wheel runs on Python 3.9 and later.
66
+
67
+ ### Added
68
+
69
+ - **`TransferHandle`** - pause, resume, and cancel any upload or download in flight. Create a `TransferHandle`, pass it to `upload_with_progress` or `download_with_progress`, then call `.pause()`, `.resume()`, or `.cancel()` from any coroutine. `.progress()` returns a dict with `done`, `total`, `elapsed_ms`, `percent`, `speed_bps`, `eta_secs`, `speed_human`, and `bytes_human`.
70
+ - **`TransferCancelled` exception** - raised when a `TransferHandle` is cancelled mid-transfer.
71
+ - **`keyboards` module** - `InlineKeyboard`, `InlineButton`, `ReplyKeyboard`, `ReplyButton`, `RemoveKeyboard`, and `ForceReply` are now pure Python and importable from `ferogram` directly.
72
+ - **`types` module** - all entity types (`User`, `Message`, `Chat`, `Dialog`, `ChatMember`, `UserFull`, `Authorization`, `ForumTopic`, `BotInfo`, `InviteLinkMember`, `ReadParticipant`, `AdminLogEvent`, `StickerSetInfo`, `BroadcastStats`, `MegagroupStats`, `NotifySettings`) moved from Rust to Python dataclasses. The public API is identical.
73
+ - **`updates` module** - update wrapper types (`NewMessage`, `EditedMessage`, `MessageDeletion`, `CallbackQuery`, `InlineQuery`, `InlineSend`, `UserStatus`, `ParticipantUpdate`, `JoinRequest`, `MessageReaction`, `PollVote`, `BotStopped`, `ShippingQuery`, `PreCheckoutQuery`, `ChatBoost`, `RawUpdate`) moved from Rust to Python dataclasses.
74
+ - **`rich` module** - `send_rich_message`, `edit_rich_message`, `send_rich_message_draft`, and `get_rich_message` via a `_RichMixin`. Supports Telegram rich text blocks including headers, tables, collages, task lists, footnotes, math, time stamps, and custom emoji via Markdown or HTML input.
75
+ - **Automatic TL codegen at build time** - `build.rs` now runs `ferogram/raw/codegen.py` during `maturin develop` / `pip install .`. Set `FEROGRAM_SKIP_CODEGEN=1` to skip if you only changed Rust. The codegen uses the same Python interpreter maturin selected.
76
+ - **`DcConnection` and `srp_calculate`** exposed from the Rust extension for use by the pure-Python `Client` class.
77
+ - **`LAYER` constant** exported from `ferogram.raw.generated._tl_schema` and used automatically in `invokeWithLayer` wrappers.
78
+ - **`all_updates` filter** - replaces the old `all` filter (which shadowed the built-in).
79
+ - **`filters` improvements** - all filters now unwrap `NewMessage` / `EditedMessage` wrapper objects before inspecting the inner `Message`. Previously filters broke when the dispatcher passed wrapper objects instead of bare messages.
80
+
81
+ ### Changed
82
+
83
+ - `Message`, `User`, `Chat`, and all entity types are now Python dataclasses instead of PyO3 structs. They serialize to / from the TL dict representation in Python. No change to the public API.
84
+ - `CallbackQuery`, `InlineQuery`, and all update types are now Python dataclasses.
85
+ - `InlineKeyboard`, `ReplyKeyboard`, and related keyboard builders are now pure Python (`ferogram/keyboards.py`). Previously they were Rust structs.
86
+ - Filters rewritten to correctly unwrap update wrapper objects. `reply` filter now checks `reply_to_msg_id`; `forwarded` checks `forward_from_id`; `media` checks the `media` field directly.
87
+ - `codegen.py` doubled in size (321 to 691 lines): now generates specialized `to_bytes()` methods using `struct.pack` inline and a CID-dispatch `from_bytes()` router, producing faster serialization and deserialization than the previous schema-dict approach.
88
+ - `ferogram-py` version bump to 0.5.0. Core crates pinned to `ferogram-*` 0.6.3.
89
+
90
+ ### Removed
91
+
92
+ - Direct dependency on the monolithic `ferogram` crate. The five focused crates replace it.
93
+ - `hex` crate dependency (was `0.4`, now unused).
94
+ - `all` filter removed and replaced with `all_updates` to avoid shadowing Python's built-in `all`.
95
+
96
+
97
+ ## 0.4.1 (2026-06-03)
98
+
99
+ Patch release. No API changes. Identical to 0.4.0 except for dependency pins and minor internal fixes.
100
+
101
+
1
102
  ## 0.4.0 (2026-06-01)
2
103
 
3
104
  ### Added
@@ -20,7 +121,7 @@
20
121
  - **`flood_sleep_threshold` kwarg on `Client`** - maps to the `AutoSleep` retry policy in the Rust core. Flood waits under this value are slept through automatically; waits above it are raised as exceptions.
21
122
  - **`download_with_progress(peer, msg_id, path, on_progress)`** - download media with a progress callback `on_progress(done, total)`.
22
123
  - **`upload_with_progress(path, on_progress)`** - upload a file with a progress callback. Returns a handle string accepted by `send_file`.
23
- - **`ferogram` 0.6.0 as core dependency** - includes `Client.channel_kind_of(channel_id)` which backs the new `Message` methods above.
124
+ - **ferogram 0.6.0 as core dependency** - includes `Client.channel_kind_of(channel_id)` which backs the new `Message` methods above.
24
125
 
25
126
  ### Changed
26
127
 
@@ -62,9 +163,6 @@ the votes graph as a JSON string. The old `get_poll_results(peer, msg_id, poll_h
62
163
  is kept for backward compat but is deprecated; the `poll_hash` parameter is ignored
63
164
  because ferogram 0.5.0 dropped the underlying API call it relied on.
64
165
 
65
- ---
66
-
67
- # Changelog
68
166
 
69
167
  ## 0.2.3 (2026-05-14)
70
168
 
@@ -124,7 +222,6 @@ Ten new methods for managing group and channel members.
124
222
 
125
223
  `get_poll_results(peer, msg_id, poll_hash)` was in Rust but had no Python wrapper. Now exposed. Fetches and caches the latest poll results from Telegram.
126
224
 
127
- ---
128
225
 
129
226
  ## 0.2.2
130
227
 
@@ -457,7 +457,7 @@ dependencies = [
457
457
 
458
458
  [[package]]
459
459
  name = "ferogram-py"
460
- version = "0.5.0"
460
+ version = "0.5.1"
461
461
  dependencies = [
462
462
  "base64 0.22.1",
463
463
  "ferogram-connect",
@@ -1,8 +1,8 @@
1
1
  [package]
2
2
  name = "ferogram-py"
3
- version = "0.5.0"
3
+ version = "0.5.1"
4
4
  edition = "2024"
5
- description = "Python bindings for ferogram (Rust MTProto)"
5
+ description = "Python MTProto client based on ferogram (Rust MTProto)"
6
6
  build = "build.rs"
7
7
  license = "MIT OR Apache-2.0"
8
8
  readme = "README.md"
@@ -0,0 +1,132 @@
1
+ Metadata-Version: 2.4
2
+ Name: ferogram
3
+ Version: 0.5.1
4
+ Classifier: Development Status :: 3 - Alpha
5
+ Classifier: Intended Audience :: Developers
6
+ Classifier: License :: OSI Approved :: MIT License
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Rust
9
+ Classifier: Topic :: Communications :: Chat
10
+ Classifier: Topic :: Software Development :: Libraries
11
+ License-File: LICENSE-APACHE
12
+ License-File: LICENSE-MIT
13
+ Summary: Python MTProto library powered by ferogram, a high-performance Rust engine for Telegram.
14
+ Keywords: telegram,mtproto,rust,client,bot,ferogram
15
+ Author-email: Ankit Chaubey <ankitchaubey.dev@gmail.com>
16
+ License: MIT OR Apache-2.0
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
19
+ Project-URL: Author, https://github.com/ankit-chaubey
20
+ Project-URL: Documentation, https://github.com/ankit-chaubey/ferogram-py#readme
21
+ Project-URL: Homepage, https://github.com/ankit-chaubey/ferogram-py
22
+ Project-URL: Source, https://github.com/ankit-chaubey/ferogram-py
23
+ Project-URL: Tracker, https://github.com/ankit-chaubey/ferogram-py/issues
24
+
25
+ # ferogram-py
26
+
27
+ A Python MTProto library powered by the Rust-based [ferogram](https://github.com/ankit-chaubey/ferogram) engine, delivering near-native performance with minimal Python overhead.
28
+
29
+ Built with [PyO3](https://pyo3.rs) and [maturin](https://maturin.rs). Works on Linux, macOS, Windows, and Android (Termux).
30
+
31
+ ---
32
+
33
+ ## Why ferogram-py?
34
+
35
+ ferogram-py combines Python's simplicity with the speed and efficiency of a native Rust implementation.
36
+
37
+ Performance-critical components such as networking, encryption, session management, and MTProto internals run natively in Rust, reducing Python overhead while exposing a clean and Pythonic API.
38
+
39
+ Whether you're building userbots, bots, or automation tools, ferogram-py provides both high-level abstractions and direct access to raw Telegram APIs when needed.
40
+
41
+ > Quick API reference: [FEATURES.md](./FEATURES.md)
42
+
43
+ ---
44
+
45
+ ## Install
46
+
47
+ ```bash
48
+ pip install ferogram
49
+ ```
50
+
51
+ Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, arm64), Windows (x86_64), and Android/Termux (aarch64, x86_64).
52
+
53
+ `pip install ferogram` picks the correct wheel automatically.
54
+
55
+ ---
56
+
57
+ ### Build from source
58
+
59
+ Clone the repository, then run:
60
+
61
+ ```bash
62
+ make dev # editable install into .venv (builds Rust extension)
63
+ make build # release wheel for this machine
64
+ make codegen # regen TL generated code without a Rust build
65
+ make test # run tests
66
+ make clean # remove .venv, target, dist, generated/
67
+ ```
68
+
69
+ Termux prerequisites: `pkg install rust clang python`
70
+
71
+ To skip TL codegen on a Rust-only change: `FEROGRAM_SKIP_CODEGEN=1 maturin develop`
72
+
73
+ ## Quick start
74
+
75
+ ```python
76
+ from ferogram import Client, filters
77
+
78
+ app = Client("mybot", api_id=0, api_hash="", bot_token="123:TOKEN")
79
+
80
+ @app.on_message(filters.command("start"))
81
+ async def start(client, message):
82
+ await message.reply("Hello!")
83
+
84
+ app.run()
85
+ ```
86
+
87
+ Credentials can also come from env vars: `API_ID`, `API_HASH`, `BOT_TOKEN`.
88
+
89
+ ## Logging
90
+
91
+ ```python
92
+ import ferogram.logging as fero_log
93
+
94
+ fero_log.setup() # INFO to stderr
95
+ fero_log.setup(level=10) # DEBUG
96
+ ```
97
+
98
+ ## Architecture
99
+
100
+ ![architecture](assets/architecture.svg)
101
+
102
+ The compiled extension (`_ferogram.so`) is intentionally minimal. Networking, encryption, session management, and MTProto internals are implemented in Rust, while the high-level API remains entirely in Python and can be updated without recompiling rust core.
103
+
104
+ ---
105
+
106
+ ## License
107
+
108
+ This project is dual-licensed under:
109
+
110
+ - MIT License
111
+ - Apache License 2.0
112
+
113
+ You may choose either license.
114
+
115
+ You are free to use, modify, and distribute this software, including for commercial use, provided the original license and copyright notice are included.
116
+
117
+ See `LICENSE-MIT` and `LICENSE-APACHE` for full details.
118
+
119
+ ---
120
+
121
+ ## Developer
122
+
123
+ Developed by [Ankit Chaubey](https://github.com/ankit-chaubey)
124
+
125
+ Don't forget to explore the Rust engine powering ferogram-py: [ferogram](https://github.com/ankit-chaubey/ferogram). Thanks for being part of the journey.
126
+
127
+ Join the ferogram community! Questions, discussions, and feedback are always welcome. As the project grows, we'll eventually split Python and Rust discussions into dedicated spaces.
128
+
129
+ - Channel (releases & announcements): [@Ferogram](https://t.me/Ferogram)
130
+
131
+ - (questions & discussion): [@FerogramChat](https://t.me/FerogramChat)
132
+
@@ -0,0 +1,107 @@
1
+ # ferogram-py
2
+
3
+ A Python MTProto library powered by the Rust-based [ferogram](https://github.com/ankit-chaubey/ferogram) engine, delivering near-native performance with minimal Python overhead.
4
+
5
+ Built with [PyO3](https://pyo3.rs) and [maturin](https://maturin.rs). Works on Linux, macOS, Windows, and Android (Termux).
6
+
7
+ ---
8
+
9
+ ## Why ferogram-py?
10
+
11
+ ferogram-py combines Python's simplicity with the speed and efficiency of a native Rust implementation.
12
+
13
+ Performance-critical components such as networking, encryption, session management, and MTProto internals run natively in Rust, reducing Python overhead while exposing a clean and Pythonic API.
14
+
15
+ Whether you're building userbots, bots, or automation tools, ferogram-py provides both high-level abstractions and direct access to raw Telegram APIs when needed.
16
+
17
+ > Quick API reference: [FEATURES.md](./FEATURES.md)
18
+
19
+ ---
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ pip install ferogram
25
+ ```
26
+
27
+ Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, arm64), Windows (x86_64), and Android/Termux (aarch64, x86_64).
28
+
29
+ `pip install ferogram` picks the correct wheel automatically.
30
+
31
+ ---
32
+
33
+ ### Build from source
34
+
35
+ Clone the repository, then run:
36
+
37
+ ```bash
38
+ make dev # editable install into .venv (builds Rust extension)
39
+ make build # release wheel for this machine
40
+ make codegen # regen TL generated code without a Rust build
41
+ make test # run tests
42
+ make clean # remove .venv, target, dist, generated/
43
+ ```
44
+
45
+ Termux prerequisites: `pkg install rust clang python`
46
+
47
+ To skip TL codegen on a Rust-only change: `FEROGRAM_SKIP_CODEGEN=1 maturin develop`
48
+
49
+ ## Quick start
50
+
51
+ ```python
52
+ from ferogram import Client, filters
53
+
54
+ app = Client("mybot", api_id=0, api_hash="", bot_token="123:TOKEN")
55
+
56
+ @app.on_message(filters.command("start"))
57
+ async def start(client, message):
58
+ await message.reply("Hello!")
59
+
60
+ app.run()
61
+ ```
62
+
63
+ Credentials can also come from env vars: `API_ID`, `API_HASH`, `BOT_TOKEN`.
64
+
65
+ ## Logging
66
+
67
+ ```python
68
+ import ferogram.logging as fero_log
69
+
70
+ fero_log.setup() # INFO to stderr
71
+ fero_log.setup(level=10) # DEBUG
72
+ ```
73
+
74
+ ## Architecture
75
+
76
+ ![architecture](assets/architecture.svg)
77
+
78
+ The compiled extension (`_ferogram.so`) is intentionally minimal. Networking, encryption, session management, and MTProto internals are implemented in Rust, while the high-level API remains entirely in Python and can be updated without recompiling rust core.
79
+
80
+ ---
81
+
82
+ ## License
83
+
84
+ This project is dual-licensed under:
85
+
86
+ - MIT License
87
+ - Apache License 2.0
88
+
89
+ You may choose either license.
90
+
91
+ You are free to use, modify, and distribute this software, including for commercial use, provided the original license and copyright notice are included.
92
+
93
+ See `LICENSE-MIT` and `LICENSE-APACHE` for full details.
94
+
95
+ ---
96
+
97
+ ## Developer
98
+
99
+ Developed by [Ankit Chaubey](https://github.com/ankit-chaubey)
100
+
101
+ Don't forget to explore the Rust engine powering ferogram-py: [ferogram](https://github.com/ankit-chaubey/ferogram). Thanks for being part of the journey.
102
+
103
+ Join the ferogram community! Questions, discussions, and feedback are always welcome. As the project grows, we'll eventually split Python and Rust discussions into dedicated spaces.
104
+
105
+ - Channel (releases & announcements): [@Ferogram](https://t.me/Ferogram)
106
+
107
+ - (questions & discussion): [@FerogramChat](https://t.me/FerogramChat)
@@ -0,0 +1,130 @@
1
+ <svg width="100%" viewBox="0 0 680 560" role="img" xmlns="http://www.w3.org/2000/svg">
2
+ <title>ferogram-py architecture</title>
3
+ <desc>Flow from user code through the Python layer, FFI boundary, and five Rust crates to Telegram MTProto</desc>
4
+ <defs>
5
+ <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
6
+ <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
7
+ </marker>
8
+ <style>
9
+ text { font-family: ui-monospace, "Cascadia Code", "Fira Mono", monospace; }
10
+ .th { font-size: 14px; font-weight: 600; fill: #2C2C2A; }
11
+ .ts { font-size: 12px; font-weight: 400; fill: #444441; }
12
+ .arr { stroke: #888780; stroke-width: 1.5; fill: none; }
13
+
14
+ /* gray */
15
+ .c-gray rect { fill: #F1EFE8; stroke: #5F5E5A; }
16
+ .c-gray .th { fill: #2C2C2A; }
17
+
18
+ /* purple */
19
+ .c-purple rect { fill: #EEEDFE; stroke: #534AB7; }
20
+ .c-purple .th { fill: #26215C; }
21
+ .c-purple .ts { fill: #3C3489; }
22
+
23
+ /* teal */
24
+ .c-teal rect { fill: #E1F5EE; stroke: #0F6E56; }
25
+ .c-teal .th { fill: #04342C; }
26
+ .c-teal .ts { fill: #085041; }
27
+
28
+ /* blue */
29
+ .c-blue rect { fill: #E6F1FB; stroke: #185FA5; }
30
+ .c-blue .th { fill: #042C53; }
31
+
32
+ @media (prefers-color-scheme: dark) {
33
+ .th { fill: #D3D1C7; }
34
+ .ts { fill: #B4B2A9; }
35
+ .arr { stroke: #5F5E5A; }
36
+
37
+ .c-gray rect { fill: #444441; stroke: #B4B2A9; }
38
+ .c-gray .th { fill: #F1EFE8; }
39
+
40
+ .c-purple rect { fill: #3C3489; stroke: #AFA9EC; }
41
+ .c-purple .th { fill: #EEEDFE; }
42
+ .c-purple .ts { fill: #CECBF6; }
43
+
44
+ .c-teal rect { fill: #085041; stroke: #5DCAA5; }
45
+ .c-teal .th { fill: #E1F5EE; }
46
+ .c-teal .ts { fill: #9FE1CB; }
47
+
48
+ .c-blue rect { fill: #0C447C; stroke: #85B7EB; }
49
+ .c-blue .th { fill: #E6F1FB; }
50
+ }
51
+ </style>
52
+ </defs>
53
+
54
+ <!-- your code -->
55
+ <g class="c-gray">
56
+ <rect x="230" y="24" width="220" height="44" rx="8" stroke-width="0.5"/>
57
+ <text class="th" x="340" y="46" text-anchor="middle" dominant-baseline="central">your code</text>
58
+ </g>
59
+
60
+ <line x1="340" y1="68" x2="340" y2="92" class="arr" marker-end="url(#arrow)"/>
61
+
62
+ <!-- Python layer -->
63
+ <g class="c-purple">
64
+ <rect x="50" y="92" width="580" height="172" rx="12" stroke-width="0.5"/>
65
+ <text class="th" x="340" y="116" text-anchor="middle" dominant-baseline="central">ferogram-py (Python)</text>
66
+ </g>
67
+ <g class="c-purple">
68
+ <rect x="70" y="134" width="118" height="48" rx="6" stroke-width="0.5"/>
69
+ <text class="ts" x="129" y="152" text-anchor="middle" dominant-baseline="central">client</text>
70
+ <text class="ts" x="129" y="168" text-anchor="middle" dominant-baseline="central">filters</text>
71
+ </g>
72
+ <g class="c-purple">
73
+ <rect x="204" y="134" width="118" height="48" rx="6" stroke-width="0.5"/>
74
+ <text class="ts" x="263" y="152" text-anchor="middle" dominant-baseline="central">types</text>
75
+ <text class="ts" x="263" y="168" text-anchor="middle" dominant-baseline="central">updates</text>
76
+ </g>
77
+ <g class="c-purple">
78
+ <rect x="338" y="134" width="118" height="48" rx="6" stroke-width="0.5"/>
79
+ <text class="ts" x="397" y="152" text-anchor="middle" dominant-baseline="central">keyboards</text>
80
+ <text class="ts" x="397" y="168" text-anchor="middle" dominant-baseline="central">rich</text>
81
+ </g>
82
+ <g class="c-purple">
83
+ <rect x="472" y="134" width="138" height="48" rx="6" stroke-width="0.5"/>
84
+ <text class="ts" x="541" y="152" text-anchor="middle" dominant-baseline="central">raw/</text>
85
+ <text class="ts" x="541" y="168" text-anchor="middle" dominant-baseline="central">TL codegen</text>
86
+ </g>
87
+
88
+ <!-- FFI arrow -->
89
+ <line x1="340" y1="264" x2="340" y2="296" class="arr" marker-end="url(#arrow)"/>
90
+ <text class="ts" x="356" y="280" dominant-baseline="central">FFI (PyO3)</text>
91
+
92
+ <!-- Rust extension box -->
93
+ <g class="c-teal">
94
+ <rect x="50" y="296" width="580" height="188" rx="12" stroke-width="0.5"/>
95
+ <text class="th" x="340" y="320" text-anchor="middle" dominant-baseline="central">_ferogram.so (Rust)</text>
96
+ </g>
97
+ <g class="c-teal">
98
+ <rect x="70" y="338" width="148" height="40" rx="6" stroke-width="0.5"/>
99
+ <text class="ts" x="144" y="358" text-anchor="middle" dominant-baseline="central">DcConnection</text>
100
+ </g>
101
+ <line x1="218" y1="358" x2="256" y2="358" class="arr" marker-end="url(#arrow)" stroke="#0F6E56"/>
102
+ <g class="c-teal">
103
+ <rect x="256" y="330" width="174" height="56" rx="6" stroke-width="0.5"/>
104
+ <text class="ts" x="343" y="348" text-anchor="middle" dominant-baseline="central">ferogram_mtsender</text>
105
+ <text class="ts" x="343" y="364" text-anchor="middle" dominant-baseline="central">ferogram_connect</text>
106
+ <text class="ts" x="343" y="380" text-anchor="middle" dominant-baseline="central">ferogram_crypto</text>
107
+ </g>
108
+ <g class="c-teal">
109
+ <rect x="70" y="396" width="148" height="52" rx="6" stroke-width="0.5"/>
110
+ <text class="ts" x="144" y="416" text-anchor="middle" dominant-baseline="central">*Session</text>
111
+ <text class="ts" x="144" y="432" text-anchor="middle" dominant-baseline="central">srp_calculate</text>
112
+ </g>
113
+ <line x1="218" y1="422" x2="448" y2="390" class="arr" marker-end="url(#arrow)" stroke="#0F6E56"/>
114
+ <g class="c-teal">
115
+ <rect x="448" y="338" width="162" height="72" rx="6" stroke-width="0.5"/>
116
+ <text class="ts" x="529" y="358" text-anchor="middle" dominant-baseline="central">ferogram_session</text>
117
+ <text class="ts" x="529" y="376" text-anchor="middle" dominant-baseline="central">ferogram_tl_types</text>
118
+ <text class="ts" x="529" y="394" text-anchor="middle" dominant-baseline="central">ferogram_crypto</text>
119
+ </g>
120
+
121
+ <!-- TCP arrow -->
122
+ <line x1="340" y1="484" x2="340" y2="512" class="arr" marker-end="url(#arrow)"/>
123
+ <text class="ts" x="356" y="498" dominant-baseline="central">TCP / TLS</text>
124
+
125
+ <!-- Telegram -->
126
+ <g class="c-blue">
127
+ <rect x="230" y="512" width="220" height="44" rx="8" stroke-width="0.5"/>
128
+ <text class="th" x="340" y="534" text-anchor="middle" dominant-baseline="central">Telegram MTProto</text>
129
+ </g>
130
+ </svg>
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.
@@ -18,7 +19,7 @@
18
19
  import asyncio
19
20
  from ferogram import Client
20
21
 
21
- app = Client("ferogram")
22
+ app = Client("ferogram") # set API_ID / API_HASH env vars (this is a user session, no bot_token)
22
23
 
23
24
 
24
25
  async def main():
@@ -2,11 +2,12 @@
2
2
  # SPDX-License-Identifier: MIT OR Apache-2.0
3
3
  #
4
4
  # ferogram is a high-performance Telegram MTProto framework written in Rust.
5
- # ferogram-py provides Python bindings built on top of the Rust core for
6
- # building Telegram clients, bots, and applications with a simple API.
5
+ # ferogram-py is a Python MTProto library powered by ferogram, delivering
6
+ # native Rust performance through a clean and Pythonic API for building
7
+ # Telegram clients, bots, and applications.
7
8
  #
8
- # Rust core: https://github.com/ankit-chaubey/ferogram
9
- # Python bindings: https://github.com/ankit-chaubey/ferogram-py
9
+ # Rust: https://github.com/ankit-chaubey/ferogram
10
+ # Python: https://github.com/ankit-chaubey/ferogram-py
10
11
  #
11
12
  # If you use or modify this code, keep this notice at the top of the file
12
13
  # and include the LICENSE-MIT or LICENSE-APACHE file from this repository.