django-tgcms 0.1.0__tar.gz

django_tgcms-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv
+.venv/
+
+# Django
+*.sqlite3
+local_settings.py
+
+# Tooling
+.idea/
+.vscode/
+.DS_Store

django_tgcms-0.1.0/LICENSE

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

django_tgcms-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: django-tgcms
+Version: 0.1.0
+Summary: Django reusable app: a Telegram post constructor that outputs Bot API-ready {text, entities} payloads.
+Project-URL: Homepage, https://gitlab.com/ddnsupp/django-tgcms
+Author: ddnsupp
+License: MIT
+License-File: LICENSE
+Keywords: bot-api,cms,django,entities,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# django-tgcms
+
+A reusable Django app for building Telegram posts. Compose posts from blocks
+(heading, formatted text, photo, video) using a WYSIWYG editor embedded in
+Django admin. `Post.render()` returns a Bot API-ready payload — sending is
+entirely up to you.
+
+**No dependencies beyond Django. No bot logic, no HTTP calls.**
+
+---
+
+## Installation
+
+```bash
+pip install django-tgcms
+# or
+uv add django-tgcms
+```
+
+`settings.py`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "tgcms",
+]
+
+# Optional — only needed for the send_post test command
+TGCMS = {
+    "BOT_TOKEN": env("YOUR_BOT_TOKEN"),  # map whatever name your project uses
+}
+```
+
+`urls.py` (only if you need the built-in views):
+
+```python
+urlpatterns += [
+    path("tg/", include("tgcms.urls")),
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+---
+
+## Content — Django admin
+
+Posts are edited in the standard Django admin at `/admin/tgcms/post/`.
+
+**Block types** (drag-and-drop reordering inside each post):
+
+| Type | Stores |
+|---|---|
+| `heading` | Plain text title |
+| `text` | Formatted text — bold, italic, underline, strikethrough, spoiler, code, pre, blockquote, links |
+| `photo` | Media asset + caption |
+| `video` | Media asset + caption |
+
+**MediaAsset** (`/admin/tgcms/mediaasset/`) is a shared media registry. One
+asset can be referenced by any number of blocks across any number of posts.
+After the first Telegram send the `telegram_file_id` is cached on the asset —
+subsequent sends reuse it without re-uploading.
+
+---
+
+## Bot integration
+
+```python
+from tgcms.models import Post
+
+post = Post.objects.prefetch_related("blocks__media").get(pk=post_id)
+payload = post.render()
+# {
+#   "blocks": [
+#     {"type": "heading", "text": "Title"},
+#     {"type": "text", "text": "Hello!", "entities": [{"type": "bold", "offset": 0, "length": 5}]},
+#     {"type": "photo", "media_asset_id": 3, "file": "AgACAgI...", "caption": "..."},
+#   ]
+# }
+```
+
+**aiogram broadcast pattern:**
+
+```python
+from asgiref.sync import sync_to_async
+
+async def send_post(bot, chat_id: int, post_id: int):
+    post = await sync_to_async(
+        Post.objects.prefetch_related("blocks__media").get
+    )(pk=post_id)
+
+    for block in post.blocks.all():
+        data = block.render()
+
+        if data["type"] == "heading":
+            await bot.send_message(chat_id, f"<b>{data['text']}</b>", parse_mode="HTML")
+
+        elif data["type"] == "text":
+            await bot.send_message(chat_id, data["text"])
+
+        elif data["type"] == "photo":
+            msg = await bot.send_photo(
+                chat_id,
+                photo=data["file"],        # telegram_file_id, S3 URL, or local path
+                caption=data.get("caption"),
+            )
+            # Cache file_id after first upload — all future renders return it
+            if block.media and not block.media.telegram_file_id:
+                await sync_to_async(block.media.cache_file_id)(msg.photo[-1].file_id)
+
+        elif data["type"] == "video":
+            msg = await bot.send_video(chat_id, video=data["file"], caption=data.get("caption"))
+            if block.media and not block.media.telegram_file_id:
+                await sync_to_async(block.media.cache_file_id)(msg.video.file_id)
+```
+
+Once `cache_file_id()` is called, `block.media.source` returns the cached
+`telegram_file_id` for every subsequent post that references the same asset.
+
+---
+
+## Testing — management command
+
+```bash
+# Token is read from settings.TGCMS["BOT_TOKEN"] automatically
+python manage.py send_post <post_id> <chat_id>
+
+# Or pass it explicitly
+python manage.py send_post 1 @mychannel --token 123456:ABC...
+
+# Or via env var
+TELEGRAM_BOT_TOKEN=123456:ABC... python manage.py send_post 1 123456789
+```
+
+Token lookup order: `--token` → `settings.TGCMS["BOT_TOKEN"]` → `TELEGRAM_BOT_TOKEN` env var.
+
+---
+
+## Models
+
+```
+MediaAsset
+  file              FileField — upload from disk
+  file_url          URLField  — S3 / CDN link
+  telegram_file_id  Cached after first send (read-only in admin)
+  .source           Property: returns the best available file reference
+  .cache_file_id()  Persists telegram_file_id; call once after the first send
+
+Post
+  title, status     draft / published
+  .render()         Returns {"blocks": [...]}
+  .mark_published() Sets status and published_at
+
+Block               FK → Post, FK → MediaAsset (nullable)
+  type              heading / text / photo / video
+  order             Managed by drag-and-drop in admin
+  text, entities    heading and text blocks
+  media             FK → MediaAsset, photo and video blocks
+  caption, caption_entities
+  .render()         Returns one block in Bot API format
+```
+
+---
+
+## UTF-16 offsets
+
+`MessageEntity.offset` and `length` are counted in UTF-16 code units, not
+Python characters. Non-BMP characters (e.g. 😀 U+1F600) occupy 2 units, not 1.
+All offset arithmetic in `tgcms.formatting` goes through `utf16_len()`.
+
+---
+
+## License
+
+MIT

django_tgcms-0.1.0/README.md

@@ -0,0 +1,179 @@
+# django-tgcms
+
+A reusable Django app for building Telegram posts. Compose posts from blocks
+(heading, formatted text, photo, video) using a WYSIWYG editor embedded in
+Django admin. `Post.render()` returns a Bot API-ready payload — sending is
+entirely up to you.
+
+**No dependencies beyond Django. No bot logic, no HTTP calls.**
+
+---
+
+## Installation
+
+```bash
+pip install django-tgcms
+# or
+uv add django-tgcms
+```
+
+`settings.py`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "tgcms",
+]
+
+# Optional — only needed for the send_post test command
+TGCMS = {
+    "BOT_TOKEN": env("YOUR_BOT_TOKEN"),  # map whatever name your project uses
+}
+```
+
+`urls.py` (only if you need the built-in views):
+
+```python
+urlpatterns += [
+    path("tg/", include("tgcms.urls")),
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+---
+
+## Content — Django admin
+
+Posts are edited in the standard Django admin at `/admin/tgcms/post/`.
+
+**Block types** (drag-and-drop reordering inside each post):
+
+| Type | Stores |
+|---|---|
+| `heading` | Plain text title |
+| `text` | Formatted text — bold, italic, underline, strikethrough, spoiler, code, pre, blockquote, links |
+| `photo` | Media asset + caption |
+| `video` | Media asset + caption |
+
+**MediaAsset** (`/admin/tgcms/mediaasset/`) is a shared media registry. One
+asset can be referenced by any number of blocks across any number of posts.
+After the first Telegram send the `telegram_file_id` is cached on the asset —
+subsequent sends reuse it without re-uploading.
+
+---
+
+## Bot integration
+
+```python
+from tgcms.models import Post
+
+post = Post.objects.prefetch_related("blocks__media").get(pk=post_id)
+payload = post.render()
+# {
+#   "blocks": [
+#     {"type": "heading", "text": "Title"},
+#     {"type": "text", "text": "Hello!", "entities": [{"type": "bold", "offset": 0, "length": 5}]},
+#     {"type": "photo", "media_asset_id": 3, "file": "AgACAgI...", "caption": "..."},
+#   ]
+# }
+```
+
+**aiogram broadcast pattern:**
+
+```python
+from asgiref.sync import sync_to_async
+
+async def send_post(bot, chat_id: int, post_id: int):
+    post = await sync_to_async(
+        Post.objects.prefetch_related("blocks__media").get
+    )(pk=post_id)
+
+    for block in post.blocks.all():
+        data = block.render()
+
+        if data["type"] == "heading":
+            await bot.send_message(chat_id, f"<b>{data['text']}</b>", parse_mode="HTML")
+
+        elif data["type"] == "text":
+            await bot.send_message(chat_id, data["text"])
+
+        elif data["type"] == "photo":
+            msg = await bot.send_photo(
+                chat_id,
+                photo=data["file"],        # telegram_file_id, S3 URL, or local path
+                caption=data.get("caption"),
+            )
+            # Cache file_id after first upload — all future renders return it
+            if block.media and not block.media.telegram_file_id:
+                await sync_to_async(block.media.cache_file_id)(msg.photo[-1].file_id)
+
+        elif data["type"] == "video":
+            msg = await bot.send_video(chat_id, video=data["file"], caption=data.get("caption"))
+            if block.media and not block.media.telegram_file_id:
+                await sync_to_async(block.media.cache_file_id)(msg.video.file_id)
+```
+
+Once `cache_file_id()` is called, `block.media.source` returns the cached
+`telegram_file_id` for every subsequent post that references the same asset.
+
+---
+
+## Testing — management command
+
+```bash
+# Token is read from settings.TGCMS["BOT_TOKEN"] automatically
+python manage.py send_post <post_id> <chat_id>
+
+# Or pass it explicitly
+python manage.py send_post 1 @mychannel --token 123456:ABC...
+
+# Or via env var
+TELEGRAM_BOT_TOKEN=123456:ABC... python manage.py send_post 1 123456789
+```
+
+Token lookup order: `--token` → `settings.TGCMS["BOT_TOKEN"]` → `TELEGRAM_BOT_TOKEN` env var.
+
+---
+
+## Models
+
+```
+MediaAsset
+  file              FileField — upload from disk
+  file_url          URLField  — S3 / CDN link
+  telegram_file_id  Cached after first send (read-only in admin)
+  .source           Property: returns the best available file reference
+  .cache_file_id()  Persists telegram_file_id; call once after the first send
+
+Post
+  title, status     draft / published
+  .render()         Returns {"blocks": [...]}
+  .mark_published() Sets status and published_at
+
+Block               FK → Post, FK → MediaAsset (nullable)
+  type              heading / text / photo / video
+  order             Managed by drag-and-drop in admin
+  text, entities    heading and text blocks
+  media             FK → MediaAsset, photo and video blocks
+  caption, caption_entities
+  .render()         Returns one block in Bot API format
+```
+
+---
+
+## UTF-16 offsets
+
+`MessageEntity.offset` and `length` are counted in UTF-16 code units, not
+Python characters. Non-BMP characters (e.g. 😀 U+1F600) occupy 2 units, not 1.
+All offset arithmetic in `tgcms.formatting` goes through `utf16_len()`.
+
+---
+
+## License
+
+MIT

django_tgcms-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "django-tgcms"
+version = "0.1.0"
+description = "Django reusable app: a Telegram post constructor that outputs Bot API-ready {text, entities} payloads."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "ddnsupp" }]
+keywords = ["django", "telegram", "bot-api", "cms", "entities"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "Django>=4.2",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/ddnsupp/django-tgcms"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tgcms"]
+
+[tool.hatch.build.targets.sdist]
+include = ["tgcms", "tests", "README.md", "LICENSE"]
+

