chkit-py 0.1.0__tar.gz

chkit_py-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+dist/
+build/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/

chkit_py-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: chkit-py
+Version: 0.1.0
+Summary: ClickHouse schema and migration toolkit for Python (port of chkit TS)
+Project-URL: Homepage, https://chkit.obsessiondb.com
+Project-URL: Repository, https://github.com/obsessiondb/chkit
+Project-URL: Issues, https://github.com/obsessiondb/chkit/issues
+Author: ObsessionDB
+License: MIT
+Keywords: cli,clickhouse,database,migrations,schema
+Requires-Python: >=3.11
+Requires-Dist: clickhouse-connect<1,>=0.8
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: rich<14,>=13.9
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pyright>=1.1.390; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: build>=1.2; extra == 'publish'
+Requires-Dist: twine>=5.1; extra == 'publish'
+Description-Content-Type: text/markdown
+
+# chkit (Python)
+
+A Python port of [chkit](https://chkit.obsessiondb.com) — ClickHouse schema
+management and migration toolkit, written in strict, imperative Python.
+
+## Design
+
+- **Type safety first.** Every public surface is annotated. The project is
+  configured for `mypy --strict` and Pyright `strict` mode out of the box.
+- **Pydantic v2 models.** Runtime validation, frozen, `extra="forbid"`.
+- **Imperative core.** Pure functions over data; minimal classes outside of
+  Pydantic models and the CLI shell.
+- **No magic.** No dynamic imports, no runtime introspection of user code
+  beyond what Pydantic provides.
+
+## Layout
+
+```
+src/chkit/
+  core/          Schema DSL, diff engine, planner, SQL rendering, validation
+  clickhouse/    ClickHouse client wrapper
+  cli/           Typer-based CLI (init, generate, migrate, status, check, drift)
+```
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+chkit --help
+mypy
+pytest
+```
+
+## Status
+
+Port-in-progress. Implements the core schema model, canonicalization, the
+diff/migration planner, validation, and a basic CLI. Parity tracker in the
+`tests/` directory mirrors the TS test suite.

chkit_py-0.1.0/README.md

@@ -0,0 +1,38 @@
+# chkit (Python)
+
+A Python port of [chkit](https://chkit.obsessiondb.com) — ClickHouse schema
+management and migration toolkit, written in strict, imperative Python.
+
+## Design
+
+- **Type safety first.** Every public surface is annotated. The project is
+  configured for `mypy --strict` and Pyright `strict` mode out of the box.
+- **Pydantic v2 models.** Runtime validation, frozen, `extra="forbid"`.
+- **Imperative core.** Pure functions over data; minimal classes outside of
+  Pydantic models and the CLI shell.
+- **No magic.** No dynamic imports, no runtime introspection of user code
+  beyond what Pydantic provides.
+
+## Layout
+
+```
+src/chkit/
+  core/          Schema DSL, diff engine, planner, SQL rendering, validation
+  clickhouse/    ClickHouse client wrapper
+  cli/           Typer-based CLI (init, generate, migrate, status, check, drift)
+```
+
+## Quickstart
+
+```bash
+pip install -e ".[dev]"
+chkit --help
+mypy
+pytest
+```
+
+## Status
+
+Port-in-progress. Implements the core schema model, canonicalization, the
+diff/migration planner, validation, and a basic CLI. Parity tracker in the
+`tests/` directory mirrors the TS test suite.

chkit_py-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chkit-py"
+version = "0.1.0"
+description = "ClickHouse schema and migration toolkit for Python (port of chkit TS)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "ObsessionDB" }]
+keywords = ["clickhouse", "schema", "migrations", "database", "cli"]
+dependencies = [
+    "pydantic>=2.9,<3",
+    "typer>=0.15,<1",
+    "clickhouse-connect>=0.8,<1",
+    "rich>=13.9,<14",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.13",
+    "pyright>=1.1.390",
+    "ruff>=0.8",
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+]
+publish = [
+    "build>=1.2",
+    "twine>=5.1",
+]
+
+[project.scripts]
+chkit = "chkit.cli.main:app"
+
+[project.urls]
+Homepage = "https://chkit.obsessiondb.com"
+Repository = "https://github.com/obsessiondb/chkit"
+Issues = "https://github.com/obsessiondb/chkit/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chkit"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_any_unimported = true
+disallow_any_explicit = false
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+strict_optional = true
+strict_equality = true
+extra_checks = true
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = "error"
+reportImplicitStringConcatenation = "warning"
+reportImportCycles = "error"
+reportShadowedImports = "error"
+reportUnnecessaryTypeIgnoreComment = "warning"
+include = ["src", "tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W", "I", "N", "UP", "B", "C4", "SIM", "ANN", "TID",
+    "RET", "ARG", "PL", "PERF", "RUF", "PT", "PIE", "ERA", "FBT",
+]
+ignore = [
+    "ANN401",   # Allow Any in narrow internal cases
+    "PLR0913",  # Too many arguments - common for data models
+    "FBT001",   # Boolean positional arg (CLI flags etc)
+    "FBT002",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests are exempt from arg-count/magic-value/annotation noise, and from
+# UPPERCASE acronyms in function names (we mirror TS describe-block names).
+"tests/**" = ["PLR2004", "ANN", "ARG", "B009", "N802", "E501", "PERF401"]
+# Parser/planner code is necessarily branchy: exhaustive discriminated-union
+# dispatch and per-operation-type branches are clearer as flat code than as
+# data-driven dispatch tables. PERF401 prefers comprehensions over append loops
+# but the imperative style is explicit and intentional here.
+"src/chkit/core/codec.py" = ["PLR0911", "PLR0912", "PLR2004", "E501"]
+"src/chkit/core/planner.py" = ["PLR0911", "PLR0912", "PERF401"]
+"src/chkit/core/model.py" = ["E501", "PLC0415"]
+"src/chkit/core/flags.py" = ["PLR0912"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra --strict-markers --strict-config"
+testpaths = ["tests"]

chkit_py-0.1.0/src/chkit/__init__.py

@@ -0,0 +1,62 @@
+"""chkit — ClickHouse schema and migration toolkit."""
+
+from chkit.core import (
+    ChxResolvedClickHouseConfig,
+    ChxResolvedConfig,
+    ChxUserClickHouseConfig,
+    ChxUserConfig,
+    ChxValidationError,
+    ColumnDefinition,
+    MaterializedViewDefinition,
+    MaterializedViewRefresh,
+    MigrationOperation,
+    MigrationPlan,
+    ProjectionDefinition,
+    SchemaDefinition,
+    TableDefinition,
+    TableRef,
+    ValidationIssue,
+    ViewDefinition,
+    canonicalize_definitions,
+    define_config,
+    materialized_view,
+    plan_diff,
+    resolve_config,
+    schema,
+    table,
+    to_create_sql,
+    validate_definitions,
+    view,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ChxResolvedClickHouseConfig",
+    "ChxResolvedConfig",
+    "ChxUserClickHouseConfig",
+    "ChxUserConfig",
+    "ChxValidationError",
+    "ColumnDefinition",
+    "MaterializedViewDefinition",
+    "MaterializedViewRefresh",
+    "MigrationOperation",
+    "MigrationPlan",
+    "ProjectionDefinition",
+    "SchemaDefinition",
+    "TableDefinition",
+    "TableRef",
+    "ValidationIssue",
+    "ViewDefinition",
+    "__version__",
+    "canonicalize_definitions",
+    "define_config",
+    "materialized_view",
+    "plan_diff",
+    "resolve_config",
+    "schema",
+    "table",
+    "to_create_sql",
+    "validate_definitions",
+    "view",
+]

chkit_py-0.1.0/src/chkit/cli/__init__.py

@@ -0,0 +1 @@
+"""chkit CLI."""

chkit_py-0.1.0/src/chkit/cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""chkit CLI commands."""
+
+from chkit.cli.commands import check, drift, generate, init, migrate, status
+
+__all__ = ["check", "drift", "generate", "init", "migrate", "status"]

chkit_py-0.1.0/src/chkit/cli/commands/check.py

@@ -0,0 +1,59 @@
+"""`chkit check` — pre-flight gate for CI."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from chkit.cli.config_loader import load_config
+from chkit.cli.migration_store import list_migrations, read_snapshot
+from chkit.cli.schema_loader import load_schema
+from chkit.core.canonical import canonicalize_definitions
+from chkit.core.planner import plan_diff
+from chkit.core.validate import validate_definitions
+
+
+def run(
+    config_path: Annotated[
+        Path | None, typer.Option("--config", "-c", help="Path to chkit.config.py.")
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Emit a JSON-formatted summary.")
+    ] = False,
+) -> None:
+    config = load_config(config_path)
+    schema_defs = canonicalize_definitions(load_schema(config.schema_))
+
+    issues = [issue.model_dump(mode="json") for issue in validate_definitions(schema_defs)]
+    pending = [m.stem for m in list_migrations(Path(config.migrations_dir))]
+    snapshot = read_snapshot(Path(config.meta_dir))
+    drift_ops: list[str] = []
+    if snapshot is not None:
+        plan = plan_diff(list(snapshot.definitions), schema_defs)
+        drift_ops = [op.key for op in plan.operations]
+
+    failed = False
+    if config.check.fail_on_pending and pending:
+        failed = True
+    if config.check.fail_on_drift and drift_ops:
+        failed = True
+    if issues:
+        failed = True
+
+    summary = {
+        "ok": not failed,
+        "issues": issues,
+        "pending_migrations": pending,
+        "drift_operations": drift_ops,
+    }
+    if output_json:
+        typer.echo(json.dumps(summary, indent=2))
+    else:
+        typer.echo(f"Validation issues: {len(issues)}")
+        typer.echo(f"Pending migrations: {len(pending)}")
+        typer.echo(f"Drift operations: {len(drift_ops)}")
+    if failed:
+        raise typer.Exit(code=1)

chkit_py-0.1.0/src/chkit/cli/commands/drift.py

@@ -0,0 +1,63 @@
+"""`chkit drift` — compare last snapshot vs. current schema."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from chkit.cli.config_loader import load_config
+from chkit.cli.migration_store import read_snapshot
+from chkit.cli.schema_loader import load_schema
+from chkit.core.canonical import canonicalize_definitions
+from chkit.core.planner import plan_diff
+
+
+def run(
+    config_path: Annotated[
+        Path | None, typer.Option("--config", "-c", help="Path to chkit.config.py.")
+    ] = None,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Emit a JSON-formatted summary.")
+    ] = False,
+) -> None:
+    config = load_config(config_path)
+    schema_defs = canonicalize_definitions(load_schema(config.schema_))
+    snapshot = read_snapshot(Path(config.meta_dir))
+    if snapshot is None:
+        typer.echo(
+            "No snapshot found — run `chkit generate` first."
+            if not output_json
+            else json.dumps({"status": "no-snapshot"})
+        )
+        return
+
+    plan = plan_diff(list(snapshot.definitions), schema_defs)
+    if not plan.operations:
+        typer.echo(
+            "No drift detected."
+            if not output_json
+            else json.dumps({"status": "no-drift"})
+        )
+        return
+
+    if output_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "status": "drift",
+                    "operations": [op.model_dump(by_alias=True) for op in plan.operations],
+                    "rename_suggestions": [
+                        s.model_dump(by_alias=True) for s in plan.rename_suggestions
+                    ],
+                },
+                indent=2,
+            )
+        )
+        return
+
+    typer.secho(f"Drift detected: {len(plan.operations)} operation(s)", fg=typer.colors.YELLOW)
+    for op in plan.operations:
+        typer.echo(f"  [{op.risk}] {op.type} {op.key}")

chkit_py-0.1.0/src/chkit/cli/commands/generate.py

@@ -0,0 +1,79 @@
+"""`chkit generate` — diff current schema vs. last snapshot and emit a migration."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from chkit.cli.config_loader import load_config
+from chkit.cli.migration_store import read_snapshot, write_migration, write_snapshot
+from chkit.cli.schema_loader import load_schema
+from chkit.core.canonical import canonicalize_definitions
+from chkit.core.model import ChxValidationError
+from chkit.core.planner import plan_diff
+from chkit.core.snapshot import create_snapshot
+from chkit.core.validate import validate_definitions
+
+
+def run(
+    config_path: Annotated[
+        Path | None,
+        typer.Option("--config", "-c", help="Path to chkit.config.py."),
+    ] = None,
+    label: Annotated[
+        str,
+        typer.Option("--label", "-l", help="Label suffix appended to the migration id."),
+    ] = "auto",
+    output_json: Annotated[
+        bool,
+        typer.Option("--json", help="Emit a JSON-formatted summary."),
+    ] = False,
+) -> None:
+    config = load_config(config_path)
+    schema_globs = config.schema_
+    definitions = load_schema(schema_globs)
+    canonical = canonicalize_definitions(definitions)
+
+    issues = validate_definitions(canonical)
+    if issues:
+        raise ChxValidationError(issues)
+
+    meta_dir = Path(config.meta_dir)
+    migrations_dir = Path(config.migrations_dir)
+
+    previous = read_snapshot(meta_dir)
+    old_defs = list(previous.definitions) if previous is not None else []
+
+    plan = plan_diff(old_defs, canonical)
+    if not plan.operations:
+        message = {"status": "no-changes"}
+        typer.echo(json.dumps(message) if output_json else "No schema changes detected.")
+        return
+
+    artifact = write_migration(migrations_dir, plan, label=label)
+    snapshot = create_snapshot(canonical)
+    snapshot_path = write_snapshot(meta_dir, snapshot)
+
+    summary = {
+        "status": "generated",
+        "migration_id": artifact.id,
+        "sql_path": str(artifact.sql_path),
+        "snapshot_path": str(snapshot_path),
+        "operations": len(plan.operations),
+        "risk_summary": plan.risk_summary.model_dump(),
+    }
+    if output_json:
+        typer.echo(json.dumps(summary, indent=2))
+        return
+
+    typer.secho(f"Generated migration {artifact.id}", fg=typer.colors.GREEN)
+    typer.echo(f"  SQL:      {artifact.sql_path}")
+    typer.echo(f"  Snapshot: {snapshot_path}")
+    typer.echo(f"  Operations: {len(plan.operations)}")
+    risks = plan.risk_summary
+    typer.echo(
+        f"  Risk: safe={risks.safe} caution={risks.caution} danger={risks.danger}"
+    )

chkit_py-0.1.0/src/chkit/cli/commands/init.py

@@ -0,0 +1,68 @@
+"""`chkit init` — scaffold a starter project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+_CONFIG_TEMPLATE = '''"""chkit configuration. Edit and re-run `chkit generate`."""
+
+from chkit import ChxUserConfig
+
+config = ChxUserConfig.model_validate(
+    {
+        "schema": ["./schema/**/*.py"],
+        "outDir": "./chkit",
+        "clickhouse": {
+            "url": "http://localhost:8123",
+            "username": "default",
+            "password": "",
+            "database": "default",
+        },
+    }
+)
+'''
+
+_EXAMPLE_TEMPLATE = '''"""Example chkit schema."""
+
+from chkit import ColumnDefinition, table
+
+events = table(
+    database="default",
+    name="events",
+    engine="MergeTree",
+    columns=[
+        ColumnDefinition(name="ts", type="DateTime"),
+        ColumnDefinition(name="user_id", type="UInt64"),
+        ColumnDefinition(name="event", type="String"),
+    ],
+    primary_key=["ts"],
+    order_by=["ts", "user_id"],
+)
+'''
+
+
+def run(
+    out_dir: Annotated[
+        Path,
+        typer.Option("--out", "-o", help="Project root to scaffold into."),
+    ] = Path("."),
+) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    config_path = out_dir / "chkit.config.py"
+    example_path = out_dir / "schema" / "events.py"
+
+    if config_path.exists():
+        typer.secho(f"Skipping: {config_path} already exists", fg=typer.colors.YELLOW)
+    else:
+        config_path.write_text(_CONFIG_TEMPLATE, encoding="utf-8")
+        typer.secho(f"Created {config_path}", fg=typer.colors.GREEN)
+
+    example_path.parent.mkdir(parents=True, exist_ok=True)
+    if example_path.exists():
+        typer.secho(f"Skipping: {example_path} already exists", fg=typer.colors.YELLOW)
+    else:
+        example_path.write_text(_EXAMPLE_TEMPLATE, encoding="utf-8")
+        typer.secho(f"Created {example_path}", fg=typer.colors.GREEN)

chkit_py-0.1.0/src/chkit/cli/commands/migrate.py

@@ -0,0 +1,83 @@
+"""`chkit migrate` — apply pending migrations to the target database."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from chkit.cli.config_loader import load_config
+from chkit.cli.migration_store import list_migrations
+from chkit.clickhouse.client import ClickHouseClient
+from chkit.core.sql_splitter import split_sql_statements
+
+
+def _read_applied(meta_dir: Path) -> set[str]:
+    applied_file = meta_dir / "applied.json"
+    if not applied_file.exists():
+        return set()
+    payload = json.loads(applied_file.read_text(encoding="utf-8"))
+    return {str(item) for item in payload.get("ids", [])}
+
+
+def _write_applied(meta_dir: Path, ids: set[str]) -> None:
+    meta_dir.mkdir(parents=True, exist_ok=True)
+    applied_file = meta_dir / "applied.json"
+    applied_file.write_text(
+        json.dumps({"ids": sorted(ids)}, indent=2), encoding="utf-8"
+    )
+
+
+def run(
+    config_path: Annotated[
+        Path | None, typer.Option("--config", "-c", help="Path to chkit.config.py.")
+    ] = None,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Print statements without executing.")
+    ] = False,
+    output_json: Annotated[
+        bool, typer.Option("--json", help="Emit a JSON-formatted summary.")
+    ] = False,
+) -> None:
+    config = load_config(config_path)
+    if config.clickhouse is None:
+        msg = "chkit.config.py must include a `clickhouse` block to migrate."
+        raise typer.BadParameter(msg)
+
+    migrations_dir = Path(config.migrations_dir)
+    meta_dir = Path(config.meta_dir)
+
+    all_migrations = list_migrations(migrations_dir)
+    applied = _read_applied(meta_dir)
+    pending = [m for m in all_migrations if m.stem not in applied]
+
+    if not pending:
+        result = {"status": "up-to-date", "applied": sorted(applied)}
+        typer.echo(json.dumps(result) if output_json else "No pending migrations.")
+        return
+
+    executed: list[str] = []
+    if dry_run:
+        for migration in pending:
+            typer.echo(f"-- {migration.name}")
+            typer.echo(migration.read_text(encoding="utf-8"))
+        return
+
+    with ClickHouseClient.connect(config.clickhouse) as client:
+        for migration in pending:
+            sql_text = migration.read_text(encoding="utf-8")
+            for statement in split_sql_statements(sql_text):
+                client.execute(statement)
+            executed.append(migration.stem)
+            applied.add(migration.stem)
+            _write_applied(meta_dir, applied)
+
+    summary = {"status": "applied", "executed": executed}
+    if output_json:
+        typer.echo(json.dumps(summary, indent=2))
+        return
+    typer.secho(f"Applied {len(executed)} migration(s).", fg=typer.colors.GREEN)
+    for migration_id in executed:
+        typer.echo(f"  - {migration_id}")