duckdb-kql 0.0.1.dev3__tar.gz → 0.0.1.dev4__tar.gz

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: duckdb-kql
-Version: 0.0.1.dev3
+Version: 0.0.1.dev4
 Summary: Run Kusto KQL queries on DuckDB, from Python
 Project-URL: Homepage, https://github.com/mmaitre314/duckdb-kql
 Project-URL: Documentation, https://github.com/mmaitre314/duckdb-kql/blob/main/docs/getting-started.md
@@ -133,7 +133,7 @@ Translate at build time and the output has no dependency on this package at all
 — not even Python. Only your CI machine installs it.
 
 ```bash
-duckdb-kql queries/ -o build/sql/ --check   # fails the build if a .sql is stale
+duckdb-kql translate queries/ -o build/sql/ --check   # fails the build if a .sql is stale
 ```
 
 See [Build-time translation](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md).

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/README.md

@@ -52,7 +52,7 @@ Translate at build time and the output has no dependency on this package at all
 — not even Python. Only your CI machine installs it.
 
 ```bash
-duckdb-kql queries/ -o build/sql/ --check   # fails the build if a .sql is stale
+duckdb-kql translate queries/ -o build/sql/ --check   # fails the build if a .sql is stale
 ```
 
 See [Build-time translation](https://github.com/mmaitre314/duckdb-kql/blob/main/docs/cli.md).

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/demo/demo.ipynb

@@ -457,7 +457,7 @@
     }
    ],
    "source": [
-    "!duckdb-kql demo.kql"
+    "!duckdb-kql translate demo.kql"
    ]
   },
   {

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/docs/api.md

@@ -277,7 +277,7 @@ translates `.kql` files to `.sql` so the output can be run without this package
 installed at all. `--check` makes a stale generated file fail CI.
 
 ```bash
-duckdb-kql queries/ -o build/sql/ --check
+duckdb-kql translate queries/ -o build/sql/ --check
 ```
 
 Full reference, including the generated header and how to bind the placeholders

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/docs/cli.md

@@ -1,19 +1,18 @@
-# Build-time translation (`duckdb-kql`)
+# Build-time translation (`duckdb-kql translate`)
 
 Translate `.kql` to `.sql` once, in CI. What ships is plain SQL, and **nothing
 that runs it needs this package** — not the transpiler, not Python.
 
-> There is one subcommand, `duckdb-kql serve`, which does something else
-> entirely: it runs a [local Kusto REST endpoint](kusto-server.md) over a DuckDB
-> database. Everything that is not the literal word `serve` is a file to
-> translate, so nothing on this page changes.
-
 ```bash
-pip install duckdb-kql                      # antlr4 only; no database
-duckdb-kql queries/ -o build/sql/           # translate
-duckdb-kql queries/ -o build/sql/ --check   # fail the build if stale
+pip install duckdb-kql                                # antlr4 only; no database
+duckdb-kql translate queries/ -o build/sql/           # translate
+duckdb-kql translate queries/ -o build/sql/ --check   # fail the build if stale
 ```
 
+> `translate` is one of two subcommands. The other,
+> [`duckdb-kql serve`](kusto-server.md), runs a local Kusto REST endpoint over a
+> DuckDB database — a different job with different dependencies.
+
 - [Why](#why)
 - [Usage](#usage)
 - [The generated header](#the-generated-header)
@@ -41,7 +40,7 @@ build time means:
 ## Usage
 
 ```
-duckdb-kql FILE... [-o PATH] [--check] [--schema FILE] [--no-header] [-v]
+duckdb-kql translate FILE... [-o PATH] [--check] [--schema FILE] [--no-header] [-v]
 ```
 
 | | |
@@ -54,14 +53,20 @@ duckdb-kql FILE... [-o PATH] [--check] [--schema FILE] [--no-header] [-v]
 | `-v, --verbose` | Report each file written, on stderr. |
 
 ```bash
-duckdb-kql queries/errors.kql                        # to stdout
-duckdb-kql queries/errors.kql -o build/errors.sql    # to one file
-duckdb-kql queries/ -o build/                        # a directory of each
-echo 'print x = 1' | duckdb-kql -                    # from stdin
+duckdb-kql translate queries/errors.kql                     # to stdout
+duckdb-kql translate queries/errors.kql -o build/errors.sql # to one file
+duckdb-kql translate queries/ -o build/                     # a directory of each
+echo 'print x = 1' | duckdb-kql translate -                 # from stdin
 ```
 
-The command is also `python -m duckdb_kql`, for CI jobs where the console script
-is not on `PATH`.
+The command is also `python -m duckdb_kql translate`, for CI jobs where the
+console script is not on `PATH`.
+
+The verb is required: a bare `duckdb-kql queries/` is a usage error, not a
+translation. It used to be the latter, and reading well was the whole argument
+for it — but a filename in the verb slot is exactly the ambiguity a subcommand
+removes, and the alternative is a second verb that silently collides with a file
+of the same name.
 
 ## The generated header
 
@@ -128,7 +133,7 @@ Commit the `.sql` and let `--check` prove it matches:
 
 ```yaml
 - run: pip install duckdb-kql
-- run: duckdb-kql queries/ -o sql/ --check
+- run: duckdb-kql translate queries/ -o sql/ --check
 ```
 
 An edited `.kql` whose `.sql` was not regenerated fails with exit 3 and a list
@@ -140,7 +145,7 @@ If you would rather not commit the output, translate into the build directory
 and skip `--check`:
 
 ```yaml
-- run: pip install duckdb-kql && duckdb-kql queries/ -o build/sql/
+- run: pip install duckdb-kql && duckdb-kql translate queries/ -o build/sql/
 ```
 
 Errors are reported as `file:line:column: error: …`, which GitHub Actions and
@@ -160,7 +165,7 @@ time there is no connection, so pass a JSON file:
 ```
 
 ```bash
-duckdb-kql queries/ -o build/sql/ --schema schema.json
+duckdb-kql translate queries/ -o build/sql/ --schema schema.json
 ```
 
 Everything else translates schema-free. A `join` without a schema fails with a

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/docs/getting-started.md

@@ -169,7 +169,7 @@ There is a command for exactly this. Translate your `.kql` files to `.sql` in
 CI, ship the SQL, and nothing at runtime needs this package:
 
 ```bash
-duckdb-kql queries/ -o build/sql/ --check
+duckdb-kql translate queries/ -o build/sql/ --check
 ```
 
 See [Build-time translation](cli.md).

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/src/duckdb_kql/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.1.dev3'
-__version_tuple__ = version_tuple = (0, 0, 1, 'dev3')
+__version__ = version = '0.0.1.dev4'
+__version_tuple__ = version_tuple = (0, 0, 1, 'dev4')
 
 __commit_id__ = commit_id = None

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/src/duckdb_kql/cli.py

@@ -1,30 +1,31 @@
-"""``duckdb-kql`` — translate ``.kql`` files to ``.sql`` at build time.
-
-The point of this command is that the *output* has no dependencies. Translate
-your queries in CI, commit or ship the ``.sql``, and the thing that runs them
-needs nothing from this package — not even DuckDB's Python bindings. A Go
-service, a dbt model, a psql script and a notebook can all read the same file.
-
-Translation is Layer 0 only: no database is opened and ``duckdb`` is never
-imported, so ``pip install duckdb-kql`` alone is enough to run it.
+"""``duckdb-kql`` — the command line, one subcommand per job.
 
 ::
 
-    duckdb-kql queries/*.kql -o build/sql/     # translate
-    duckdb-kql queries/*.kql -o build/sql/ --check   # ... and fail if stale
-
-The ``--check`` mode is the one that belongs in CI: it regenerates in memory and
-compares, so a ``.kql`` edited without regenerating its ``.sql`` fails the build
-instead of shipping a stale query.
-
-There is one subcommand, ``serve``, which is a different job entirely — it runs
-a local Kusto-compatible HTTP endpoint over a DuckDB database so that Kusto
-tools, including the Azure Data Explorer web UI, can query it::
-
-    duckdb-kql serve logs.duckdb
-
-It needs the ``duckdb`` extra. Everything that is not the literal word ``serve``
-is a file to translate, so the interface above is unchanged.
+    duckdb-kql translate queries/ -o build/sql/           # KQL files -> SQL files
+    duckdb-kql translate queries/ -o build/sql/ --check   # ... and fail if stale
+    duckdb-kql serve logs.duckdb                          # a local Kusto endpoint
+
+**translate** is the build-time path, and the point of it is that the *output*
+has no dependencies. Translate your queries in CI, commit or ship the ``.sql``,
+and the thing that runs them needs nothing from this package — not even DuckDB's
+Python bindings. A Go service, a dbt model, a psql script and a notebook can all
+read the same file. ``--check`` is the mode that belongs in CI: it regenerates in
+memory and compares, so a ``.kql`` edited without regenerating its ``.sql`` fails
+the build instead of shipping a stale query.
+
+It is Layer 0 only — no database is opened and ``duckdb`` is never imported, so
+``pip install duckdb-kql`` alone is enough to run it.
+
+**serve** is a different job entirely: a local Kusto-compatible HTTP endpoint
+over a DuckDB database, so Kusto tools — including the Azure Data Explorer web
+UI — can query it. It needs the ``duckdb`` extra.
+
+Every subcommand is explicit. An earlier version took a bare list of files
+(``duckdb-kql queries/ -o build/``), which read well while translation was the
+only thing this command did, but leaves no room for a second verb: any new one
+would be ambiguous with a file of the same name, and the ambiguity would be
+silent. Naming the verb costs one word and keeps the space open.
 """
 
 from __future__ import annotations
@@ -33,9 +34,9 @@ import argparse
 import datetime as dt
 import json
 import sys
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from . import __version__, to_sql
 from .errors import KqlError, KqlSyntaxError
@@ -56,15 +57,17 @@ EXIT_STALE = 3
 
 def main(argv: Sequence[str] | None = None) -> int:
     """Entry point. Returns a process exit code rather than raising."""
-    argv = list(sys.argv[1:] if argv is None else argv)
-    # Dispatched by hand rather than with argparse subparsers, because
-    # subparsers would make the existing form — a bare list of files — a
-    # subcommand too, and every documented invocation would have to change.
-    if argv and argv[0] == "serve":
-        return _serve(argv[1:])
-
     args = _parser().parse_args(argv)
+    return cast("Callable[[argparse.Namespace], int]", args.run)(args)
+
+
+# ---------------------------------------------------------------------------
+# translate
+# ---------------------------------------------------------------------------
+
 
+def _translate_command(args: argparse.Namespace) -> int:
+    """``duckdb-kql translate`` — KQL files in, SQL files out."""
     try:
         schema = _load_schema(args.schema)
     except (OSError, ValueError) as exc:
@@ -129,9 +132,10 @@ def main(argv: Sequence[str] | None = None) -> int:
 # ---------------------------------------------------------------------------
 
 
-def _serve(argv: Sequence[str]) -> int:
+def _serve_command(args: argparse.Namespace) -> int:
     """``duckdb-kql serve`` — a local Kusto endpoint over a DuckDB database."""
-    args = _serve_parser().parse_args(argv)
+    # Imported here, not at module scope: this is the only subcommand that needs
+    # a database, and `translate` is documented to run without one installed.
     from .server import serve  # noqa: PLC0415
 
     origins = tuple(args.allow_origin) if args.allow_origin else ADX_ORIGINS
@@ -148,48 +152,6 @@ def _serve(argv: Sequence[str]) -> int:
     return EXIT_OK
 
 
-def _serve_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="duckdb-kql serve",
-        description=(
-            "Serve a DuckDB database over the Kusto REST API, so Kusto tools "
-            "can query it. Open https://dataexplorer.azure.com, choose Add "
-            "connection, and give it the URL this prints."
-        ),
-        epilog=(
-            "Listens on 127.0.0.1 only and cannot be made to listen anywhere "
-            "else: it answers unauthenticated queries, so reaching it has to "
-            "mean already being on this machine."
-        ),
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument(
-        "database",
-        nargs="?",
-        default=":memory:",
-        metavar="DATABASE",
-        help="DuckDB database file to serve. Omit for an empty in-memory one.",
-    )
-    parser.add_argument(
-        "-p",
-        "--port",
-        type=int,
-        default=DEFAULT_PORT,
-        metavar="PORT",
-        help=f"TCP port to listen on (default: {DEFAULT_PORT})",
-    )
-    parser.add_argument(
-        "--allow-origin",
-        action="append",
-        metavar="ORIGIN",
-        help=(
-            "additionally allow a browser origin to make cross-origin requests. "
-            "Repeatable. Replaces the Azure Data Explorer default list, and is a "
-            "decision about who may read this database from another browser tab."
-        ),
-    )
-    parser.add_argument("--version", action="version", version=f"duckdb-kql {__version__}")
-    return parser
 
 
 # ---------------------------------------------------------------------------
@@ -360,8 +322,34 @@ def _load_schema(path: str | None) -> dict[str, list[str]] | None:
 
 
 def _parser() -> argparse.ArgumentParser:
+    """The whole command line. Each subparser stores its handler in ``run``.
+
+    Dispatching through ``set_defaults(run=...)`` rather than a chain of
+    ``if args.command == ...`` means a new subcommand is added in exactly one
+    place, and cannot be registered without being wired up.
+    """
     parser = argparse.ArgumentParser(
         prog="duckdb-kql",
+        description=(
+            "Run KQL on DuckDB. `translate` turns .kql files into .sql at build "
+            "time; `serve` puts a local Kusto REST endpoint in front of a DuckDB "
+            "database."
+        ),
+        epilog=(
+            "exit codes: 0 ok; 1 a query failed to translate, or the server "
+            "could not start; 2 bad usage; 3 --check found a missing or stale "
+            "output"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"duckdb-kql {__version__}")
+    # `required` so a bare `duckdb-kql` prints usage rather than a traceback
+    # about a missing `run` attribute.
+    subcommands = parser.add_subparsers(dest="command", metavar="COMMAND", required=True)
+
+    translate = subcommands.add_parser(
+        "translate",
+        help="translate .kql files to .sql",
         description=(
             "Translate KQL files to DuckDB SQL. The generated SQL has no "
             "dependency on this package, so queries can be translated once at "
@@ -373,13 +361,14 @@ def _parser() -> argparse.ArgumentParser:
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument(
+    translate.set_defaults(run=_translate_command)
+    translate.add_argument(
         "files",
         nargs="+",
         metavar="FILE",
         help="KQL files or directories to translate; '-' reads stdin",
     )
-    parser.add_argument(
+    translate.add_argument(
         "-o",
         "--output",
         metavar="PATH",
@@ -388,7 +377,7 @@ def _parser() -> argparse.ArgumentParser:
             "stdout."
         ),
     )
-    parser.add_argument(
+    translate.add_argument(
         "--check",
         action="store_true",
         help=(
@@ -396,7 +385,7 @@ def _parser() -> argparse.ArgumentParser:
             "in CI so an edited .kql cannot ship with a stale .sql."
         ),
     )
-    parser.add_argument(
+    translate.add_argument(
         "--schema",
         metavar="FILE",
         help=(
@@ -404,18 +393,59 @@ def _parser() -> argparse.ArgumentParser:
             "Only `join` needs it."
         ),
     )
-    parser.add_argument(
+    translate.add_argument(
         "--no-header",
         action="store_true",
         help="omit the generated-file comment block",
     )
-    parser.add_argument(
+    translate.add_argument(
         "-v",
         "--verbose",
         action="store_true",
         help="report each file written, on stderr",
     )
-    parser.add_argument("--version", action="version", version=f"duckdb-kql {__version__}")
+
+    serve = subcommands.add_parser(
+        "serve",
+        help="serve a DuckDB database over the Kusto REST API",
+        description=(
+            "Serve a DuckDB database over the Kusto REST API, so Kusto tools "
+            "can query it. Open https://dataexplorer.azure.com, choose Add "
+            "connection, and give it the URL this prints."
+        ),
+        epilog=(
+            "Listens on 127.0.0.1 only and cannot be made to listen anywhere "
+            "else: it answers unauthenticated queries, so reaching it has to "
+            "mean already being on this machine."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    serve.set_defaults(run=_serve_command)
+    serve.add_argument(
+        "database",
+        nargs="?",
+        default=":memory:",
+        metavar="DATABASE",
+        help="DuckDB database file to serve. Omit for an empty in-memory one.",
+    )
+    serve.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        metavar="PORT",
+        help=f"TCP port to listen on (default: {DEFAULT_PORT})",
+    )
+    serve.add_argument(
+        "--allow-origin",
+        action="append",
+        metavar="ORIGIN",
+        help=(
+            "additionally allow a browser origin to make cross-origin requests. "
+            "Repeatable. Replaces the Azure Data Explorer default list, and is a "
+            "decision about who may read this database from another browser tab."
+        ),
+    )
     return parser
 
 

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/tests/test_cli.py

@@ -10,6 +10,7 @@ promised not to need.
 
 from __future__ import annotations
 
+import argparse
 import re
 import subprocess
 import sys
@@ -45,7 +46,7 @@ def test_writes_to_stdout_by_default(
     project: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     """Writing files unasked would be a surprising default for a translator."""
-    assert main([str(project / "queries" / "count.kql")]) == EXIT_OK
+    assert main(["translate", str(project / "queries" / "count.kql")]) == EXIT_OK
     out = capsys.readouterr().out
     assert "SELECT" in out
     assert not list(project.glob("**/*.sql"))
@@ -53,20 +54,20 @@ def test_writes_to_stdout_by_default(
 
 def test_single_input_and_a_file_target(project: Path) -> None:
     target = project / "out" / "count.sql"
-    assert main([str(project / "queries" / "count.kql"), "-o", str(target)]) == EXIT_OK
+    assert main(["translate", str(project / "queries" / "count.kql"), "-o", str(target)]) == EXIT_OK
     assert "SELECT" in target.read_text(encoding="utf-8")
 
 
 def test_a_directory_input_expands_to_its_kql_files(project: Path) -> None:
     """A build script has a directory, not a shell-expanded list."""
     out = project / "build"
-    assert main([str(project / "queries"), "-o", str(out)]) == EXIT_OK
+    assert main(["translate", str(project / "queries"), "-o", str(out)]) == EXIT_OK
     assert sorted(p.name for p in out.glob("*.sql")) == ["by_state.sql", "count.sql"]
 
 
 def test_output_directory_is_created(project: Path) -> None:
     out = project / "deep" / "nested" / "build"
-    assert main([str(project / "queries"), "-o", str(out)]) == EXIT_OK
+    assert main(["translate", str(project / "queries"), "-o", str(out)]) == EXIT_OK
     assert (out / "count.sql").is_file()
 
 
@@ -76,7 +77,7 @@ def test_stdin_is_readable(
     import io  # noqa: PLC0415
 
     monkeypatch.setattr("sys.stdin", io.StringIO("print x = 1"))
-    assert main(["-"]) == EXIT_OK
+    assert main(["translate", "-"]) == EXIT_OK
     out = capsys.readouterr().out
     assert "<stdin>" in out
     assert 'AS "x"' in out
@@ -89,41 +90,41 @@ def test_stdin_is_readable(
 
 def test_check_passes_on_freshly_generated_output(project: Path) -> None:
     out = project / "build"
-    assert main([str(project / "queries"), "-o", str(out)]) == EXIT_OK
-    assert main([str(project / "queries"), "-o", str(out), "--check"]) == EXIT_OK
+    assert main(["translate", str(project / "queries"), "-o", str(out)]) == EXIT_OK
+    assert main(["translate", str(project / "queries"), "-o", str(out), "--check"]) == EXIT_OK
 
 
 def test_check_fails_when_the_kql_changed(project: Path) -> None:
     """The point of the mode: an edited query cannot ship a stale .sql."""
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out)])
+    main(["translate", str(project / "queries"), "-o", str(out)])
     (project / "queries" / "count.kql").write_text(SIMPLE + "| take 5\n", encoding="utf-8")
-    assert main([str(project / "queries"), "-o", str(out), "--check"]) == EXIT_STALE
+    assert main(["translate", str(project / "queries"), "-o", str(out), "--check"]) == EXIT_STALE
 
 
 def test_check_fails_when_the_output_is_missing(project: Path) -> None:
     assert (
-        main([str(project / "queries"), "-o", str(project / "nothing"), "--check"])
+        main(["translate", str(project / "queries"), "-o", str(project / "nothing"), "--check"])
         == EXIT_STALE
     )
 
 
 def test_check_writes_nothing(project: Path) -> None:
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out), "--check"])
+    main(["translate", str(project / "queries"), "-o", str(out), "--check"])
     assert not out.exists()
 
 
 def test_check_without_an_output_is_a_usage_error(project: Path) -> None:
     """There is nothing to compare stdout against; saying so beats exiting 0."""
-    assert main([str(project / "queries"), "--check"]) == 2
+    assert main(["translate", str(project / "queries"), "--check"]) == 2
 
 
 def test_check_names_the_stale_files(
     project: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out), "--check"])
+    main(["translate", str(project / "queries"), "-o", str(out), "--check"])
     assert "count.sql" in capsys.readouterr().err
 
 
@@ -139,7 +140,7 @@ def test_header_warns_about_the_time_zone(project: Path) -> None:
     Someone running generated SQL has no library to set it for them.
     """
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out)])
+    main(["translate", str(project / "queries"), "-o", str(out)])
     assert "SET TimeZone='UTC'" in (out / "count.sql").read_text(encoding="utf-8")
 
 
@@ -151,7 +152,7 @@ def test_header_carries_no_version_or_timestamp(project: Path) -> None:
     from duckdb_kql import __version__  # noqa: PLC0415
 
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out)])
+    main(["translate", str(project / "queries"), "-o", str(out)])
     header = (out / "count.sql").read_text(encoding="utf-8").split("\n\n")[0]
     assert __version__ not in header
     assert "20" not in header.replace("UTC", "")  # no year, no date
@@ -160,7 +161,7 @@ def test_header_carries_no_version_or_timestamp(project: Path) -> None:
 def test_header_maps_placeholders_back_to_parameter_names(project: Path) -> None:
     """``$kqlp0`` alone tells a caller nothing about what to bind."""
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out)])
+    main(["translate", str(project / "queries"), "-o", str(out)])
     sql = (out / "by_state.sql").read_text(encoding="utf-8")
 
     assert "$kqlp0" in sql and "state" in sql
@@ -172,13 +173,13 @@ def test_header_maps_placeholders_back_to_parameter_names(project: Path) -> None
 
 def test_no_header_produces_bare_sql(project: Path) -> None:
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out), "--no-header"])
+    main(["translate", str(project / "queries"), "-o", str(out), "--no-header"])
     assert (out / "count.sql").read_text(encoding="utf-8").startswith("WITH")
 
 
 def test_a_query_without_parameters_gets_no_parameter_block(project: Path) -> None:
     out = project / "build"
-    main([str(project / "queries"), "-o", str(out)])
+    main(["translate", str(project / "queries"), "-o", str(out)])
     assert "Query parameters" not in (out / "count.sql").read_text(encoding="utf-8")
 
 
@@ -193,7 +194,7 @@ def test_a_syntax_error_reports_file_line_and_column(
     """``file:line:col:`` is what editors and CI annotators parse."""
     bad = tmp_path / "bad.kql"
     bad.write_text("StormEvents | where State ==\n", encoding="utf-8")
-    assert main([str(bad)]) == EXIT_TRANSLATION_ERROR
+    assert main(["translate", str(bad)]) == EXIT_TRANSLATION_ERROR
     err = capsys.readouterr().err
     # The shape is what matters, not which line the parser stopped on.
     assert re.match(rf"^{re.escape(bad.as_posix())}:\d+:\d+: error: ", err), err
@@ -204,7 +205,7 @@ def test_an_unsupported_construct_is_an_error_not_a_guess(
 ) -> None:
     bad = tmp_path / "unsupported.kql"
     bad.write_text("StormEvents | parse State with * 'x' *\n", encoding="utf-8")
-    assert main([str(bad)]) == EXIT_TRANSLATION_ERROR
+    assert main(["translate", str(bad)]) == EXIT_TRANSLATION_ERROR
     assert "error:" in capsys.readouterr().err
 
 
@@ -214,14 +215,14 @@ def test_one_bad_file_does_not_stop_the_others(
     """A build reporting one error at a time is a slow build."""
     (project / "queries" / "bad.kql").write_text("| where", encoding="utf-8")
     out = project / "build"
-    assert main([str(project / "queries"), "-o", str(out)]) == EXIT_TRANSLATION_ERROR
+    assert main(["translate", str(project / "queries"), "-o", str(out)]) == EXIT_TRANSLATION_ERROR
     assert (out / "count.sql").is_file()
 
 
 def test_a_missing_file_is_reported_not_raised(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    assert main([str(tmp_path / "nope.kql")]) == EXIT_TRANSLATION_ERROR
+    assert main(["translate", str(tmp_path / "nope.kql")]) == EXIT_TRANSLATION_ERROR
     assert "nope.kql" in capsys.readouterr().err
 
 
@@ -239,6 +240,7 @@ def test_schema_file_enables_join(tmp_path: Path) -> None:
     assert (
         main(
             [
+                "translate",
                 str(tmp_path / "j.kql"),
                 "-o",
                 str(tmp_path / "j.sql"),
@@ -257,7 +259,7 @@ def test_a_malformed_schema_says_what_was_expected(
     (tmp_path / "q.kql").write_text("print 1", encoding="utf-8")
     (tmp_path / "schema.json").write_text('{"T": "not a list"}', encoding="utf-8")
     assert (
-        main([str(tmp_path / "q.kql"), "--schema", str(tmp_path / "schema.json")])
+        main(["translate", str(tmp_path / "q.kql"), "--schema", str(tmp_path / "schema.json")])
         == EXIT_TRANSLATION_ERROR
     )
     assert "list of column" in capsys.readouterr().err
@@ -280,7 +282,7 @@ def test_the_cli_does_not_import_duckdb(tmp_path: Path) -> None:
     probe.write_text(
         "import sys\n"
         "from duckdb_kql.cli import main\n"
-        f"main([{str(query)!r}, '-o', {str(tmp_path / 'q.sql')!r}])\n"
+        f"main(['translate', {str(query)!r}, '-o', {str(tmp_path / 'q.sql')!r}])\n"
         "assert 'duckdb' not in sys.modules, 'the CLI imported duckdb'\n"
         "print('clean')\n",
         encoding="utf-8",
@@ -300,7 +302,7 @@ def test_python_m_duckdb_kql_works(tmp_path: Path) -> None:
     query = tmp_path / "q.kql"
     query.write_text(SIMPLE, encoding="utf-8")
     proc = subprocess.run(  # noqa: S603 - fixed argv, no shell
-        [sys.executable, "-m", "duckdb_kql", str(query)],
+        [sys.executable, "-m", "duckdb_kql", "translate", str(query)],
         capture_output=True,
         text=True,
         check=False,
@@ -317,28 +319,69 @@ def test_the_console_script_is_declared() -> None:
 
 
 # ---------------------------------------------------------------------------
-# The `serve` subcommand
+# Subcommands
 # ---------------------------------------------------------------------------
 
+#: Every verb this command answers to. A new one that is not listed here is a
+#: new one nobody checked the wiring of.
+SUBCOMMANDS = ["translate", "serve"]
 
-def test_serve_is_the_only_word_that_is_not_a_filename(project: Path) -> None:
-    """Adding a subcommand must not turn the documented form into one.
 
-    `duckdb-kql queries/ -o out/` has to keep working exactly as before, which
-    is why the dispatch is a single literal rather than argparse subparsers.
+def test_the_subcommands_are_the_documented_ones() -> None:
+    from duckdb_kql.cli import _parser  # noqa: PLC0415
+
+    (subparsers,) = [
+        action
+        for action in _parser()._actions
+        if isinstance(action, argparse._SubParsersAction)
+    ]
+    assert sorted(subparsers.choices) == sorted(SUBCOMMANDS)
+
+
+@pytest.mark.parametrize("command", SUBCOMMANDS)
+def test_every_subcommand_is_wired_to_a_handler(command: str) -> None:
+    """Registering a subparser and forgetting `set_defaults(run=...)` would
+    parse fine and then fail on the attribute, in front of the user."""
+    from duckdb_kql.cli import _parser  # noqa: PLC0415
+
+    args = _parser().parse_args([command] + (["x.kql"] if command == "translate" else []))
+    assert callable(args.run)
+
+
+def test_a_bare_invocation_is_a_usage_error_not_a_traceback() -> None:
+    """`duckdb-kql` with no verb has nothing to do; 2 is argparse's usage code."""
+    with pytest.raises(SystemExit) as exit_code:
+        main([])
+    assert exit_code.value.code == 2
+
+
+def test_an_unknown_subcommand_lists_the_known_ones() -> None:
+    with pytest.raises(SystemExit) as exit_code:
+        main(["transalte", "q.kql"])
+    assert exit_code.value.code == 2
+
+
+def test_a_kql_file_is_no_longer_a_verb(tmp_path: Path) -> None:
+    """The breaking change, stated as a test.
+
+    `duckdb-kql queries/` used to translate. It is now a usage error, because a
+    filename in the verb slot is exactly the ambiguity subcommands remove — and
+    a silent reinterpretation would be worse than a refusal.
     """
-    out = project / "out"
-    assert main([str(project / "queries"), "-o", str(out)]) == EXIT_OK
-    assert (out / "count.sql").is_file()
+    query = tmp_path / "q.kql"
+    query.write_text(SIMPLE, encoding="utf-8")
+    with pytest.raises(SystemExit) as exit_code:
+        main([str(query)])
+    assert exit_code.value.code == 2
 
 
 def test_a_kql_file_called_serve_is_still_translated(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    """Only the bare word dispatches; `serve.kql` is a file like any other."""
+    """The verb slot is the only place `serve` is a verb."""
     query = tmp_path / "serve.kql"
     query.write_text(SIMPLE, encoding="utf-8")
-    assert main([str(query)]) == EXIT_OK
+    assert main(["translate", str(query)]) == EXIT_OK
     assert "SELECT" in capsys.readouterr().out
 
 
@@ -355,15 +398,24 @@ def test_serve_help_describes_the_local_only_guarantee(
 
 
 def test_serve_defaults_to_an_in_memory_database() -> None:
-    from duckdb_kql.cli import _serve_parser  # noqa: PLC0415
+    from duckdb_kql.cli import _parser  # noqa: PLC0415
 
-    args = _serve_parser().parse_args([])
+    args = _parser().parse_args(["serve"])
     assert args.database == ":memory:"
     assert args.port == 31415
 
 
 def test_serve_takes_a_port_override() -> None:
-    from duckdb_kql.cli import _serve_parser  # noqa: PLC0415
+    from duckdb_kql.cli import _parser  # noqa: PLC0415
+
+    assert _parser().parse_args(["serve", "--port", "9000"]).port == 9000
+    assert _parser().parse_args(["serve", "-p", "9000"]).port == 9000
 
-    assert _serve_parser().parse_args(["--port", "9000"]).port == 9000
-    assert _serve_parser().parse_args(["-p", "9000"]).port == 9000
+
+def test_the_top_level_help_names_both_jobs(capsys: pytest.CaptureFixture[str]) -> None:
+    """Someone typing `duckdb-kql` blind should learn what it can do."""
+    with pytest.raises(SystemExit):
+        main(["--help"])
+    printed = capsys.readouterr().out
+    for command in SUBCOMMANDS:
+        assert command in printed

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev4}/tests/test_server.py

@@ -109,9 +109,17 @@ def test_it_binds_to_loopback_only(server) -> None:
 
 def test_the_cli_cannot_ask_for_a_different_bind_address() -> None:
     """`--host` must not exist. A flag is all it would take to undo the above."""
-    from duckdb_kql.cli import _serve_parser
+    import argparse  # noqa: PLC0415
 
-    flags = {option for action in _serve_parser()._actions for option in action.option_strings}
+    from duckdb_kql.cli import _parser  # noqa: PLC0415
+
+    (subparsers,) = [
+        action
+        for action in _parser()._actions
+        if isinstance(action, argparse._SubParsersAction)
+    ]
+    serve = subparsers.choices["serve"]
+    flags = {option for action in serve._actions for option in action.option_strings}
     assert not flags & {"--host", "--bind", "--interface", "--address"}