django_tgcms-0.1.0/tests/settings.py

@@ -0,0 +1,9 @@
+SECRET_KEY = "test-secret-key"
+DATABASES = {"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}}
+INSTALLED_APPS = [
+    "django.contrib.contenttypes",
+    "django.contrib.auth",
+    "tgcms",
+]
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+USE_TZ = True

django_tgcms-0.1.0/tests/test_formatting.py

@@ -0,0 +1,101 @@
+import unittest
+
+from tgcms.formatting import html_to_text_entities, text_entities_to_html, utf16_len
+
+
+class UTF16LenTests(unittest.TestCase):
+    def test_ascii(self):
+        self.assertEqual(utf16_len("hello"), 5)
+
+    def test_bmp_non_ascii(self):
+        # Cyrillic chars are BMP -> 1 code unit each.
+        self.assertEqual(utf16_len("привет"), 6)
+
+    def test_non_bmp_emoji_is_two_units(self):
+        # U+1F600 is a surrogate pair -> 2 UTF-16 code units.
+        self.assertEqual(utf16_len("\U0001f600"), 2)
+        self.assertEqual(utf16_len("a\U0001f600b"), 4)
+
+
+class HtmlToEntitiesTests(unittest.TestCase):
+    def test_basic_bold(self):
+        text, entities = html_to_text_entities("<b>hi</b> there")
+        self.assertEqual(text, "hi there")
+        self.assertEqual(entities, [{"type": "bold", "offset": 0, "length": 2}])
+
+    def test_offsets_after_emoji_are_utf16(self):
+        # The emoji occupies 2 UTF-16 units, so "bold" must start at offset 3.
+        text, entities = html_to_text_entities("a\U0001f600<b>bold</b>")
+        self.assertEqual(text, "a\U0001f600bold")
+        self.assertEqual(entities, [{"type": "bold", "offset": 3, "length": 4}])
+
+    def test_emoji_inside_entity_length_is_utf16(self):
+        text, entities = html_to_text_entities("<b>x\U0001f600y</b>")
+        self.assertEqual(entities, [{"type": "bold", "offset": 0, "length": 4}])
+
+    def test_text_link(self):
+        text, entities = html_to_text_entities('<a href="https://t.me">t.me</a>')
+        self.assertEqual(text, "t.me")
+        self.assertEqual(
+            entities,
+            [{"type": "text_link", "offset": 0, "length": 4, "url": "https://t.me"}],
+        )
+
+    def test_nested_entities(self):
+        text, entities = html_to_text_entities("<b><i>x</i></b>")
+        self.assertEqual(text, "x")
+        types = sorted(e["type"] for e in entities)
+        self.assertEqual(types, ["bold", "italic"])
+        self.assertTrue(all(e["offset"] == 0 and e["length"] == 1 for e in entities))
+
+    def test_spoiler_span(self):
+        text, entities = html_to_text_entities('<span class="tg-spoiler">s</span>')
+        self.assertEqual(entities, [{"type": "spoiler", "offset": 0, "length": 1}])
+
+    def test_pre_with_language(self):
+        text, entities = html_to_text_entities(
+            '<pre><code class="language-python">x=1</code></pre>'
+        )
+        self.assertEqual(text, "x=1")
+        self.assertEqual(
+            entities,
+            [{"type": "pre", "offset": 0, "length": 3, "language": "python"}],
+        )
+
+    def test_entities_are_sorted(self):
+        _, entities = html_to_text_entities("<b>a</b>b<i>c</i>")
+        offsets = [e["offset"] for e in entities]
+        self.assertEqual(offsets, sorted(offsets))
+
+
+class RoundTripTests(unittest.TestCase):
+    def assert_roundtrip(self, html):
+        text, entities = html_to_text_entities(html)
+        rebuilt = text_entities_to_html(text, entities)
+        # A second parse must yield the same canonical (text, entities).
+        text2, entities2 = html_to_text_entities(rebuilt)
+        self.assertEqual(text, text2)
+        self.assertEqual(entities, entities2)
+
+    def test_roundtrip_plain(self):
+        self.assert_roundtrip("hello world")
+
+    def test_roundtrip_bold_with_emoji(self):
+        self.assert_roundtrip("a\U0001f600<b>bold \U0001f4a1 end</b>")
+
+    def test_roundtrip_link_and_code(self):
+        self.assert_roundtrip('see <a href="https://t.me">t.me</a> and <code>x</code>')
+
+    def test_roundtrip_nested(self):
+        self.assert_roundtrip("<b>bold <i>both</i></b> plain")
+
+    def test_html_special_chars_escaped(self):
+        text, entities = html_to_text_entities("a &lt; b &amp; c")
+        self.assertEqual(text, "a < b & c")
+        rebuilt = text_entities_to_html(text, entities)
+        self.assertIn("&lt;", rebuilt)
+        self.assertIn("&amp;", rebuilt)
+
+
+if __name__ == "__main__":
+    unittest.main()