tysql 0.1.0__tar.gz → 0.2.0__tar.gz

{tysql-0.1.0 → tysql-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tysql
-Version: 0.1.0
+Version: 0.2.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
@@ -18,15 +18,6 @@ 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
 
@@ -46,11 +37,11 @@ to make the *shape* of a query a static fact:
 
 ```python
 from typing import Literal
-from tysql import Col, Cols, PrimaryKey, Select, Table, run
+from tysql import Col, Cols, SerialPrimaryKey, Select, Table, run
 
 
 class User(Table):
-    id: PrimaryKey[int]
+    id: SerialPrimaryKey[int]
     age: int
     email: str
 
@@ -74,6 +65,22 @@ 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).
 
+## Install
+
+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`
+```
+
+The [`mypy` fork](https://github.com/iliyasone/mypy-typemap) is only needed for
+`tysql check` (see [CLI](#cli)); it cannot ship as a PyPI extra (direct URL), so
+it is installed from GitHub. Runnable demo snippets ship inside the package under
+[`tysql/examples/`](src/tysql/examples).
+
 ## What works
 
 Type inference below holds on **both** tracks (the `mypy` fork *and* runtime
@@ -83,7 +90,7 @@ Type inference below holds on **both** tracks (the `mypy` fork *and* runtime
 | --- | :---: | :---: |
 | `CREATE TABLE` (incl. `SERIAL PRIMARY KEY`, `REFERENCES`) | — | ✅ |
 | `INSERT` — params inferred, `RETURNING` the primary key | ✅ | ✅ |
-| `SELECT *` — full row, primary key unwrapped (`PrimaryKey[int]` → `int`) | ✅ | ✅ |
+| `SELECT *` — full row, primary key unwrapped (`SerialPrimaryKey[int]` → `int`) | ✅ | ✅ |
 | `SELECT` projection — `Cols[...]` picks columns | ✅ | ✅ |
 | Column alias — `As[col, Literal["name"]]` | ✅ | ✅ |
 | `WHERE` — `Param`s collected into the inferred parameter mapping | ✅ | ✅ |
@@ -163,7 +170,8 @@ 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).
+A larger example schema lives in [`src/tysql/examples/users.py`](src/tysql/examples/users.py),
+alongside the numbered demo snippets the [playground](https://github.com/iliyasone/tysql-playground) serves.
 
 ## CLI
 

{tysql-0.1.0 → tysql-0.2.0}/README.md

@@ -1,14 +1,5 @@
 # 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
 
@@ -28,11 +19,11 @@ to make the *shape* of a query a static fact:
 
 ```python
 from typing import Literal
-from tysql import Col, Cols, PrimaryKey, Select, Table, run
+from tysql import Col, Cols, SerialPrimaryKey, Select, Table, run
 
 
 class User(Table):
-    id: PrimaryKey[int]
+    id: SerialPrimaryKey[int]
     age: int
     email: str
 
@@ -56,6 +47,22 @@ 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).
 
