tysql 0.1.0__tar.gz

tysql-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.3
+Name: tysql
+Version: 0.1.0
+Summary: Experimental, type-level PostgreSQL query builder prototype using PEP 827 typemaps.
+Keywords: mypy,pep-827,postgresql,query-builder,typemap,typing
+Author: Ilias Dzhabbarov
+Author-email: Ilias Dzhabbarov <iliyas.dzabbarov@gmail.com>
+License: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: python-typemap>=0.1.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/iliyasone/tysql
+Project-URL: Issues, https://github.com/iliyasone/tysql/issues
+Description-Content-Type: text/markdown
+
+# tysql
+
+Install with [uv](https://docs.astral.sh/uv/) — from PyPI, or straight from GitHub for the
+latest commit:
+
+```bash
+uv add tysql                                                        # core library, from PyPI
+uv add "tysql @ git+https://github.com/iliyasone/tysql.git"         # or the latest from GitHub
+uv add "mypy @ git+https://github.com/iliyasone/mypy-typemap.git"   # + the mypy fork for `tysql check`
+```
+
+**tysql** is an experimental, type-level query builder for PostgreSQL. A SQL
+statement is written as a *type* — `Select[User]` — and tysql
+
+- **statically infers the result type of every statement** and **rejects
+  ill-typed statements with a type error**, using the type operators from
+  [PEP 827](https://peps.python.org/pep-0827/); and
+- **renders the statement to PostgreSQL text** you could hand to a driver.
+
+It is a research prototype: the API is unstable and SQL coverage is deliberately
+narrow (see [what works](#what-works)). There is **no database bridge** — tysql
+produces types and SQL strings, it does not execute anything.
+
+## The idea
+
+PEP 827 lets a type checker evaluate small type-level programs. tysql uses that
+to make the *shape* of a query a static fact:
+
+```python
+from typing import Literal
+from tysql import Col, Cols, PrimaryKey, Select, Table, run
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+# SELECT id, email FROM "user"
+rows = run(Select[User, Cols[Col[User, Literal["id"]], Col[User, Literal["email"]]]], data=None)
+rows[0]["id"]     # int   — inferred
+rows[0]["email"]  # str   — inferred
+rows[0]["age"]    # type error: "age" is not in the projected row
+```
+
+`run`'s signature *is* the product: `data` is typed to the parameters the
+statement takes, and the return type is the list of rows it yields. Both are
+computed from the statement type by the combinators in
+[`tysql/shapes.py`](src/tysql/shapes.py).
+
+Until PEP 827 lands in a released type checker, the same evaluation is done two
+ways: at runtime by [`typemap`](https://github.com/iliyasone/python-typemap),
+and statically by a [`mypy` fork](https://github.com/iliyasone/mypy-typemap).
+tysql ships a **CLI validator** over that fork so the errors show up today,
+exactly where a stock type checker would raise them once PEP 827 is standard —
+see [CLI](#cli).
+
+## What works
+
+Type inference below holds on **both** tracks (the `mypy` fork *and* runtime
+`eval_typing`); SQL rendering is runtime (`tysql.render.render`).
+
+| Capability | Type inference | SQL rendering |
+| --- | :---: | :---: |
+| `CREATE TABLE` (incl. `SERIAL PRIMARY KEY`, `REFERENCES`) | — | ✅ |
+| `INSERT` — params inferred, `RETURNING` the primary key | ✅ | ✅ |
+| `SELECT *` — full row, primary key unwrapped (`PrimaryKey[int]` → `int`) | ✅ | ✅ |
+| `SELECT` projection — `Cols[...]` picks columns | ✅ | ✅ |
+| Column alias — `As[col, Literal["name"]]` | ✅ | ✅ |
+| `WHERE` — `Param`s collected into the inferred parameter mapping | ✅ | ✅ |
+| `INNER JOIN` with an explicit `On` predicate | ✅ | ✅ |
+| Aggregate `Count` (result typed `int`) | ✅ | ✅ |
+| `GROUP BY` / `ORDER BY` | ✅ | ✅ |
+
+### What it rejects
+
+The parameter and row types are exact `TypedDict`s, so a type checker (and the
+CLI) reject, at check time: a column that doesn't exist on its table
+(`Col: no such column`); a projected column whose table isn't in the `FROM`/`JOIN`
+(`Col: table is not in the FROM clause` — the "map the column to the table"
+check); reading a result column that wasn't selected; and an `INSERT`/`WHERE`
+`data` payload with a missing, extra, mis-named or wrong-typed key (the primary
+key may not be supplied on insert).
+
+Column checks are **per reference site**. A ✅ is enforced on both tracks; a ❌ is
+currently **accepted** — a known false negative, not a guarantee:
+
+| Column reference site | exists on its table | belongs to the `FROM` | operand types compatible |
+| --- | :---: | :---: | :---: |
+| `SELECT` projection | ✅ | ✅ | n/a |
+| join `ON` predicate | ✅ | ❌ | ❌ |
+| `WHERE` | ❌ | ❌ | ❌ |
+| `GROUP BY` / `ORDER BY` | ❌ | ❌ | n/a |
+
+### Not implemented
+
+Out of scope for this prototype — tysql produces types and SQL text only, and no
+database is contacted:
+
+| Not implemented | Notes |
+| --- | --- |
+| Query execution / database bridge | `run` raises `NotImplementedError`; use `render` for SQL text |
+| `LEFT` / `RIGHT` / `FULL` / `CROSS JOIN` | `INNER JOIN` only |
+| `OR` / `NOT` / nested boolean in `WHERE` | flat conjunction (`AND`) of `Eq` only |
+| Comparison operators other than `=` (`<`, `>`, `LIKE`, `IN`, `BETWEEN`) | `Eq` only |
+| Aggregates other than `Count` (`SUM`, `AVG`, `MIN`, `MAX`) | — |
+| `HAVING`, `LIMIT`, `OFFSET`, `DISTINCT` | — |
+| Subqueries, CTEs (`WITH`), set operations (`UNION`) | — |
+| `UPDATE` / `DELETE` statements | `CREATE TABLE`, `INSERT`, `SELECT` only |
+| `WHERE` param type inferred from its column | declared explicitly via `Param[name, T]`, not cross-checked |
+| `GROUP BY` functional-dependency check | not enforced (unlike PostgreSQL) |
+
+### Examples
+
+```python
+from typing import Literal
+from tysql import (
+    As, Col, Cols, Count, Eq, GroupBy, InnerJoin, On, OrderBy, Param, Select, Where, run,
+)
+
+# WHERE, with parameters inferred from the clause
+Select[User, Cols[Col[User, Literal["id"]]],
+       Where[Eq[Col[User, Literal["age"]], Param[Literal["min_age"], int]]]]
+# rows: {"id": int};  data: {"min_age": int}
+
+# explicit INNER JOIN — columns from both tables in one row
+Select[InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]], Col[Post, Literal["author"]]]]],
+       Cols[Col[User, Literal["email"]], Col[Post, Literal["text"]]]]
+# rows: {"email": str, "text": str}
+
+# aggregate + GROUP BY + ORDER BY
+Select[InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]], Col[Post, Literal["author"]]]]],
+       Cols[Col[User, Literal["id"]], As[Count[Col[Post, Literal["id"]]], Literal["n_posts"]]],
+       GroupBy[Col[User, Literal["id"]]],
+       OrderBy[Col[User, Literal["id"]], Literal["asc"]]]
+# rows: {"id": int, "n_posts": int}
+```
+
+Rendering the last statement with `tysql.render.render` yields:
+
+```sql
+SELECT "user"."id", count("post"."id") AS "n_posts"
+FROM "user" INNER JOIN "post" ON "user"."id" = "post"."author"
+GROUP BY "user"."id" ORDER BY "user"."id" ASC;
+```
+
+A larger example schema lives in [`src/examples/users.py`](src/examples/users.py).
+
+## CLI
+
+Installing tysql provides a `tysql` command that wraps the pinned `mypy` fork, so
+PEP 827 combinator types resolve to real types instead of `Any`. The fork cannot
+be a PyPI dependency (direct URL), so install it next to tysql from GitHub:
+`uv add "mypy @ git+https://github.com/iliyasone/mypy-typemap.git"`.
+
+```bash
+tysql check [PATH ...]   # type-check paths (default: .) — rejects ill-typed statements
+tysql mypy  [ARG ...]    # forward arguments straight to the fork's mypy
+```
+
+`tysql check some_file.py` reports, for instance, `Col: no such column` when a
+statement references a column that does not exist — the same error a type
+checker will emit once PEP 827 is standard.
+
+## Development
+
+```bash
+uv sync --all-groups
+
+uv run ruff check .   # lint
+uv run mypy .         # static type-check — the primary type-level test layer
+uv run pytest         # runtime tests
+```
+
+`mypy` is part of the test contract. Two conventions make it load-bearing:
+
+- `mypy_test_*` functions (bodies under `if TYPE_CHECKING:`) are **not** collected
+  by pytest but **are** checked by the fork — they assert inferred types with
+  `assert_type`.
+- `--warn-unused-ignores` is on, so every `# type: ignore[code]` is a negative
+  assertion: if the fork stops emitting that error, the run fails.
+
+PostgreSQL integration dependencies (for a future execution bridge) are staged
+in the `postgres` dependency group.

tysql-0.1.0/README.md

@@ -0,0 +1,185 @@
+# tysql
+
+Install with [uv](https://docs.astral.sh/uv/) — from PyPI, or straight from GitHub for the
+latest commit:
+
+```bash
+uv add tysql                                                        # core library, from PyPI
+uv add "tysql @ git+https://github.com/iliyasone/tysql.git"         # or the latest from GitHub
+uv add "mypy @ git+https://github.com/iliyasone/mypy-typemap.git"   # + the mypy fork for `tysql check`
+```
+
+**tysql** is an experimental, type-level query builder for PostgreSQL. A SQL
+statement is written as a *type* — `Select[User]` — and tysql
+
+- **statically infers the result type of every statement** and **rejects
+  ill-typed statements with a type error**, using the type operators from
+  [PEP 827](https://peps.python.org/pep-0827/); and
+- **renders the statement to PostgreSQL text** you could hand to a driver.
+
+It is a research prototype: the API is unstable and SQL coverage is deliberately
+narrow (see [what works](#what-works)). There is **no database bridge** — tysql
+produces types and SQL strings, it does not execute anything.
+
+## The idea
+
+PEP 827 lets a type checker evaluate small type-level programs. tysql uses that
+to make the *shape* of a query a static fact:
+
+```python
+from typing import Literal
+from tysql import Col, Cols, PrimaryKey, Select, Table, run
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+# SELECT id, email FROM "user"
+rows = run(Select[User, Cols[Col[User, Literal["id"]], Col[User, Literal["email"]]]], data=None)
+rows[0]["id"]     # int   — inferred
+rows[0]["email"]  # str   — inferred
+rows[0]["age"]    # type error: "age" is not in the projected row
+```
+
+`run`'s signature *is* the product: `data` is typed to the parameters the
+statement takes, and the return type is the list of rows it yields. Both are
+computed from the statement type by the combinators in
+[`tysql/shapes.py`](src/tysql/shapes.py).
+
+Until PEP 827 lands in a released type checker, the same evaluation is done two
+ways: at runtime by [`typemap`](https://github.com/iliyasone/python-typemap),
+and statically by a [`mypy` fork](https://github.com/iliyasone/mypy-typemap).
+tysql ships a **CLI validator** over that fork so the errors show up today,
+exactly where a stock type checker would raise them once PEP 827 is standard —
+see [CLI](#cli).
+
+## What works
+
+Type inference below holds on **both** tracks (the `mypy` fork *and* runtime
+`eval_typing`); SQL rendering is runtime (`tysql.render.render`).
+
+| Capability | Type inference | SQL rendering |
+| --- | :---: | :---: |
+| `CREATE TABLE` (incl. `SERIAL PRIMARY KEY`, `REFERENCES`) | — | ✅ |
+| `INSERT` — params inferred, `RETURNING` the primary key | ✅ | ✅ |
+| `SELECT *` — full row, primary key unwrapped (`PrimaryKey[int]` → `int`) | ✅ | ✅ |
+| `SELECT` projection — `Cols[...]` picks columns | ✅ | ✅ |
+| Column alias — `As[col, Literal["name"]]` | ✅ | ✅ |
+| `WHERE` — `Param`s collected into the inferred parameter mapping | ✅ | ✅ |
+| `INNER JOIN` with an explicit `On` predicate | ✅ | ✅ |
+| Aggregate `Count` (result typed `int`) | ✅ | ✅ |
+| `GROUP BY` / `ORDER BY` | ✅ | ✅ |
+
+### What it rejects
+
+The parameter and row types are exact `TypedDict`s, so a type checker (and the
+CLI) reject, at check time: a column that doesn't exist on its table
+(`Col: no such column`); a projected column whose table isn't in the `FROM`/`JOIN`
+(`Col: table is not in the FROM clause` — the "map the column to the table"
+check); reading a result column that wasn't selected; and an `INSERT`/`WHERE`
+`data` payload with a missing, extra, mis-named or wrong-typed key (the primary
+key may not be supplied on insert).
+
+Column checks are **per reference site**. A ✅ is enforced on both tracks; a ❌ is
+currently **accepted** — a known false negative, not a guarantee:
+
+| Column reference site | exists on its table | belongs to the `FROM` | operand types compatible |
+| --- | :---: | :---: | :---: |
+| `SELECT` projection | ✅ | ✅ | n/a |
+| join `ON` predicate | ✅ | ❌ | ❌ |
+| `WHERE` | ❌ | ❌ | ❌ |
+| `GROUP BY` / `ORDER BY` | ❌ | ❌ | n/a |
+
+### Not implemented
+
+Out of scope for this prototype — tysql produces types and SQL text only, and no
+database is contacted:
+
+| Not implemented | Notes |
+| --- | --- |
+| Query execution / database bridge | `run` raises `NotImplementedError`; use `render` for SQL text |
+| `LEFT` / `RIGHT` / `FULL` / `CROSS JOIN` | `INNER JOIN` only |
+| `OR` / `NOT` / nested boolean in `WHERE` | flat conjunction (`AND`) of `Eq` only |
+| Comparison operators other than `=` (`<`, `>`, `LIKE`, `IN`, `BETWEEN`) | `Eq` only |
+| Aggregates other than `Count` (`SUM`, `AVG`, `MIN`, `MAX`) | — |
+| `HAVING`, `LIMIT`, `OFFSET`, `DISTINCT` | — |
+| Subqueries, CTEs (`WITH`), set operations (`UNION`) | — |
+| `UPDATE` / `DELETE` statements | `CREATE TABLE`, `INSERT`, `SELECT` only |
+| `WHERE` param type inferred from its column | declared explicitly via `Param[name, T]`, not cross-checked |
+| `GROUP BY` functional-dependency check | not enforced (unlike PostgreSQL) |
+
+### Examples
+
+```python
+from typing import Literal
+from tysql import (
+    As, Col, Cols, Count, Eq, GroupBy, InnerJoin, On, OrderBy, Param, Select, Where, run,
+)
+
+# WHERE, with parameters inferred from the clause
+Select[User, Cols[Col[User, Literal["id"]]],
+       Where[Eq[Col[User, Literal["age"]], Param[Literal["min_age"], int]]]]
+# rows: {"id": int};  data: {"min_age": int}
+
+# explicit INNER JOIN — columns from both tables in one row
+Select[InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]], Col[Post, Literal["author"]]]]],
+       Cols[Col[User, Literal["email"]], Col[Post, Literal["text"]]]]
+# rows: {"email": str, "text": str}
+
+# aggregate + GROUP BY + ORDER BY
+Select[InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]], Col[Post, Literal["author"]]]]],
+       Cols[Col[User, Literal["id"]], As[Count[Col[Post, Literal["id"]]], Literal["n_posts"]]],
+       GroupBy[Col[User, Literal["id"]]],
+       OrderBy[Col[User, Literal["id"]], Literal["asc"]]]
+# rows: {"id": int, "n_posts": int}
+```
+
+Rendering the last statement with `tysql.render.render` yields:
+
+```sql
+SELECT "user"."id", count("post"."id") AS "n_posts"
+FROM "user" INNER JOIN "post" ON "user"."id" = "post"."author"
+GROUP BY "user"."id" ORDER BY "user"."id" ASC;
+```
+
+A larger example schema lives in [`src/examples/users.py`](src/examples/users.py).
+
+## CLI
+
+Installing tysql provides a `tysql` command that wraps the pinned `mypy` fork, so
+PEP 827 combinator types resolve to real types instead of `Any`. The fork cannot
+be a PyPI dependency (direct URL), so install it next to tysql from GitHub:
+`uv add "mypy @ git+https://github.com/iliyasone/mypy-typemap.git"`.
+
+```bash
+tysql check [PATH ...]   # type-check paths (default: .) — rejects ill-typed statements
+tysql mypy  [ARG ...]    # forward arguments straight to the fork's mypy
+```
+
+`tysql check some_file.py` reports, for instance, `Col: no such column` when a
+statement references a column that does not exist — the same error a type
+checker will emit once PEP 827 is standard.
+
+## Development
+
+```bash
+uv sync --all-groups
+
+uv run ruff check .   # lint
+uv run mypy .         # static type-check — the primary type-level test layer
+uv run pytest         # runtime tests
+```
+
+`mypy` is part of the test contract. Two conventions make it load-bearing:
+
+- `mypy_test_*` functions (bodies under `if TYPE_CHECKING:`) are **not** collected
+  by pytest but **are** checked by the fork — they assert inferred types with
+  `assert_type`.
+- `--warn-unused-ignores` is on, so every `# type: ignore[code]` is a negative
+  assertion: if the fork stops emitting that error, the run fails.
+
+PostgreSQL integration dependencies (for a future execution bridge) are staged
+in the `postgres` dependency group.

tysql-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.9.11,<0.12.0"]
+
+[project]
+authors = [{name = "Ilias Dzhabbarov", email = "iliyas.dzabbarov@gmail.com"}]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "python-typemap>=0.1.0",
+]
+description = "Experimental, type-level PostgreSQL query builder prototype using PEP 827 typemaps."
+keywords = ["mypy", "pep-827", "postgresql", "query-builder", "typemap", "typing"]
+license = {text = "MIT"}
+name = "tysql"
+readme = "README.md"
+requires-python = ">=3.14"
+version = "0.1.0"
+
+[project.scripts]
+tysql = "tysql.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/iliyasone/tysql"
+Issues = "https://github.com/iliyasone/tysql/issues"
+
+[dependency-groups]
+# The mypy fork is only needed by `tysql check` / `tysql mypy`. It cannot ship as a
+# PyPI extra (PyPI rejects direct URL dependencies), so users install it from git:
+#   uv add "mypy @ git+https://github.com/iliyasone/mypy-typemap.git"
+lint = [
+  "mypy @ git+https://github.com/iliyasone/mypy-typemap.git",
+  "ruff>=0.14.7",
+]
+postgres = [
+  "psycopg[binary]>=3.0.0",
+  "testcontainers>=4.0.0",
+]
+test = [
+  "pytest>=9.0.3",
+]
+
+[tool.mypy]
+enable_error_code = ["ignore-without-code"]
+python_version = "3.14"
+show_error_codes = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+markers = [
+  "postgres: integration tests that require Docker and PostgreSQL",
+]
+python_functions = ["test_*"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "UP"]

tysql-0.1.0/src/tysql/__init__.py

@@ -0,0 +1,51 @@
+"""tysql: a type-level PostgreSQL query builder prototype.
+
+Statements are written as types (``Select[User]``); ``shapes`` infers the
+parameters and result rows they carry, and ``render`` turns them into SQL text.
+"""
+
+from tysql.render import render
+from tysql.schema import Col, Column, ForeignKey, PrimaryKey, Table
+from tysql.shapes import ParamsOf, ResultOf, run
+from tysql.statements import (
+    As,
+    Cols,
+    Count,
+    CreateTable,
+    Eq,
+    GroupBy,
+    InnerJoin,
+    Insert,
+    On,
+    OrderBy,
+    Param,
+    Select,
+    Statement,
+    Where,
+)
+
+__all__ = [
+    "As",
+    "Col",
+    "Cols",
+    "Column",
+    "Count",
+    "CreateTable",
+    "Eq",
+    "ForeignKey",
+    "GroupBy",
+    "InnerJoin",
+    "Insert",
+    "On",
+    "OrderBy",
+    "Param",
+    "ParamsOf",
+    "PrimaryKey",
+    "ResultOf",
+    "Select",
+    "Statement",
+    "Table",
+    "Where",
+    "render",
+    "run",
+]

tysql-0.1.0/src/tysql/__main__.py

@@ -0,0 +1,4 @@
+from tysql.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tysql-0.1.0/src/tysql/cli.py

@@ -0,0 +1,101 @@
+"""Command-line entry point for tysql.
+
+Two subcommands, both backed by the pinned mypy fork (`msullivan/mypy-typemap`)
+that evaluates PEP 827 combinators natively:
+
+- ``tysql check [PATH ...]``  - type-check the given paths (default: ``.``) with
+  tysql-appropriate defaults. This is the friendly command most users want.
+- ``tysql mypy [ARG ...]``    - forward every argument verbatim to the fork's
+  mypy. The escape hatch for full mypy control.
+
+Both run ``python -m mypy`` in the *current* interpreter, so the mypy that gets
+used is whichever one tysql was installed alongside. The fork cannot ship as a
+PyPI dependency (direct URL), so it is installed from git next to tysql; that is
+what makes the combinator types resolve to real types instead of ``Any``.
+"""
+
+import subprocess
+import sys
+from collections.abc import Sequence
+from importlib.util import find_spec
+from pathlib import Path
+
+# Marker file that only the mypy fork ships in its bundled typeshed. Its presence
+# is how we tell "our mypy" apart from a stock one.
+_FORK_MARKER = Path("typeshed", "stdlib", "_typeshed", "typemap.pyi")
+
+# Defaults layered under `tysql check` before the user's own paths/flags.
+_CHECK_DEFAULTS = ("--show-error-codes",)
+
+_USAGE = """\
+usage: tysql <command> [args]
+
+commands:
+  check [PATH ...]   type-check paths with the tysql mypy fork (default: .)
+  mypy  [ARG ...]    forward all arguments straight to the mypy fork
+
+Run `tysql mypy --help` for the full set of mypy flags.
+"""
+
+
+def _is_fork() -> bool:
+    """True when the importable mypy looks like the tysql fork.
+
+    Uses ``find_spec`` so we never import (and pay the startup cost of) mypy just
+    to answer the question.
+    """
+    spec = find_spec("mypy")
+    if spec is None or spec.origin is None:
+        return False
+    return (Path(spec.origin).parent / _FORK_MARKER).is_file()
+
+
+def _warn_if_not_fork() -> None:
+    if not _is_fork():
+        print(
+            "tysql: warning: no tysql mypy fork found; PEP 827 combinator types "
+            "will collapse to Any. Install the fork from GitHub, e.g.\n"
+            '  uv add "mypy @ git+https://github.com/iliyasone/mypy-typemap.git"',
+            file=sys.stderr,
+        )
+
+
+def _run_mypy(args: Sequence[str]) -> int:
+    """Invoke the fork's mypy in this interpreter, streaming its output."""
+    completed = subprocess.run([sys.executable, "-m", "mypy", *args])
+    return completed.returncode
+
+
+def _cmd_mypy(args: Sequence[str]) -> int:
+    _warn_if_not_fork()
+    return _run_mypy(args)
+
+
+def _cmd_check(args: Sequence[str]) -> int:
+    _warn_if_not_fork()
+    # No arguments at all -> check the current tree. Once the user passes
+    # anything (paths and/or extra mypy flags) we forward it untouched.
+    targets = list(args) if args else ["."]
+    return _run_mypy([*_CHECK_DEFAULTS, *targets])
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv or argv[0] in ("-h", "--help"):
+        sys.stdout.write(_USAGE)
+        return 0 if argv else 2
+
+    command, rest = argv[0], argv[1:]
+    if command == "check":
+        return _cmd_check(rest)
+    if command == "mypy":
+        return _cmd_mypy(rest)
+
+    sys.stderr.write(f"tysql: unknown command {command!r}\n\n")
+    sys.stderr.write(_USAGE)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tysql-0.1.0/src/tysql/py.typed

@@ -0,0 +1 @@
+

tysql-0.1.0/src/tysql/render.py

@@ -0,0 +1,202 @@
+"""Render a statement type to PostgreSQL text.
+
+This is the runtime companion to ``tysql.shapes``: the shapes track says what a
+statement *returns*, this says what it *is*. It walks the statement type with
+``typing.get_origin`` / ``get_args`` and emits SQL a person would recognise --
+qualified identifiers, ``psycopg`` named placeholders (``%(name)s``), and a
+``RETURNING`` clause on inserts. It does not talk to a database; there is no
+connection here, only text.
+"""
+
+from datetime import datetime
+from typing import Any, get_args, get_origin
+
+from tysql.schema import Column, ForeignKey, PrimaryKey
+from tysql.statements import (
+    As,
+    Cols,
+    Count,
+    CreateTable,
+    GroupBy,
+    InnerJoin,
+    Insert,
+    On,
+    OrderBy,
+    Param,
+    Select,
+    Where,
+)
+
+# Python value type -> PostgreSQL column type.
+_PG_TYPES: dict[Any, str] = {
+    int: "INTEGER",
+    str: "TEXT",
+    bool: "BOOLEAN",
+    float: "DOUBLE PRECISION",
+    bytes: "BYTEA",
+    datetime: "TIMESTAMP",
+}
+
+
+def render(stmt: Any) -> str:
+    """Render a statement type such as ``Select[User]`` to a PostgreSQL string."""
+    origin = get_origin(stmt)
+    if origin is CreateTable:
+        return _render_create(stmt)
+    if origin is Insert:
+        return _render_insert(stmt)
+    if origin is Select:
+        return _render_select(stmt)
+    raise ValueError(f"render: unsupported statement {stmt!r}")
+
+
+# --- identifiers and small parts --------------------------------------------
+
+
+def _ident(name: str) -> str:
+    return f'"{name}"'
+
+
+def _table_ref(table: type) -> str:
+    return _ident(table.__name__.lower())
+
+
+def _literal(lit: Any) -> Any:
+    """The single value inside a ``Literal[...]``."""
+    return get_args(lit)[0]
+
+
+def _column_ref(col: Any) -> str:
+    """``Col[User, Literal["id"]]`` -> ``"user"."id"``."""
+    owner, name_literal = get_args(col)[:2]
+    return f"{_table_ref(owner)}.{_ident(_literal(name_literal))}"
+
+
+def _expr(expr: Any) -> str:
+    """A projected item or predicate operand: a column, ``count(...)`` or a placeholder."""
+    origin = get_origin(expr)
+    if origin is Count:
+        return f"count({_column_ref(get_args(expr)[0])})"
+    if origin is Param:
+        return f"%({_literal(get_args(expr)[0])})s"
+    return _column_ref(expr)
+
+
+def _projection_item(item: Any) -> str:
+    if get_origin(item) is As:
+        expr, alias = get_args(item)
+        return f"{_expr(expr)} AS {_ident(_literal(alias))}"
+    return _expr(item)
+
+
+def _predicate(pred: Any) -> str:
+    left, right = get_args(pred)
+    return f"{_expr(left)} = {_expr(right)}"
+
+
+def _base_pg_type(annotation: Any) -> str:
+    return _PG_TYPES.get(annotation, "TEXT")
+
+
+# --- FROM / joins -----------------------------------------------------------
+
+
+def _from(source: Any) -> str:
+    if get_origin(source) is InnerJoin:
+        left, right, *mods = get_args(source)
+        clause = f"{_table_ref(left)} INNER JOIN {_table_ref(right)}"
+        on = _find(mods, On)
+        if on is not None:
+            clause += f" ON {_predicate(get_args(on)[0])}"
+        return clause
+    return _table_ref(source)
+
+
+def _find(mods: tuple[Any, ...] | list[Any], combinator: Any) -> Any:
+    """The first modifier whose origin is ``combinator``, or ``None``."""
+    for mod in mods:
+        if get_origin(mod) is combinator:
+            return mod
+    return None
+
+
+# --- statements -------------------------------------------------------------
+
+
+def _columns(table: type) -> list[Column[Any, Any, Any]]:
+    return list(table.__tysql_columns__.values())  # type: ignore[attr-defined]
+
+
+def _is_primary_key(annotation: Any) -> bool:
+    return get_origin(annotation) is PrimaryKey
+
+
+def _column_ddl(column: Column[Any, Any, Any]) -> str:
+    annotation = column.type
+    origin = get_origin(annotation)
+    if origin is PrimaryKey:
+        inner = get_args(annotation)[0]
+        kind = "SERIAL PRIMARY KEY" if inner is int else f"{_base_pg_type(inner)} PRIMARY KEY"
+        return f"{_ident(column.name)} {kind}"
+    if origin is ForeignKey:
+        ref, name_literal = get_args(annotation)
+        name = _literal(name_literal)
+        referenced = ref.__tysql_columns__[name].type
+        if get_origin(referenced) is PrimaryKey:
+            referenced = get_args(referenced)[0]
+        return (
+            f"{_ident(column.name)} {_base_pg_type(referenced)} NOT NULL "
+            f"REFERENCES {_table_ref(ref)}({_ident(name)})"
+        )
+    return f"{_ident(column.name)} {_base_pg_type(annotation)} NOT NULL"
+
+
+def _render_create(stmt: Any) -> str:
+    table = get_args(stmt)[0]
+    lines = ",\n".join(f"    {_column_ddl(c)}" for c in _columns(table))
+    return f"CREATE TABLE {_table_ref(table)} (\n{lines}\n);"
+
+
+def _render_insert(stmt: Any) -> str:
+    table = get_args(stmt)[0]
+    inserted = [c for c in _columns(table) if not _is_primary_key(c.type)]
+    keys = [c for c in _columns(table) if _is_primary_key(c.type)]
+    names = ", ".join(_ident(c.name) for c in inserted)
+    placeholders = ", ".join(f"%({c.name})s" for c in inserted)
+    sql = f"INSERT INTO {_table_ref(table)} ({names}) VALUES ({placeholders})"
+    if keys:
+        sql += " RETURNING " + ", ".join(_ident(c.name) for c in keys)
+    return sql + ";"
+
+
+def _star_projection(source: Any) -> str:
+    if get_origin(source) is InnerJoin:
+        return "*"
+    return ", ".join(f"{_table_ref(source)}.{_ident(c.name)}" for c in _columns(source))
+
+
+def _render_select(stmt: Any) -> str:
+    source, *mods = get_args(stmt)
+
+    cols = _find(mods, Cols)
+    if cols is not None:
+        projection = ", ".join(_projection_item(c) for c in get_args(cols))
+    else:
+        projection = _star_projection(source)
+
+    sql = f"SELECT {projection} FROM {_from(source)}"
+
+    where = _find(mods, Where)
+    if where is not None:
+        sql += " WHERE " + " AND ".join(_predicate(p) for p in get_args(where))
+
+    group_by = _find(mods, GroupBy)
+    if group_by is not None:
+        sql += " GROUP BY " + ", ".join(_column_ref(c) for c in get_args(group_by))
+
+    order_by = _find(mods, OrderBy)
+    if order_by is not None:
+        column, direction = get_args(order_by)
+        sql += f" ORDER BY {_column_ref(column)} {str(_literal(direction)).upper()}"
+
+    return sql + ";"

tysql-0.1.0/src/tysql/schema.py

@@ -0,0 +1,64 @@
+import sys
+from typing import Any, Literal, Never, get_type_hints
+
+if sys.version_info >= (3, 16):
+    # When PEP 827 lands in the stdlib (hoped for 3.16+), the combinators live in `typing` itself.
+    import typing
+else:
+    import typemap_extensions as typing
+
+
+class Column[Owner, Name, T]:
+    """Column reference carrying owner, column name, and value type."""
+
+    def __init__(self, owner: type, name: str, type_: Any) -> None:
+        self.owner = owner
+        self.name = name
+        self.type = type_
+
+    def __repr__(self) -> str:
+        type_name = getattr(self.type, "__name__", repr(self.type))
+        return f"Column({self.owner.__name__}.{self.name}: {type_name})"
+
+
+class Table:
+    def __init_subclass__[T](
+        cls: type[T],
+    ) -> typing.UpdateClass[
+        *[typing.Member[x.name, Column[T, x.name, x.type]] for x in typing.Iter[typing.Attrs[T]]]
+    ]:
+        # TODO: validate types
+        columns: dict[str, Column[Any, Any, Any]] = {}
+        for name, annotation in get_type_hints(cls).items():
+            column: Column[Any, Any, Any] = Column(cls, name, annotation)
+            columns[name] = column
+            setattr(cls, name, column)
+        cls.__tysql_columns__ = columns  # type: ignore[attr-defined]
+        return None  # type: ignore[return-value]
+
+
+# A column reference: Col[User, Literal["id"]] resolves to the Column that the
+# Table metaclass injected for `id`, or a "no such column" type error.
+#
+# This is a flat two-way conditional on purpose. A chained `A if .. else B if ..
+# else C` makes the static fork eagerly evaluate the deepest branch even when it
+# is not selected, so a RaiseError in a trailing `else` fires for *valid*
+# columns. Keeping the RaiseError in the taken-only branch avoids that.
+type Col[C, N] = (
+    typing.RaiseError[Literal["Col: no such column"]]
+    if typing.IsEquivalent[typing.GetMemberType[C, N], Never]
+    else typing.GetMemberType[C, N]
+)
+
+
+class PrimaryKey[T]:
+    """Marks a column as the table's primary key; unwrapped to ``T`` in results."""
+
+
+class ForeignKey[Owner, Name]:
+    """A foreign key referencing ``Owner``'s column ``Name``.
+
+    Written ``ForeignKey[User, Literal["id"]]`` rather than nesting a ``Col``,
+    so the reference stays a plain type argument (a conditional ``Col`` in
+    annotation position would eagerly trip its own "no such column" guard).
+    """

tysql-0.1.0/src/tysql/shapes.py

@@ -0,0 +1,223 @@
+"""Type-level shapes: from a statement type to its parameters and result rows.
+
+Each combinator here is a PEP 827 type function. The runtime track evaluates
+them with ``typemap.type_eval.eval_typing``; the static track evaluates the very
+same aliases inside the ``mypy-typemap`` fork. Both must agree, which shapes how
+these are written:
+
+- only conditionals (``A if Cond else B``) and *single* comprehensions are used;
+  the fork does not support recursive aliases or nested ``for`` comprehensions;
+- ``RaiseError`` branches stay on the value-position path (through ``run`` /
+  ``eval_typing``), never in bare annotations, where the fork would force them.
+"""
+
+import sys
+from typing import Any, Literal
+
+from tysql.schema import Column, PrimaryKey
+from tysql.statements import (
+    As,
+    Cols,
+    Count,
+    CreateTable,
+    Eq,
+    InnerJoin,
+    Insert,
+    Param,
+    Select,
+    Statement,
+    Where,
+)
+
+if sys.version_info >= (3, 16):
+    # When PEP 827 lands in the stdlib (hoped for 3.16+), the combinators live in `typing` itself.
+    import typing
+else:
+    import typemap_extensions as typing
+
+
+# A table type -> the TypedDict you pass to INSERT: every column except the
+# primary key, which the database fills in.
+type Row[T] = typing.NewTypedDict[
+    *[
+        typing.Member[x.name, typing.GetArg[x.type, Column, Literal[2]]]
+        for x in typing.Iter[typing.Attrs[T]]
+        if not typing.IsAssignable[x.type, Column[Any, Any, PrimaryKey[Any]]]
+    ]
+]
+
+
+# A column's value as it comes back from a query: PrimaryKey[int] -> int,
+# anything else unchanged.
+type Unwrap[T] = (
+    typing.GetArg[T, PrimaryKey, Literal[0]] if typing.IsAssignable[T, PrimaryKey[Any]] else T
+)
+
+
+# A table type -> the TypedDict of a full result row: every column, PK unwrapped.
+type ResultRow[T] = typing.NewTypedDict[
+    *[
+        typing.Member[x.name, Unwrap[typing.GetArg[x.type, Column, Literal[2]]]]
+        for x in typing.Iter[typing.Attrs[T]]
+    ]
+]
+
+
+# --- projection -------------------------------------------------------------
+#
+# A projected item is a bare column, an As[expr, Literal[alias]] rename, or an
+# aggregate. These three helpers each take one item and are applied to the loop
+# variable of ProjectedRow's comprehension (helper aliases on a loop variable
+# evaluate on both tracks; nested comprehensions do not).
+
+# The output key: the alias if the item is wrapped in As, else the column name.
+type ItemName[C] = (
+    typing.GetArg[C, As, Literal[1]]
+    if typing.IsAssignable[C, As[Any, Any]]
+    else typing.GetArg[C, Column, Literal[1]]
+)
+
+
+# The underlying expression: unwrap one layer of As.
+type ItemExpr[C] = typing.GetArg[C, As, Literal[0]] if typing.IsAssignable[C, As[Any, Any]] else C
+
+
+# The value type of an expression: Count[...] is int; a column is its own type
+# with the primary key unwrapped.
+type ItemType[E] = (
+    int if typing.IsAssignable[E, Count[Any]] else Unwrap[typing.GetArg[E, Column, Literal[2]]]
+)
+
+
+# The underlying column of an item, unwrapping As then Count, and its owner table
+# (a Column's first argument). Used to check the column belongs to the FROM.
+type ColExpr[C] = (
+    typing.GetArg[ItemExpr[C], Count, Literal[0]]
+    if typing.IsAssignable[ItemExpr[C], Count[Any]]
+    else ItemExpr[C]
+)
+type OwnerOf[C] = typing.GetArg[ColExpr[C], Column, Literal[0]]
+
+
+# The two sides of a join source (only reached when Src is an InnerJoin).
+type JoinLeft[Src] = typing.GetArg[Src, InnerJoin, Literal[0]]
+type JoinRight[Src] = typing.GetArg[Src, InnerJoin, Literal[1]]
+
+
+# A Cols[...] projection over source Src -> the TypedDict of exactly the projected
+# items, in order. Each item's column must belong to a table in the FROM (Src is a
+# table, or an InnerJoin's two sides), else a type error.
+#
+# The scope check rides in the NAME slot: NewTypedDict forces every key, whereas
+# the value slot stays lazy on the static track (a RaiseError there never fires).
+# The membership boolean is written inline -- a helper alias in the if-slot would
+# be a truthy TypeAliasType, not a real bool (see [[ternary-laziness-is-load-bearing]]).
+# `and` short-circuits on both tracks, so the InnerJoin GetArgs are reached only
+# when Src actually is a join.
+type ProjectedRow[Src, P] = typing.NewTypedDict[
+    *[
+        typing.Member[
+            typing.RaiseError[Literal["Col: table is not in the FROM clause"]]
+            if not (
+                (
+                    typing.IsAssignable[Src, InnerJoin[Any, Any, *tuple[Any, ...]]]
+                    and (
+                        typing.IsAssignable[OwnerOf[c], JoinLeft[Src]]
+                        or typing.IsAssignable[OwnerOf[c], JoinRight[Src]]
+                    )
+                )
+                or (
+                    not typing.IsAssignable[Src, InnerJoin[Any, Any, *tuple[Any, ...]]]
+                    and typing.IsAssignable[OwnerOf[c], Src]
+                )
+            )
+            else ItemName[c],
+            ItemType[ItemExpr[c]],
+        ]
+        for c in typing.Iter[typing.GetArgs[P, Cols]]
+    ]
+]
+
+
+# --- WHERE parameters -------------------------------------------------------
+
+# A Where[...] clause -> the TypedDict of its parameters. Each predicate is an
+# Eq whose right-hand side is a Param[Literal[name], type]; a single comprehension
+# collects them (one conjunctive level, which is all the fork can flatten).
+type FlatParams[W] = typing.NewTypedDict[
+    *[
+        typing.Member[
+            typing.GetArg[typing.GetArg[pred, Eq, Literal[1]], Param, Literal[0]],
+            typing.GetArg[typing.GetArg[pred, Eq, Literal[1]], Param, Literal[1]],
+        ]
+        for pred in typing.Iter[typing.GetArgs[W, Where]]
+    ]
+]
+
+
+# --- SELECT dispatch --------------------------------------------------------
+
+# Result rows of a SELECT. With a lone source argument it is SELECT * (a full
+# ResultRow); otherwise the second argument is the Cols projection. Star vs
+# projection is decided by Length, not IsAssignable: the runtime evaluator
+# unifies variadic tails permissively, so IsAssignable alone cannot tell
+# Select[T] apart from Select[T, Cols[...]].
+type _SelectResult[S] = (
+    list[ResultRow[typing.GetArg[S, Select, Literal[0]]]]
+    if typing.IsEquivalent[typing.Length[typing.GetArgs[S, Select]], Literal[1]]
+    else list[
+        ProjectedRow[typing.GetArg[S, Select, Literal[0]], typing.GetArg[S, Select, Literal[1]]]
+    ]
+)
+
+
+# Parameters of a SELECT. A Where clause, when present, is the modifier right
+# after Cols (index 2). The Length guards keep the out-of-range index-2 lookup
+# from ever being evaluated when there is no such modifier (`and` short-circuits
+# on both tracks).
+type _SelectParams[S] = (
+    FlatParams[typing.GetArg[S, Select, Literal[2]]]
+    if (
+        not typing.IsEquivalent[typing.Length[typing.GetArgs[S, Select]], Literal[1]]
+        and not typing.IsEquivalent[typing.Length[typing.GetArgs[S, Select]], Literal[2]]
+        and typing.IsAssignable[typing.GetArg[S, Select, Literal[2]], Where[*tuple[Any, ...]]]
+    )
+    else None
+)
+
+
+# A carrier that pairs a statement's params with its result, so both facts are
+# written together on one branch instead of being spread across two ladders.
+class Spec[Params, Result]:
+    pass
+
+
+# fmt: off
+type SpecOf[S: Statement] = (
+    Spec[Row[typing.GetArg[S, Insert, Literal[0]]], int]
+    if typing.IsAssignable[S, Insert[Any, *tuple[Any, ...]]]
+
+    else Spec[_SelectParams[S], _SelectResult[S]]
+    if typing.IsAssignable[S, Select[Any, *tuple[Any, ...]]]
+
+    else Spec[None, None]
+    if typing.IsAssignable[S, CreateTable[Any]]
+
+    else typing.RaiseError[Literal["run: unsupported statement"]]
+)
+# fmt: on
+
+
+# ParamsOf and ResultOf are the two symmetric projections of that one ladder.
+type ParamsOf[S: Statement] = typing.GetArg[SpecOf[S], Spec, Literal[0]]
+type ResultOf[S: Statement] = typing.GetArg[SpecOf[S], Spec, Literal[1]]
+
+
+def run[S: Statement](stmt: type[S], data: ParamsOf[S]) -> ResultOf[S]:
+    """The typed contract of a statement: ``data`` in, rows out.
+
+    There is no database bridge yet, so this raises at runtime; its *signature*
+    is the product — ``ParamsOf[S]`` and ``ResultOf[S]`` are what a type checker
+    enforces at every call site. Use ``tysql.render.render`` for the SQL text.
+    """
+    raise NotImplementedError

tysql-0.1.0/src/tysql/statements.py

@@ -0,0 +1,100 @@
+"""The vocabulary of SQL statements, expressed as types.
+
+Every SQL statement is written as a *type*, not a value: ``Select[User]`` is a
+type whose structure a type checker can inspect. ``tysql.shapes`` turns that
+structure into the parameters a statement takes and the rows it returns;
+``tysql.render`` turns it into PostgreSQL text.
+
+The combinators below are deliberately close to SQL keywords so a query reads
+the way the SQL does:
+
+    Select[InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]],
+                                       Col[Post, Literal["author"]]]]],
+           Cols[Col[User, Literal["email"]], Col[Post, Literal["text"]]]]
+"""
+
+
+class Statement:
+    """Base type for a single SQL statement expressed as a value."""
+
+
+class CreateTable[T](Statement):
+    """``CREATE TABLE`` for the table type ``T``."""
+
+
+class Insert[T, *Mods](Statement):
+    """``INSERT INTO`` the table type ``T``."""
+
+
+class Select[Src, *Mods](Statement):
+    """``SELECT`` from ``Src`` (a table or a join), refined by ``*Mods``.
+
+    The modifiers appear in SQL order: an optional ``Cols`` projection, then an
+    optional ``Where``, ``GroupBy`` and ``OrderBy``. With no modifiers at all,
+    ``Select[User]`` means ``SELECT *``.
+    """
+
+
+# --- FROM sources -----------------------------------------------------------
+
+
+class InnerJoin[Left, Right, *Mods]:
+    """An ``INNER JOIN`` between two tables, usable as ``Select``'s source.
+
+    The join predicate is carried as an ``On`` modifier, e.g.
+    ``InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]],
+                                  Col[Post, Literal["author"]]]]]``.
+    """
+
+
+class On[Pred]:
+    """The ``ON`` predicate of a join."""
+
+
+# --- projection -------------------------------------------------------------
+
+
+class Cols[*Cs]:
+    """A ``SELECT`` projection: the ordered list of items to return.
+
+    Each item is a bare ``Col``, an ``As[item, Literal[alias]]`` rename, or an
+    aggregate such as ``Count``.
+    """
+
+
+class As[C, N]:
+    """Alias a projected item: the output key becomes ``N`` instead of the column name."""
+
+
+class Count[C]:
+    """The ``count(...)`` aggregate over column ``C``; its result type is ``int``."""
+
+
+# --- filtering --------------------------------------------------------------
+
+
+class Where[*Preds]:
+    """A ``WHERE`` clause: a conjunction (``AND``) of ``Eq`` predicates."""
+
+
+class Eq[L, R]:
+    """Equality between a column and another column or a ``Param``."""
+
+
+class Param[Name, T]:
+    """A bound parameter named ``Name`` carrying value type ``T``.
+
+    Every ``Param`` in a ``Where`` clause is collected into the parameter
+    mapping a statement expects (see ``tysql.shapes.ParamsOf``).
+    """
+
+
+# --- grouping / ordering ----------------------------------------------------
+
+
+class GroupBy[*Cs]:
+    """A ``GROUP BY`` over one or more columns."""
+
+
+class OrderBy[C, Dir]:
+    """An ``ORDER BY`` on column ``C`` with direction ``Dir`` (``"asc"``/``"desc"``)."""