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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: duckdb-kql
-Version: 0.0.1.dev3
+Version: 0.0.1.dev5
 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
@@ -44,6 +44,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Topic :: Database :: Front-Ends
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
@@ -133,7 +134,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.dev5}/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.dev5}/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.dev5}/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.dev5}/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.dev5}/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.dev5}/docs/kusto-server.md

@@ -66,6 +66,13 @@ https://dataexplorer.azure.us
 `--allow-origin` replaces that list. Widening it is a decision about who may read
 this database from another browser tab, not a formatting preference.
 
+The **origin** is the whole check. Request *headers* are not: a preflight echoes
+back whatever `Access-Control-Request-Headers` asked for, because naming a header
+authorises nothing and a hand-written list is only a second place to be wrong
+about someone else's client. It was wrong once — the list said `x-ms-user` where
+the web UI sends `x-ms-user-id`, and the browser answered by failing the real
+POST with a bare `net::ERR_FAILED` after a preflight that returned 204.
+
 **Nothing it serves can write.** The translated surface is read-only: no
 supported KQL operator produces a statement that modifies the database, and
 control commands that would administer a cluster are refused rather than

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev5}/pyproject.toml

@@ -31,6 +31,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Database",
     "Topic :: Database :: Front-Ends",
     "Topic :: Software Development :: Compilers",
@@ -167,7 +168,7 @@ files = ["src/duckdb_kql"]
 # way, and the next dependency to adopt the syntax would do it again. Letting
 # each interpreter check against itself is more robust *and* better coverage:
 # CI runs the floor and the ceiling, so 3.10-incompatible code fails on the
-# 3.10 lane while the newest semantics are exercised on the 3.13 one.
+# 3.10 lane while the newest semantics are exercised on the newest one.
 disallow_untyped_defs = true
 disallow_incomplete_defs = true
 disallow_untyped_calls = true

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev5}/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.dev5'
+__version_tuple__ = version_tuple = (0, 0, 1, 'dev5')
 
 __commit_id__ = commit_id = None

{duckdb_kql-0.0.1.dev3 → duckdb_kql-0.0.1.dev5}/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.dev5}/src/duckdb_kql/server.py

@@ -41,6 +41,7 @@ import uuid
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import TYPE_CHECKING, Any, NamedTuple, cast
 
+from . import __version__
 from .control import SCHEMA, CommandColumn, is_control_command, split_command
 from .errors import KqlError
 from .types import kusto_type, rest_datatype
@@ -347,11 +348,18 @@ def error_response(message: str, *, code: str = "General_BadRequest") -> dict[st
 
 _LOOPBACK = re.compile(r"^(127\.\d+\.\d+\.\d+|::1)$")
 
+#: Only for a preflight that names no headers, which no browser sends — a
+#: preflight exists *because* there is something non-simple to declare. Kept so
+#: the header is never emitted empty.
+_DEFAULT_ALLOW_HEADERS = "Authorization, Content-Type, Accept"
+
 
 class _Handler(BaseHTTPRequestHandler):
     """One request. The connection and the allow-list come from the server."""
 
-    server_version = f"duckdb-kql/{CLUSTER_NAME}"
+    # `duckdb-kql/0.1.2`, not `duckdb-kql/duckdb-kql`: the slot after the slash
+    # is a version, and this used to interpolate the cluster name into it.
+    server_version = f"duckdb-kql/{__version__}"
     # Announce HTTP/1.1 so the web UI's keep-alive works; every response below
     # sets Content-Length, which is what makes that safe.
     protocol_version = "HTTP/1.1"
@@ -406,17 +414,37 @@ class _Handler(BaseHTTPRequestHandler):
         self.send_response(204)
         self.send_header("Access-Control-Allow-Origin", origin)
         self.send_header("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
-        self.send_header(
-            "Access-Control-Allow-Headers",
-            "Authorization, Content-Type, x-ms-client-request-id, "
-            "x-ms-app, x-ms-user, x-ms-client-version, Accept, Connection",
-        )
+        self.send_header("Access-Control-Allow-Headers", self._allow_headers())
+        # Only when asked. Chrome gates requests from a public page to a private
+        # address behind this; answering unprompted would claim a policy the
+        # browser did not ask about.
+        if self.headers.get("Access-Control-Request-Private-Network") == "true":
+            self.send_header("Access-Control-Allow-Private-Network", "true")
         self.send_header("Access-Control-Allow-Credentials", "true")
         self.send_header("Access-Control-Max-Age", "600")
-        self.send_header("Vary", "Origin")
+        self.send_header("Vary", "Origin, Access-Control-Request-Headers")
         self.send_header("Content-Length", "0")
         self.end_headers()
 
+    def _allow_headers(self) -> str:
+        """The request headers the preflight permits: whatever was asked for.
+
+        Echoed rather than listed, because a hand-written list is a second place
+        to be wrong about someone else's client. It *was* wrong: the list said
+        `x-ms-user` where the Azure Data Explorer UI sends `x-ms-user-id`, CORS
+        matches header names exactly, and the browser answered by failing the
+        real POST with a bare `net::ERR_FAILED` — a preflight that returned 204
+        and still blocked the request. Every header the UI adds in future would
+        break it the same way.
+
+        This gives up nothing. Naming a header does not authorise anything; the
+        origin allow-list and the loopback bind are what decide who may talk to
+        this endpoint, and both are checked before we get here. `*` would be the
+        lazy version of this and is not equivalent — it is invalid alongside
+        `Allow-Credentials: true`, which is why the exact list is echoed back.
+        """
+        return self.headers.get("Access-Control-Request-Headers", _DEFAULT_ALLOW_HEADERS)
+
     def do_GET(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler's interface
         """A human landing page. Anything else 404s."""
         if not self._is_local():