Languages: English · Русский · 简体中文
Когда вы нашли баг, до того, как его исправлять, напишите
воспроизводящий тест — он должен падать на main и проходить
после фикса. И тест, и фикс — в одном PR.
Тесты лежат в tests/:
| Файл | Область |
|---|---|
test_loads.py |
Поведение парсера. |
test_dumps.py |
Поведение сериализатора. |
test_roundtrip.py |
loads(dumps(x)) == x. |
test_errors.py |
Таксономия и распространение исключений. |
test_load_dump.py |
Обёртки под файл-подобные объекты. |
test_module.py |
Экспорты модуля, строки версий. |
test_conformance.py |
Кросс-языковое соответствие спецификации. |
Эти Python-биндинги — намеренно тонкая обёртка. Поведение парсера и
формата принадлежит Rust-крейту
(ktav-lang/rust) — изменение
там сразу обновляет все языковые биндинги. В этом репозитории живёт
только Python-специфичная эргономика (обёртки под файл-подобные
объекты, типы исключений, заглушки типов).
Если ваше изменение требует правки формата, начните с обсуждения в
ktav-lang/spec.
Если вы трогаете что-то экспортируемое из ktav или ktav._core, в
описании PR укажите, является ли это:
- semver-совместимым (добавления, ослабленные типы, правки документации); или
- semver-ломающим (переименование / удаление, изменение сигнатур, ужесточение типов) — в этом случае бамп версии попадёт в следующий MINOR, пока мы до 1.0.
Обновите CHANGELOG-юниты под root-docs/CHANGELOG/ (все три блока
>>>>> lang=) в том же PR и перегенерируйте вывод.
Коммиты атомарны: багфикс и его тест вместе, фича и её тесты вместе,
переименование отдельным коммитом, рефакторинг отдельным.
git log --oneline должен читаться как журнал изменений. Не
префиксуйте сообщения feat: / fix: — никаких conventional commits
здесь.
Нужно:
- Python 3.9+ (любая версия, под которую тестируете).
- Rust-тулчейн через
rustup. MSRV: 1.70. maturinи тестовый инструментарий:
pip install -e ".[dev]"Раскладка во время разработки — эти биндинги разрешают Rust-крейт
ktav через зависимость path = "../rust" в Cargo.toml. Клонируйте
соседний репозиторий рядом с этим:
ktav-lang/
├── python/ ← this repo
├── rust/ ← sibling Rust crate
└── spec/ ← conformance fixtures (optional but recommended)Когда ktav будет опубликован на crates.io, path-зависимость уйдёт, и
останется только требование version = "0.1". См. комментарий на той
строке в Cargo.toml.
make dev # debug build (fast incremental)
make install # release build (realistic perf)Или напрямую:
maturin develop
maturin develop --releasematurin develop компилирует Rust-расширение и устанавливает его в
текущее активное Python-окружение — запускайте тесты из того же
окружения.
make test # full suite
pytest -v -k multiline # filter by name
pytest -v tests/parse/test_loads.py # single fileМодуль test_conformance.py запускает набор кросс-языковых фикстур
из ktav-lang/spec, путь захардкожен как <repo>/spec/versions/0.8/tests
(git submodule spec). Когда submodule не подтянут,
conformance-тесты пропускаются, а не падают.
Conformance-набор параметризован по обоим backend-ам: одни и те же
fixtures прогоняются и через нативное расширение, и через ktav.pure.
CI дополнительно запускает отдельную job pure-mode, которая собирает
pure wheel из packaging/pure и ставит его в свежий venv
(KTAV_REQUIRE_PURE=1;
tests/conftest.py роняет job, если ktav._core импортируется) и
прогоняет установленный пакет через весь корпус скриптом
scripts/check_installed_pure.py.
make lint # ruff check + ruff format --check
make typecheck # mypy --strict
make rust-lint # cargo fmt --check + cargo clippy -D warnings
make all # lint + typecheck + rust-lint + testВ CI выполняются те же команды; прогоните make all локально перед
пушем.
pre-commit install
pre-commit run --all-filesЭто подключает ruff, mypy, rustfmt, clippy и стандартные whitespace /
EOL hooks к git commit.
Девиз Ktav: «будь другом конфига, а не его экзаменатором». Прежде чем предлагать новую Python-специфичную возможность, спросите себя:
- Не добавляет ли это новое правило, которое читатель должен держать в голове?
- Может ли это жить в пользовательском коде вместо библиотеки?
- Не размывает ли это принцип «никакой магии в типах»?
Новые правила стоят дорого. Отклоняйте всё, что явно не на своём месте.
Этот репозиторий участвует в общеорганизационной политике трёх языков
(EN / RU / ZH). Каждый prose-документ живёт в трёх параллельных версиях
— см. ktav-lang/.github/AGENTS.md
для соглашения об именовании и правила «обновлять все три в одном
коммите».
Если вы не владеете одним из языков, всё равно откройте PR на языке,
которым владеете, отметьте нетронутые версии комментарием
<!-- TODO: sync with <name>.md --> в начале — мейнтейнер или
участник сообщества заполнит пробел до слияния.
Если вы явно не заявите иное, любой вклад, намеренно отправленный для включения в этот проект вами, как определено лицензией Apache-2.0, будет лицензирован на условиях MIT OR Apache-2.0 без каких-либо дополнительных условий.