+## Install
+
+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`
+```
+
+The [`mypy` fork](https://github.com/iliyasone/mypy-typemap) is only needed for
+`tysql check` (see [CLI](#cli)); it cannot ship as a PyPI extra (direct URL), so
+it is installed from GitHub. Runnable demo snippets ship inside the package under
+[`tysql/examples/`](src/tysql/examples).
+
 ## What works
 
 Type inference below holds on **both** tracks (the `mypy` fork *and* runtime
@@ -65,7 +72,7 @@ Type inference below holds on **both** tracks (the `mypy` fork *and* runtime
 | --- | :---: | :---: |
 | `CREATE TABLE` (incl. `SERIAL PRIMARY KEY`, `REFERENCES`) | — | ✅ |
 | `INSERT` — params inferred, `RETURNING` the primary key | ✅ | ✅ |
-| `SELECT *` — full row, primary key unwrapped (`PrimaryKey[int]` → `int`) | ✅ | ✅ |
+| `SELECT *` — full row, primary key unwrapped (`SerialPrimaryKey[int]` → `int`) | ✅ | ✅ |
 | `SELECT` projection — `Cols[...]` picks columns | ✅ | ✅ |
 | Column alias — `As[col, Literal["name"]]` | ✅ | ✅ |
 | `WHERE` — `Param`s collected into the inferred parameter mapping | ✅ | ✅ |
@@ -145,7 +152,8 @@ 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).
+A larger example schema lives in [`src/tysql/examples/users.py`](src/tysql/examples/users.py),
+alongside the numbered demo snippets the [playground](https://github.com/iliyasone/tysql-playground) serves.
 
 ## CLI
 

{tysql-0.1.0 → tysql-0.2.0}/pyproject.toml

@@ -19,7 +19,7 @@ license = {text = "MIT"}
 name = "tysql"
 readme = "README.md"
 requires-python = ">=3.14"
-version = "0.1.0"
+version = "0.2.0"
 
 [project.scripts]
 tysql = "tysql.cli:main"
@@ -46,6 +46,10 @@ test = [
 
 [tool.mypy]
 enable_error_code = ["ignore-without-code"]
+# The bundled examples are standalone demo snippets — some carry deliberate type
+# errors (a typo'd column, an out-of-scope reference) that are the point of the
+# example. They ship in the wheel but are not part of this repo's type contract.
+exclude = ["src/tysql/examples/", "scratch/"]
 python_version = "3.14"
 show_error_codes = true
 warn_unused_ignores = true
@@ -58,6 +62,7 @@ python_functions = ["test_*"]
 testpaths = ["tests"]
 
 [tool.ruff]
+extend-exclude = ["src/tysql/examples"]
 line-length = 100
 target-version = "py314"
 

{tysql-0.1.0 → tysql-0.2.0}/src/tysql/__init__.py

@@ -5,7 +5,7 @@ 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.schema import Col, Column, ForeignKey, PrimaryKey, SerialPrimaryKey, Table
 from tysql.shapes import ParamsOf, ResultOf, run
 from tysql.statements import (
     As,
@@ -43,6 +43,7 @@ __all__ = [
     "PrimaryKey",
     "ResultOf",
     "Select",
+    "SerialPrimaryKey",
     "Statement",
     "Table",
     "Where",

tysql-0.2.0/src/tysql/examples/1_dual_track.py

@@ -0,0 +1,40 @@
+# Paired tests — pytest × mypy, the dual-track setup this playground runs on.
+# One feature, two adjacent tests. mypy_test_* is static-only (assert_type
+# positives, type-ignore negatives kept honest by --warn-unused-ignores);
+# test_* is runtime (pytest + eval_typing). ⌘/Ctrl+Enter runs both suites at
+# once — Check type-checks with the PEP 827 mypy fork, Test runs pytest here in
+# your browser. That both agree is the whole point of the prototype.
+
+from typing import TYPE_CHECKING, Literal, assert_type
+
+import typemap_extensions as tm
+from typemap.type_eval import eval_typing
+
+
+class Point:
+    x: int
+    y: float
+
+
+# A TypedDict computed from Point's annotations, names uppercased at the type level.
+type Loud = tm.NewTypedDict[
+    *[tm.Member[tm.Uppercase[a.name], a.type] for a in tm.Iter[tm.Attrs[Point]]]
+]
+
+
+def mypy_test_loud_keys() -> None:  # static: mypy checks it, pytest skips it
+    if TYPE_CHECKING:
+        p: Loud = {"X": 1, "Y": 2.0}
+        assert_type(p["X"], int)
+        assert_type(p["Y"], float)
+        p["x"]  # type: ignore[misc]  # negative: the lowercase key must be rejected
+
+
+def test_loud_keys() -> None:  # runtime: pytest checks the evaluated class
+    D = eval_typing(Loud)
+    assert D.__annotations__ == {"X": int, "Y": float}
+    assert D.__required_keys__ == frozenset({"X", "Y"})
+
+
+def test_uppercase() -> None:
+    assert eval_typing(tm.Uppercase[Literal["pep 827"]]) == Literal["PEP 827"]

tysql-0.2.0/src/tysql/examples/2_select.py

@@ -0,0 +1,24 @@
+# SELECT & projection — a statement is a type.
+# Projected columns become the row type; reading any other column is a type error.
+
+from typing import TYPE_CHECKING, Literal
+
+from tysql import Col, Cols, PrimaryKey, Select, Table, run
+from tysql.render import render
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+stmt = Select[User, Cols[Col[User, Literal["id"]], Col[User, Literal["email"]]]]
+
+print(render(stmt))  # Run renders the SQL — right in your browser
+
+if TYPE_CHECKING:  # run() is the static contract; there is no database bridge yet
+    rows = run(stmt, data=None)
+    reveal_type(rows[0]["id"])     # int — inferred
+    reveal_type(rows[0]["email"])  # str — inferred
+    rows[0]["age"]  # error: "age" was not selected

tysql-0.2.0/src/tysql/examples/3_typo.py

@@ -0,0 +1,23 @@
+# Catch a typo — a column that does not exist is rejected at the reference site.
+# Run still renders the broken SQL: only the type checker stands between this
+# statement and your database.
+
+from typing import TYPE_CHECKING, Literal
+
+from tysql import Col, Cols, PrimaryKey, Select, Table, run
+from tysql.render import render
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+# "emial" is not a column of User — the statement itself is ill-typed
+stmt = Select[User, Cols[Col[User, Literal["emial"]]]]
+
+print(render(stmt))  # runtime happily renders SELECT "user"."emial" …
+
+if TYPE_CHECKING:
+    rows = run(stmt, data=None)  # error: Col: no such column

tysql-0.2.0/src/tysql/examples/4_where.py

@@ -0,0 +1,26 @@
+# WHERE & inferred params — params in the WHERE clause become required, typed
+# keys of data=. A wrong value type is rejected.
+
+from typing import TYPE_CHECKING, Literal
+
+from tysql import Col, Cols, Eq, Param, PrimaryKey, Select, Table, Where, run
+from tysql.render import render
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+stmt = Select[
+    User,
+    Cols[Col[User, Literal["id"]]],
+    Where[Eq[Col[User, Literal["age"]], Param[Literal["min_age"], int]]],
+]
+
+print(render(stmt))  # SELECT … WHERE "user"."age" = %(min_age)s
+
+if TYPE_CHECKING:  # the params of run() are inferred from the statement
+    run(stmt, data={"min_age": 21})    # ok
+    run(stmt, data={"min_age": "21"})  # error: "min_age" must be int

tysql-0.2.0/src/tysql/examples/5_join.py

@@ -0,0 +1,38 @@
+# JOIN, COUNT & GROUP BY — an INNER JOIN with an ON predicate, a Count aggregate
+# under an alias, GROUP BY and ORDER BY. The row type is computed through all of it.
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Literal
+
+from tysql import (
+    As, Col, Cols, Count, Eq, ForeignKey, GroupBy, InnerJoin, On, OrderBy,
+    PrimaryKey, Select, Table, run,
+)
+from tysql.render import render
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+class Post(Table):
+    id: PrimaryKey[int]
+    author: ForeignKey[User, Literal["id"]]
+    created_at: datetime
+    text: str
+
+
+stmt = 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"]],
+]
+
+print(render(stmt))
+
+if TYPE_CHECKING:
+    rows = run(stmt, data=None)
+    reveal_type(rows[0]["n_posts"])  # int

tysql-0.2.0/src/tysql/examples/6_scope.py

@@ -0,0 +1,30 @@
+# Column out of scope — projecting a column whose table is not in the FROM/JOIN
+# clause is caught; the column is mapped back to its table.
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Literal
+
+from tysql import Col, Cols, ForeignKey, PrimaryKey, Select, Table, run
+from tysql.render import render
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+class Post(Table):
+    id: PrimaryKey[int]
+    author: ForeignKey[User, Literal["id"]]
+    created_at: datetime
+    text: str
+
+
+# Post.text is a real column — but Post is not in the FROM clause
+stmt = Select[User, Cols[Col[Post, Literal["text"]]]]
+
+print(render(stmt))  # runtime renders SQL that selects from the wrong table
+
+if TYPE_CHECKING:
+    rows = run(stmt, data=None)  # error: Col: table is not in the FROM clause

tysql-0.2.0/src/tysql/examples/7_lazy_load.py

@@ -0,0 +1,58 @@
+# The lazy-load lie — what tysql fixes about ORMs.
+#
+# SQLAlchemy (for contrast, not runnable here):
+#     post = session.scalars(select(Post).where(Post.id == 1)).one()
+#     reveal_type(post.author.posts[0].text)  # str — a whole object graph
+# ...yet select(Post) loaded ONE row; every "." past `post` is a hidden query or
+# an error on a closed session. The type promises data the query never loaded.
+#
+# In tysql the result TYPE is the load plan: a statement returns a flat row of
+# exactly the columns it selected. What you did not load, you cannot name.
+
+from typing import TYPE_CHECKING, Literal
+
+from tysql import (
+    Col, Cols, Eq, ForeignKey, InnerJoin, On, Param, PrimaryKey, Select, Table, Where, run,
+)
+from tysql.render import render
+
+
+class User(Table):
+    id: PrimaryKey[int]
+    age: int
+    email: str
+
+
+class Post(Table):
+    id: PrimaryKey[int]
+    author: ForeignKey[User, Literal["id"]]
+    text: str
+
+
+# You selected Post's own columns — so that is exactly the row you get back.
+post_only = Select[
+    Post,
+    Cols[Col[Post, Literal["id"]], Col[Post, Literal["author"]], Col[Post, Literal["text"]]],
+    Where[Eq[Col[Post, Literal["id"]], Param[Literal["id"], int]]],
+]
+
+print(render(post_only))
+
+if TYPE_CHECKING:
+    row = run(post_only, data={"id": 1})[0]
+    reveal_type(row["text"])    # str
+    reveal_type(row["author"])  # the raw foreign key — NOT a hydrated User object
+    row["email"]  # error: the user was never loaded — "email" is not on this row
+
+# Want the user's columns? Load them, explicitly, with a join. Only now do they
+# appear on the row type — because the join is what put them there.
+with_author = Select[
+    InnerJoin[User, Post, On[Eq[Col[User, Literal["id"]], Col[Post, Literal["author"]]]]],
+    Cols[Col[Post, Literal["text"]], Col[User, Literal["email"]]],
+]
+
+print(render(with_author))
+
+if TYPE_CHECKING:
+    joined = run(with_author, data=None)[0]
+    reveal_type(joined["email"])  # str — present now, and only now

tysql-0.2.0/src/tysql/examples/8_pep827.py

@@ -0,0 +1,28 @@
+# Pure PEP 827 — no tysql: compute types from types.
+# Check evaluates this statically with the mypy fork; Run evaluates the very same
+# program with typemap at runtime, in your browser.
+
+from typing import Literal
+
+import typemap_extensions as tm
+from typemap.type_eval import eval_typing
+
+
+class Point:
+    x: int
+    y: float
+
+
+# A TypedDict computed from Point's annotations — names uppercased at the type level
+Loud = tm.NewTypedDict[
+    *[tm.Member[tm.Uppercase[a.name], a.type] for a in tm.Iter[tm.Attrs[Point]]]
+]
+
+
+def f(p: Loud) -> None:
+    reveal_type(p["X"])  # int — computed statically
+    reveal_type(p["Y"])  # float
+    p["x"]               # error: the key is "X" now
+
+
+print(eval_typing(tm.Uppercase[Literal["pep 827"]]))  # the same machinery, at runtime

tysql-0.2.0/src/tysql/examples/99_if_order_dependency.py

@@ -0,0 +1,53 @@
+# Order-dependent caching — a cursed corner where evaluation order leaks.
+# Two identical functions resolve their type-level `if` to DIFFERENT annotations
+# depending on which evaluator touches them first: the typemap-aware and
+# typemap-naive lookups share one cache, so whoever runs first wins. mypy
+# evaluates the `if` correctly; the runtime tracks disagree by construction.
+
+from typing import TYPE_CHECKING, Literal, assert_type
+
+import typemap_extensions as typing
+from typemap.type_eval import eval_call_with_types, eval_typing
+
+
+def foo() -> int if typing.Bool[Literal[True]] else Literal["UNREACHABLE"]:
+    raise NotImplementedError
+
+
+def bar() -> int if typing.Bool[Literal[True]] else Literal["UNREACHABLE"]:
+    raise NotImplementedError
+
+
+# identical functions
+
+
+def mypy_flow() -> None:
+    if TYPE_CHECKING:
+        assert_type(foo(), int)
+        assert_type(bar(), int)
+        # ✅ mypy evaluates `if` correctly
+
+
+def test_foo() -> None:
+    assert foo.__annotations__["return"] == Literal["UNREACHABLE"]
+    # ✅ typemap-unaware annotations lookup: `typing.Bool[...]` resolves to False
+    # (expected for a naive evaluator)
+
+    assert eval_typing(foo).__annotations__["return"] == Literal["UNREACHABLE"]
+    # ⚠️ typemap-aware evaluator resolved to the incorrect cache instead of reducing
+
+    assert eval_call_with_types(foo) is int
+    # ✅ eval_call_with_types does not use the cache (bug?)
+
+
+def test_bar() -> None:
+    assert eval_typing(bar).__annotations__["return"] is int
+    # ✅ typemap-aware evaluator ran first — correct type put in the cache
+
+    assert bar.__annotations__["return"] is int
+    # ⚠️ typemap-unaware lookup used the cached typemap-aware value
+
+
+if __name__ == "__main__":
+    print(f"{foo.__annotations__=}")
+    print(f"{bar.__annotations__=}")

tysql-0.2.0/src/tysql/examples/__init__.py

@@ -0,0 +1,8 @@
+"""Bundled tysql examples.
+
+Each ``*.py`` sibling is a self-contained snippet demonstrating one feature. The
+files ship in the wheel so tools (e.g. the playground) can read them straight
+from the installed package with ``importlib.resources.files("tysql.examples")``.
+The digit prefix orders them; the first ``# Title — blurb`` comment line is the
+display title.
+"""

tysql-0.2.0/src/tysql/examples/users.py

@@ -0,0 +1,40 @@
+"""A small social-graph schema used across the tests and the README examples."""
+
+from datetime import datetime
+from typing import Literal
+
+from tysql.schema import ForeignKey, SerialPrimaryKey, Table
+
+
+class User(Table):
+    id: SerialPrimaryKey[int]
+    age: int
+    email: str
+
+
+class Post(Table):
+    id: SerialPrimaryKey[int]
+    author: ForeignKey[User, Literal["id"]]
+    created_at: datetime
+    text: str
+
+
+class Comment(Table):
+    id: SerialPrimaryKey[int]
+    author: ForeignKey[User, Literal["id"]]
+    post: ForeignKey[Post, Literal["id"]]
+    created_at: datetime
+    text: str
+
+
+class Follow(Table):
+    follower: ForeignKey[User, Literal["id"]]
+    followed: ForeignKey[User, Literal["id"]]
+    created_at: datetime
+
+
+class Reaction(Table):
+    user: ForeignKey[User, Literal["id"]]
+    post: ForeignKey[Post, Literal["id"]]
+    kind: str
+    created_at: datetime

{tysql-0.1.0 → tysql-0.2.0}/src/tysql/render.py

@@ -11,7 +11,7 @@ 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.schema import Column, ForeignKey, PrimaryKey, SerialPrimaryKey
 from tysql.statements import (
     As,
     Cols,
@@ -127,14 +127,24 @@ def _columns(table: type) -> list[Column[Any, Any, Any]]:
     return list(table.__tysql_columns__.values())  # type: ignore[attr-defined]
 
 
+_PRIMARY_KEY_NOT_IMPLEMENTED = (
+    "render: PrimaryKey (general, non-serial primary key) is not implemented "
+    "yet -- use SerialPrimaryKey instead."
+)
+
+
 def _is_primary_key(annotation: Any) -> bool:
-    return get_origin(annotation) is PrimaryKey
+    if get_origin(annotation) is PrimaryKey:
+        raise NotImplementedError(_PRIMARY_KEY_NOT_IMPLEMENTED)
+    return get_origin(annotation) is SerialPrimaryKey
 
 
 def _column_ddl(column: Column[Any, Any, Any]) -> str:
     annotation = column.type
     origin = get_origin(annotation)
     if origin is PrimaryKey:
+        raise NotImplementedError(_PRIMARY_KEY_NOT_IMPLEMENTED)
+    if origin is SerialPrimaryKey:
         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}"
@@ -143,6 +153,8 @@ def _column_ddl(column: Column[Any, Any, Any]) -> str:
         name = _literal(name_literal)
         referenced = ref.__tysql_columns__[name].type
         if get_origin(referenced) is PrimaryKey:
+            raise NotImplementedError(_PRIMARY_KEY_NOT_IMPLEMENTED)
+        if get_origin(referenced) is SerialPrimaryKey:
             referenced = get_args(referenced)[0]
         return (
             f"{_ident(column.name)} {_base_pg_type(referenced)} NOT NULL "

{tysql-0.1.0 → tysql-0.2.0}/src/tysql/schema.py

@@ -51,10 +51,14 @@ type Col[C, N] = (
 )
 
 
-class PrimaryKey[T]:
+class SerialPrimaryKey[T]:
     """Marks a column as the table's primary key; unwrapped to ``T`` in results."""
 
 
+class PrimaryKey[T]:
+    """General (non-serial) PRIMARY KEY. Not implemented yet — use SerialPrimaryKey."""
+
+
 class ForeignKey[Owner, Name]:
     """A foreign key referencing ``Owner``'s column ``Name``.
 

{tysql-0.1.0 → tysql-0.2.0}/src/tysql/shapes.py

@@ -14,7 +14,7 @@ these are written:
 import sys
 from typing import Any, Literal
 
-from tysql.schema import Column, PrimaryKey
+from tysql.schema import Column, SerialPrimaryKey
 from tysql.statements import (
     As,
     Cols,
@@ -42,15 +42,17 @@ 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]]]
+        if not typing.IsAssignable[x.type, Column[Any, Any, SerialPrimaryKey[Any]]]
     ]
 ]
 
 
-# A column's value as it comes back from a query: PrimaryKey[int] -> int,
+# A column's value as it comes back from a query: SerialPrimaryKey[int] -> int,
 # anything else unchanged.
 type Unwrap[T] = (
-    typing.GetArg[T, PrimaryKey, Literal[0]] if typing.IsAssignable[T, PrimaryKey[Any]] else T
+    typing.GetArg[T, SerialPrimaryKey, Literal[0]]
+    if typing.IsAssignable[T, SerialPrimaryKey[Any]]
+    else T
 )