tgblocks 0.2.0__tar.gz

tgblocks-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+# generated bots
+bot.py
+!examples/*.py
+.idea/
+.vscode/
+.DS_Store

tgblocks-0.2.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+## 0.2.0
+
+The release that made the three editors agree with each other.
+
+### Added
+
+- **A single feature catalogue** (`src/tgblocks/model.py`): every action and event is
+  described once, and the DSL parser, the text parser, the converters, the code
+  generator and all three editors read it. `/api/schema` serves it to the pages, so a
+  new block appears in `/nodes`, `/blocks` and `/text` without touching their code.
+- **Media**: `send_document`, `send_video`, `send_animation`, `send_audio`,
+  `send_voice`, `send_sticker`, `send_location`, `send_contact`, `send_poll`,
+  `send_dice`.
+- **Editing and answering**: `edit_text`, `answer_callback [alert]`.
+- **Chat actions**: `pin [silent]`, `unpin`.
+- **Moderation**: `ban_user`, `unban_user`, `mute_user` — without an ID they act on the
+  sender of the message.
+- **Dialogues (FSM)**: `state order`, `set_state`, `clear_state`, `on state order:`.
+  The generated bot gets `StatesGroup` and a `MemoryStorage` dispatcher.
+- **Events**: `on callback:`, `on callback "/data":`, `on inline_query:` with
+  `inline_result`, `on chat_member:`, `on my_chat_member:`, `on poll_answer:`,
+  `on channel_post:`, `on dice:`, `on pinned:`, `on web_app_data:`.
+- **Filters** on any event: `chat=`, `from_user=`, `regex=`.
+- **Webhook mode**: `bot webhook`, `bot webhook_path`, `bot webhook_secret`.
+- **Keyboard buttons**: Web App buttons, and reply buttons that request a contact or a
+  location.
+- `tgblocks check` reports warnings, and the editors show them.
+- `tools/check_javascript.py`, and tests that parse every page.
+
+### Changed
+
+- `tgblocks compile` writes code **without** the token; `--embed-token` restores the old
+  behaviour. `tgblocks run` passes the token through the environment.
+- Generated helpers are emitted only when a bot uses them, so a small bot stays small.
+- The node editor no longer has its own JavaScript DSL writer: the board goes to the
+  server, and one converter produces the shared text and the code.
+- The block editor sends its Blockly workspace as XML; the server converts it back.
+  Blocks are now chained with `<next>`, which fixes only the first handler being shown.
+- `scaffold.py` is generated from the tree by `tools/build_scaffold.py` and checked by
+  `tests/test_scaffold.py`.
+
+### Fixed
+
+- **Security**: the local server refused nothing from other origins. It now checks
+  `Host`, `Origin` and `Sec-Fetch-Site`, requires `application/json` bodies, and needs
+  `--allow-remote` before `--host` exposes it. Requests from a foreign page could start
+  arbitrary code through `/api/run`.
+- Two handlers with the same filters are refused instead of silently leaving the second
+  one dead.
+- A button that calls a command nobody handles produces a warning.
+- `pass` at the top level of the text syntax no longer raises `NameError`.
+- The server no longer reloads the DSL modules on every request (that replaced the
+  exception classes under a running `except`).
+- On Windows, a second `tgblocks visual` can no longer bind the same port and leave the
+  old code answering.
+- `Tuple` is imported where it is annotated; the long-line wrapper, the entity escaping
+  and the `_1`-suffixed handler names are consistent.
+- **Filters and magic filters**: `Command("start") & F.chat.type == "private"` crashed
+  with `TypeError: unsupported operand type(s) for &: 'Command' and 'bool'`. Filters are
+  now separate decorator arguments, and every combination is run against aiogram in
+  `tests/test_filters.py`.
+- **The three views stay in sync when a document is emptied**: clearing a canvas or the
+  text sets a new revision with empty text, instead of leaving the old bot in the other
+  views. A half-built canvas still keeps the last good text.
+- **Editor pages no longer hang**: a missing page-local helper (`L`) threw at boot and
+  left `/blocks` and `/text` on "Loading Blockly…"; `tools/check_javascript.py` now fails
+  on a helper that is called but never defined.
+- **The light theme was broken**: colours were hardcoded per rule, so only `--bg`/`--panel`
+  changed. Every surface is a variable now (`--chip`, `--field`, `--log`, `--tok-*`), and
+  the Blockly canvas follows the theme too.
+- `/blocks?lang=ru` reloaded itself in a loop, because the page compared the language
+  before the preference was read.
+- Stray spaces or tabs around a pasted token, proxy or webhook URL are stripped instead of
+  silently breaking the connection.
+
+### Editor
+
+- **Settings in every view**: ⚙ in the header switches the theme (dark/light) and the
+  interface language (English by default, Russian optional). The choice is remembered and
+  can be shared as `?theme=light&lang=ru`; the whole catalogue — block names, field
+  captions, hints, drop-down values, status lines — is translated.
+- **Typing is one-line everywhere again**, and every field has a caption, so a drop-down
+  says what it is.
+- **Two event filters are hidden** from the panel: "only these texts" and "matches a
+  pattern". A `when` condition does the same job visibly. Values that come from the text
+  view are kept and shown as a removable chip, so nothing is dropped silently.
+- **Blockly ships with the package** (`static/vendor/blockly.js`), so the block editor
+  works without internet; the CDN is only a fallback.
+- The palette scrollbar is thin and vertical; a drag handle sets the panel width.
+- The scrollbar, the fields and the node headers are correct in both themes.
+
+## 0.1.0
+
+First public shape: DSL, one code generator, three editors, no tests worth the name.

tgblocks-0.2.0/GITHUB.md

@@ -0,0 +1,267 @@
+# Публикация tgblocks на GitHub и в PyPI
+
+Полная инструкция с нуля: от пустого аккаунта до `pip install tgblocks` у любого
+человека. Всё, что нужно сделать тебе, — один раз выполнить команды из разделов 1–4,
+а потом (по желанию) разделы 5–6.
+
+---
+
+## 0. Что понадобится
+
+**Аккаунт GitHub** — хранить код: <https://github.com/signup>
+
+**git** — отправлять код: <https://git-scm.com/download/win>
+(при установке оставь галочки по умолчанию)
+
+**Python 3.9 или новее** — собирать пакет: <https://www.python.org/downloads/>
+
+**Аккаунт PyPI** — чтобы работал `pip install`: <https://pypi.org/account/register/>
+
+Проверка, что всё стоит:
+
+```powershell
+git --version
+python --version
+```
+
+---
+
+## 1. Один раз настроить git
+
+```powershell
+git config --global user.name "Твоё Имя"
+git config --global user.email "твоя_почта@example.com"
+```
+
+Почта должна совпадать с той, на которую зарегистрирован GitHub — иначе коммиты не
+будут связаны с профилем.
+
+---
+
+## 2. Создать репозиторий на GitHub
+
+1. Открой <https://github.com/new>.
+2. **Repository name**: `tgblocks`.
+3. **Public** (для приватного всё то же, но `pip install` с GitHub не сработает).
+4. **НЕ** ставь галочки «Add a README», «Add .gitignore», «Choose a license» — они уже
+   есть в проекте, иначе будет конфликт при первом `push`.
+5. **Create repository**.
+
+GitHub покажет адрес вида `https://github.com/Pupka228228/tgblocks.git`.
+
+---
+
+## 3. Отправить код (первый push)
+
+```powershell
+cd C:\TGBots\tgblocks
+git status                      # должно быть "nothing to commit, working tree clean"
+git log --oneline | Select-Object -First 3
+
+git remote add origin https://github.com/Pupka228228/tgblocks.git
+git branch -M main
+git push -u origin main
+```
+
+Если `remote origin already exists`:
+
+```powershell
+git remote set-url origin https://github.com/Pupka228228/tgblocks.git
+```
+
+### Пароль не подойдёт — нужен токен
+
+GitHub больше не принимает пароль аккаунта. Один раз:
+
+1. <https://github.com/settings/tokens> → **Generate new token (classic)**.
+2. Note: `tgblocks push`, Expiration: 90 days, галочка **`repo`**.
+3. **Generate token**, скопируй строку `ghp_...` (она показывается один раз).
+4. В окне `git push` на запрос пароля вставь этот токен, логин — обычный.
+
+Сохранить токен в менеджере Windows, чтобы не вводить каждый раз:
+
+```powershell
+git config --global credential.helper manager
+```
+
+Альтернатива — GitHub CLI:
+
+```powershell
+winget install --id GitHub.cli
+gh auth login        # выбираешь GitHub.com → HTTPS → Login with a web browser
+```
+
+### Каждый следующий раз
+
+```powershell
+git add -A
+git commit -m "что изменилось"
+git push
+```
+
+---
+
+## 4. Проверить, что всё в порядке
+
+1. Открой страницу репозитория — файлы на месте, README и `docs/demo.gif` видны.
+2. Вкладка **Actions**: workflow **CI** должен стать зелёным. Он прогоняет 261 тест на
+   Windows и Linux (Python 3.9, 3.11, 3.13), проверяет JS редакторов, собирает пакет и
+   ставит его в чистое окружение.
+3. Бейдж в README (вставь после заголовка):
+
+```markdown
+[![CI](https://github.com/Pupka228228/tgblocks/actions/workflows/ci.yml/badge.svg)](https://github.com/Pupka228228/tgblocks/actions/workflows/ci.yml)
+```
+
+Если Actions красный — открой лог: чаще всего это не установленные зависимости, а не
+код; локально повтори `python -m pytest -q`.
+
+---
+
+## 5. Установка из GitHub (работает сразу после push)
+
+Ничего дополнительно публиковать не нужно:
+
+```bash
+pip install "tgblocks[runtime] @ git+https://github.com/Pupka228228/tgblocks.git"
+tgblocks
+```
+
+---
+
+## 6. PyPI: чтобы работала одна строка `pip install tgblocks`
+
+### 6.1 Аккаунт и токен
+
+1. Регистрация: <https://pypi.org/account/register/>.
+2. Включи **двухфакторную аутентификацию** (без неё токен не создать):
+   Account settings → Two-factor authentication.
+3. Account settings → **API tokens** → **Add API token** → Name: `tgblocks`,
+   Scope: **Entire account** (для первого раза) → **Add token**.
+4. Скопируй `pypi-AgEIcHlwaS5vcmc...` — это пароль для загрузки.
+
+### 6.2 Собрать и проверить
+
+```powershell
+cd C:\TGBots\tgblocks
+python -m pip install --upgrade build twine
+python -m build                # dist\tgblocks-0.2.0-py3-none-any.whl и .tar.gz
+python -m twine check dist/*   # "PASSED" для обоих файлов
+```
+
+### 6.3 Загрузить
+
+```powershell
+python -m twine upload dist/*
+```
+
+Логин: `__token__`, пароль: сам токен `pypi-...`.
+
+Проверка (подожди полминуты):
+
+```powershell
+pip install --upgrade "tgblocks[runtime]"
+tgblocks --version
+```
+
+### 6.4 Тренировка на тестовом индексе (необязательно)
+
+```powershell
+python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+pip install --index-url https://test.pypi.org/simple tgblocks
+```
+
+Там отдельный аккаунт (<https://test.pypi.org/account/register/>) и отдельный токен.
+
+---
+
+## 7. Как это ставится у любого человека
+
+```bash
+pip install "tgblocks[runtime]"     # пакет + aiogram, чтобы запускать ботов
+tgblocks                            # редактор: http://127.0.0.1:8765/
+tgblocks check mybot.tg
+tgblocks compile mybot.tg -o bot.py
+```
+
+- без `[runtime]` ставится только компилятор и редакторы (генерация кода работает);
+- `tgblocks` появляется в PATH вместе с Python; в виртуальном окружении — после
+  активации. Если команда не находится: `python -m tgblocks` работает всегда.
+
+---
+
+## 8. Выпуск новой версии
+
+1. Подними версию в `pyproject.toml` (`version = "0.2.1"`).
+2. Допиши раздел в `CHANGELOG.md`.
+3. Прогони проверки:
+
+```powershell
+python -m pytest -q
+python tools/build_scaffold.py --check
+python tools/check_javascript.py
+python -m build
+python -m twine check dist/*
+```
+
+4. Отправь код и создай релиз:
+
+```powershell
+git add -A
+git commit -m "release 0.2.1"
+git tag v0.2.1
+git push
+git push --tags
+```
+
+На GitHub: **Releases** → **Draft a new release** → выбери тег `v0.2.1` → опиши
+изменения → прикрепи файлы из `dist/` → **Publish release**.
+
+5. Загрузи в PyPI (`python -m twine upload dist/*`). Одно и то же имя версии дважды
+   загрузить нельзя — всегда поднимай номер.
+
+---
+
+## 9. Частые проблемы
+
+**`Authentication failed` при push** — введён пароль вместо токена.
+Смотри раздел 3, нужен токен с галочкой `repo`.
+
+**`remote origin already exists`** — remote уже привязан.
+Выполни `git remote set-url origin <адрес>`.
+
+**`Updates were rejected`** — на GitHub уже есть коммиты (например, создавал README
+через сайт). Сделай `git pull --rebase origin main`, потом `git push`.
+
+**`403` при `twine upload`** — токен без Scope «Entire account» или не включена 2FA.
+Создай токен заново.
+
+**`File already exists` на PyPI** — эта версия уже загружена.
+Подними `version` в `pyproject.toml`.
+
+**`tgblocks: command not found`** — папка скриптов Python не в PATH.
+Активируй venv или запускай `python -m tgblocks`.
+
+**`ModuleNotFoundError: aiogram`** при запуске бота — пакет поставлен без `[runtime]`.
+Нужен `pip install "tgblocks[runtime]"`.
+
+**README не показывает картинки** — файлы не попали в репозиторий.
+Проверь, что `docs/editor-nodes.png`, `docs/editor-blocks.png`, `docs/editor-text.png`
+и `docs/demo.gif` закоммичены, а ветка в ссылках — `main`.
+
+---
+
+## 10. Чек-лист перед публикацией
+
+```powershell
+python -m pytest -q                     # 261 passed
+python tools/build_scaffold.py --check  # scaffold.py не отстал
+python tools/check_javascript.py        # JS редакторов и его хелперы
+python tools/qa_smoke.py                # эндпоинты + переходы между видами
+python -m build
+python -m twine check dist/*
+```
+
+И глазами: `tgblocks` открывает редактор, `⚙` переключает тему и язык,
+`tgblocks check examples/full.tg` печатает сводку, `tgblocks compile examples/hello.tg
+-o bot.py` даёт файл, который открывается в PyCharm без ошибок.

tgblocks-0.2.0/LICENSE

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