sqlty 0.0.1.dev1__tar.gz → 0.2.0__tar.gz

sqlty-0.2.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: sqlty
+Version: 0.2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: typing-extensions>=4.15.0 ; python_full_version < '3.15'
+Requires-Dist: psycopg>=3.2.12 ; extra == 'psycopg'
+Provides-Extra: psycopg
+License-File: LICENSE
+Summary: Type-safe SQL queries for Python
+Keywords: sql,type-hints,mypy,type-safety,static-analysis,code-generation
+Author-email: Jiri Kuncar <jiri.kuncar@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/jirikuncar/sqlty/releases
+Project-URL: Documentation, https://jirikuncar.github.io/sqlty/
+Project-URL: Homepage, https://github.com/jirikuncar/sqlty
+Project-URL: Issues, https://github.com/jirikuncar/sqlty/issues
+Project-URL: Repository, https://github.com/jirikuncar/sqlty
+
+# SQLTy
+
+[![PyPI](https://img.shields.io/pypi/v/sqlty.svg)](https://pypi.org/project/sqlty/)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://github.com/jirikuncar/sqlty/actions/workflows/tests.yml/badge.svg)](https://github.com/jirikuncar/sqlty/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Your SQL already knows its types. SQLTy tells Python.
+
+Type-safe raw SQL without an ORM or a database connection. sqlty reads row and
+parameter types from your SQL and schema, and checks them on every commit, so a
+migration that changes a column is caught in review, not in production.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jirikuncar/sqlty/main/docs/assets/demo.gif" alt="A terminal session: sqlty rewrite adds the row type to a query, a migration makes email nullable, sqlty check --fix updates the type and mypy reports the line that would crash" width="720">
+  <br>
+  <em>A migration makes <code>email</code> nullable. sqlty and mypy find the code that would crash.</em>
+  (<a href="https://github.com/jirikuncar/sqlty/blob/main/docs/assets/demo.tape">view source</a>)
+</p>
+
+**Documentation: [jirikuncar.github.io/sqlty](https://jirikuncar.github.io/sqlty/)**
+
+**Fits if** you write SQL as string literals on Python 3.14+, against
+PostgreSQL, SQLite or MySQL, with a schema dump or SQL migrations in the
+repository. Rows are typed end to end with psycopg 3; with other drivers sqlty
+checks the query and its parameters, and you annotate what the cursor returns
+([Drivers](https://jirikuncar.github.io/sqlty/guide/drivers-and-orms/)).
+
+> **Beta.** APIs and configuration may change before 1.0. Feedback welcome in
+> [GitHub Issues](https://github.com/jirikuncar/sqlty/issues).
+
+## How it works
+
+Drivers return rows of `Any`, so nothing ties a query's columns to the code
+that reads them. Start a query with `--sql` and a newline, and
+`sqlty rewrite .` adds the row type inferred from your `CREATE TABLE`
+statements:
+
+```toml
+# pyproject.toml
+[tool.sqlty]
+schema = "schema.sql"
+```
+
+`schema.sql`:
+
+```sql
+CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email VARCHAR(255) NOT NULL);
+```
+
+```python
+query = "--sql\nSELECT id, name, email FROM users"
+# rewritten: query = SQL[tuple[int, str, str]]("--sql\nSELECT id, name, email FROM users")
+```
+
+`SQL[T]` is a `str` subclass, so the query still runs anywhere a string does,
+and mypy, pyright and ty see `T`. Without a schema, casts such as `id::INTEGER`
+type the columns; a query with neither stays as it is. With a space instead of
+the newline, `"--sql SELECT ..."` is a SQL comment, and `sqlty check` warns.
+
+## What it catches
+
+### A migration changes a column
+
+```toml
+[tool.sqlty]
+schema = "schema.sql"
+```
+
+A migration dropped `NOT NULL` from `email`.
+
+`schema.sql`:
+
+```sql
+CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT);
+```
+
+```python
+from sqlty import SQL
+
+# error: [narrow-type] "SQL[tuple[int, str]] should be SQL[tuple[int, str | None]]"
+query = SQL[tuple[int, str]]("--sql\nSELECT id, email FROM users")
+```
+
+`sqlty check --fix .` updates the type, and your type checker finds every
+caller that now needs a `None` check. `narrow-type` is an error, so CI fails on
+it; an annotation that is only wider than the rows, such as `str | None` for a
+column made `NOT NULL`, is a `stale-type` warning
+([CI](https://jirikuncar.github.io/sqlty/recipes/ci/)). For rolling deploys,
+`sqlty breaking --against origin/main` exits 1 when old code breaks on the new
+schema or new code on the old one
+([Breaking schema changes](https://jirikuncar.github.io/sqlty/guide/breaking-changes/)).
+
+### A row type that doesn't match its query
+
+```python
+from typing import TypedDict
+from sqlty import SQL
+
+class User(TypedDict):
+    id: str
+    name: str
+
+# error: [column-type-mismatch] "User.id is str but query column 'id' infers int"
+query = SQL[User]("--sql\nSELECT id::INTEGER, name::TEXT FROM users")
+```
+
+`TypedDict`, `NamedTuple`, dataclasses and Pydantic models are all checked
+([Row types](https://jirikuncar.github.io/sqlty/guide/row-types/)).
+
+### Wrong parameters, misspelled columns
+
+```toml
+[tool.sqlty]
+dialect = "sqlite"
+schema = "schema.sql"
+
+[tool.sqlty.rules]
+unknown-column = "warn"
+```
+
+`schema.sql`:
+
+```sql
+CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT);
+```
+
+```python
+import sqlite3
+from sqlty import SQL
+
+conn = sqlite3.connect("app.db")
+
+# error: [param-count-mismatch] "query has 1 parameter, the call passes 2"
+conn.execute(SQL[tuple[str | None]]("--sql\nSELECT email FROM users WHERE id = ?"), (1, 2))
+
+# error: [unknown-column] "column `emial` does not exist in `users`"
+conn.execute("--sql\nSELECT emial FROM users")
+```
+
+`?`, `$1`, `%s` and `:name` placeholders are checked on sqlite3, psycopg and
+asyncpg calls ([Parameters](https://jirikuncar.github.io/sqlty/guide/parameters/)).
+These are the mistakes coding agents make: every problem is one
+`file:line: [rule] message` line and a non-zero exit code they can act on, and
+the [sqlty skills](https://jirikuncar.github.io/sqlty/recipes/agents/) teach
+them the conventions. In Claude Code, `/plugin install sqlty --marketplace jirikuncar/sqlty`
+installs them.
+
+## Get started
+
+```bash
+pip install "sqlty[psycopg]"   # or: uv add sqlty; the extra adds the psycopg helpers
+printf '%s\n' 'q = "--sql\nSELECT id::INTEGER, name::TEXT FROM users"' > queries.py
+sqlty rewrite -v .             # q = SQL[tuple[int, str]]("--sql\n...")
+sqlty check .                  # report drift and mismatches
+sqlty strip .                  # undo: back to plain strings
+```
+
+`rewrite` and `strip` only touch the wrapper, never the SQL, so you can adopt
+sqlty one module at a time and back out. New project:
+[Quickstart](https://jirikuncar.github.io/sqlty/quickstart/). Existing codebase:
+[Migration](https://jirikuncar.github.io/sqlty/recipes/migration/), starting
+with `pg_dump --schema-only app > schema.sql`.
+
+Not a fit for ORMs, SQL built at runtime, or runtime validation;
+[Why SQLTy?](https://jirikuncar.github.io/sqlty/motivation/) compares it with
+sqlc, sqlx, PgTyped and others.
+
+## About
+
+The engine is Rust ([sqlparser-rs](https://github.com/apache/datafusion-sqlparser-rs)
+via [PyO3](https://pyo3.rs)), with wheels for Linux, macOS and Windows. SQLTy is
+developed with AI coding agents, mainly Claude Code; every change is reviewed by
+a maintainer (see the
+[AI-assisted contributions](https://github.com/jirikuncar/sqlty/blob/main/CONTRIBUTING.md#ai-assisted-contributions)
+policy). [Contributing](https://github.com/jirikuncar/sqlty/blob/main/CONTRIBUTING.md) ·
+[Credits](https://jirikuncar.github.io/sqlty/credits/) ·
+MIT [License](https://github.com/jirikuncar/sqlty/blob/main/LICENSE).
+

sqlty-0.2.0/README.md

@@ -0,0 +1,178 @@
+# SQLTy
+
+[![PyPI](https://img.shields.io/pypi/v/sqlty.svg)](https://pypi.org/project/sqlty/)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://github.com/jirikuncar/sqlty/actions/workflows/tests.yml/badge.svg)](https://github.com/jirikuncar/sqlty/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Your SQL already knows its types. SQLTy tells Python.
+
+Type-safe raw SQL without an ORM or a database connection. sqlty reads row and
+parameter types from your SQL and schema, and checks them on every commit, so a
+migration that changes a column is caught in review, not in production.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jirikuncar/sqlty/main/docs/assets/demo.gif" alt="A terminal session: sqlty rewrite adds the row type to a query, a migration makes email nullable, sqlty check --fix updates the type and mypy reports the line that would crash" width="720">
+  <br>
+  <em>A migration makes <code>email</code> nullable. sqlty and mypy find the code that would crash.</em>
+  (<a href="https://github.com/jirikuncar/sqlty/blob/main/docs/assets/demo.tape">view source</a>)
+</p>
+
+**Documentation: [jirikuncar.github.io/sqlty](https://jirikuncar.github.io/sqlty/)**
+
+**Fits if** you write SQL as string literals on Python 3.14+, against
+PostgreSQL, SQLite or MySQL, with a schema dump or SQL migrations in the
+repository. Rows are typed end to end with psycopg 3; with other drivers sqlty
+checks the query and its parameters, and you annotate what the cursor returns
+([Drivers](https://jirikuncar.github.io/sqlty/guide/drivers-and-orms/)).
+
+> **Beta.** APIs and configuration may change before 1.0. Feedback welcome in
+> [GitHub Issues](https://github.com/jirikuncar/sqlty/issues).
+
+## How it works
+
+Drivers return rows of `Any`, so nothing ties a query's columns to the code
+that reads them. Start a query with `--sql` and a newline, and
+`sqlty rewrite .` adds the row type inferred from your `CREATE TABLE`
+statements:
+
+```toml
+# pyproject.toml
+[tool.sqlty]
+schema = "schema.sql"
+```
+
+`schema.sql`:
+
+```sql
+CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email VARCHAR(255) NOT NULL);
+```
+
+```python
+query = "--sql\nSELECT id, name, email FROM users"
+# rewritten: query = SQL[tuple[int, str, str]]("--sql\nSELECT id, name, email FROM users")
+```
+
+`SQL[T]` is a `str` subclass, so the query still runs anywhere a string does,
+and mypy, pyright and ty see `T`. Without a schema, casts such as `id::INTEGER`
+type the columns; a query with neither stays as it is. With a space instead of
+the newline, `"--sql SELECT ..."` is a SQL comment, and `sqlty check` warns.
+
+## What it catches
+
+### A migration changes a column
+
+```toml
+[tool.sqlty]
+schema = "schema.sql"
+```
+
+A migration dropped `NOT NULL` from `email`.
+
+`schema.sql`:
+
+```sql
+CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT);
+```
+
+```python
+from sqlty import SQL
+
+# error: [narrow-type] "SQL[tuple[int, str]] should be SQL[tuple[int, str | None]]"
+query = SQL[tuple[int, str]]("--sql\nSELECT id, email FROM users")
+```
+
+`sqlty check --fix .` updates the type, and your type checker finds every
+caller that now needs a `None` check. `narrow-type` is an error, so CI fails on
+it; an annotation that is only wider than the rows, such as `str | None` for a
+column made `NOT NULL`, is a `stale-type` warning
+([CI](https://jirikuncar.github.io/sqlty/recipes/ci/)). For rolling deploys,
+`sqlty breaking --against origin/main` exits 1 when old code breaks on the new
+schema or new code on the old one
+([Breaking schema changes](https://jirikuncar.github.io/sqlty/guide/breaking-changes/)).
+
+### A row type that doesn't match its query
+
+```python
+from typing import TypedDict
+from sqlty import SQL
+
+class User(TypedDict):
+    id: str
+    name: str
+
+# error: [column-type-mismatch] "User.id is str but query column 'id' infers int"
+query = SQL[User]("--sql\nSELECT id::INTEGER, name::TEXT FROM users")
+```
+
+`TypedDict`, `NamedTuple`, dataclasses and Pydantic models are all checked
+([Row types](https://jirikuncar.github.io/sqlty/guide/row-types/)).
+
+### Wrong parameters, misspelled columns
+
+```toml
+[tool.sqlty]
+dialect = "sqlite"
+schema = "schema.sql"
+
+[tool.sqlty.rules]
+unknown-column = "warn"
+```
+
+`schema.sql`:
+
+```sql
+CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT);
+```
+
+```python
+import sqlite3
+from sqlty import SQL
+
+conn = sqlite3.connect("app.db")
+
+# error: [param-count-mismatch] "query has 1 parameter, the call passes 2"
+conn.execute(SQL[tuple[str | None]]("--sql\nSELECT email FROM users WHERE id = ?"), (1, 2))
+
+# error: [unknown-column] "column `emial` does not exist in `users`"
+conn.execute("--sql\nSELECT emial FROM users")
+```
+
+`?`, `$1`, `%s` and `:name` placeholders are checked on sqlite3, psycopg and
+asyncpg calls ([Parameters](https://jirikuncar.github.io/sqlty/guide/parameters/)).
+These are the mistakes coding agents make: every problem is one
+`file:line: [rule] message` line and a non-zero exit code they can act on, and
+the [sqlty skills](https://jirikuncar.github.io/sqlty/recipes/agents/) teach
+them the conventions. In Claude Code, `/plugin install sqlty --marketplace jirikuncar/sqlty`
+installs them.
+
+## Get started
+
+```bash
+pip install "sqlty[psycopg]"   # or: uv add sqlty; the extra adds the psycopg helpers
+printf '%s\n' 'q = "--sql\nSELECT id::INTEGER, name::TEXT FROM users"' > queries.py
+sqlty rewrite -v .             # q = SQL[tuple[int, str]]("--sql\n...")
+sqlty check .                  # report drift and mismatches
+sqlty strip .                  # undo: back to plain strings
+```
+
+`rewrite` and `strip` only touch the wrapper, never the SQL, so you can adopt
+sqlty one module at a time and back out. New project:
+[Quickstart](https://jirikuncar.github.io/sqlty/quickstart/). Existing codebase:
+[Migration](https://jirikuncar.github.io/sqlty/recipes/migration/), starting
+with `pg_dump --schema-only app > schema.sql`.
+
+Not a fit for ORMs, SQL built at runtime, or runtime validation;
+[Why SQLTy?](https://jirikuncar.github.io/sqlty/motivation/) compares it with
+sqlc, sqlx, PgTyped and others.
+
+## About
+
+The engine is Rust ([sqlparser-rs](https://github.com/apache/datafusion-sqlparser-rs)
+via [PyO3](https://pyo3.rs)), with wheels for Linux, macOS and Windows. SQLTy is
+developed with AI coding agents, mainly Claude Code; every change is reviewed by
+a maintainer (see the
+[AI-assisted contributions](https://github.com/jirikuncar/sqlty/blob/main/CONTRIBUTING.md#ai-assisted-contributions)
+policy). [Contributing](https://github.com/jirikuncar/sqlty/blob/main/CONTRIBUTING.md) ·
+[Credits](https://jirikuncar.github.io/sqlty/credits/) ·
+MIT [License](https://github.com/jirikuncar/sqlty/blob/main/LICENSE).

sqlty-0.2.0/pyproject.toml

@@ -0,0 +1,172 @@
+[project]
+name = "sqlty"
+dynamic = ["version"]
+description = "Type-safe SQL queries for Python"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jiri Kuncar", email = "jiri.kuncar@gmail.com" }]
+keywords = [
+    "sql",
+    "type-hints",
+    "mypy",
+    "type-safety",
+    "static-analysis",
+    "code-generation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Programming Language :: Rust",
+    "Programming Language :: SQL",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Database",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pathspec>=0.12.1",
+    "typing-extensions>=4.15.0; python_version < '3.15'",
+]
+
+[project.urls]
+Homepage = "https://github.com/jirikuncar/sqlty"
+Documentation = "https://jirikuncar.github.io/sqlty/"
+Repository = "https://github.com/jirikuncar/sqlty"
+Changelog = "https://github.com/jirikuncar/sqlty/releases"
+Issues = "https://github.com/jirikuncar/sqlty/issues"
+
+[project.scripts]
+sqlty = "sqlty._cli:main"
+
+[project.optional-dependencies]
+psycopg = ["psycopg>=3.2.12"]
+
+[build-system]
+requires = ["maturin>=1.12.1,<2.0"]
+build-backend = "maturin"
+
+[tool.maturin]
+python-source = "src"
+module-name = "sqlty._core"
+features = ["pyo3/extension-module"]
+manifest-path = "rust/crates/sqlty-ext/Cargo.toml"
+# Ship the startup hook at the wheel root so it lands in site-packages and
+# registers the lazy "sqlty" codec lookup (see docs/guide/magic-codec.md).
+# The path is relative to the project root (maturin >= 1.12.1): the wheel gets
+# it at the root (python-source prefix stripped), the sdist at src/.
+# The Agent Skills are compiled into the extension, so only the sdist needs them.
+include = ["src/sqlty_magic.pth", { path = "skills/**/*", format = "sdist" }]
+
+[dependency-groups]
+dev = [
+    "inline-snapshot>=0.15.0",
+    "maturin>=1.12.1,<2.0",
+    "mypy>=2.4.0",
+    "prek>=0.5.4",
+    "pyright>=1.1.414",
+    "pytest>=8.4.2",
+    "pytest-cov>=6.0.0",
+    "pytest-randomly>=3.16.0",
+    "pyyaml>=6.0.2",
+    "ruff>=0.16.10",
+    "ty>=0.0.85",
+    "rumdl>=0.3.0",
+    "vale>=3.22.0.0",
+    "zizmor>=1.31.1",
+]
+cli = ["rich>=15.0.0"]
+# Only the DuckDB type tests need it, and it has no wheel for every Python.
+duckdb = ["duckdb>=1.4.0"]
+psycopg = ["psycopg>=3.2.12"]
+fuzz = [
+    "hypothesis>=6.140",
+]
+
+[tool.pytest.ini_options]
+addopts = ["-p", "tests._mdtest.plugin", "--cov-report=term-missing", "--cov-report=html", "-v"]
+pythonpath = ["."]
+testpaths = ["tests", "docs", "src/sqlty/rules", "README.md"]
+mdtest_paths = ["tests/mdtest", "docs", "src/sqlty/rules", "README.md", "skills"]
+markers = [
+    "e2e: end-to-end tests (subprocess + inline-snapshot)",
+    "slow: slow tests that can be skipped with -m 'not slow'",
+    "pg: needs a PostgreSQL server (SQLTY_PG_DSN); skipped without it",
+]
+
+[tool.coverage.run]
+concurrency = ["multiprocessing"]
+parallel = true
+sigterm = true
+patch = ["subprocess"]
+omit = ["tests/*", "examples/*"]
+
+[tool.coverage.paths]
+source = ["src/"]
+
+[tool.coverage.combine]
+show_missing = true
+
+[tool.mypy]
+python_version = "3.15"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+check_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+
+[[tool.mypy.overrides]]
+module = "psycopg.*"
+ignore_missing_imports = true
+
+[tool.ty.environment]
+# Python version will be inferred from requires-python
+root = ["./src", "./examples"]
+
+[tool.ty.src]
+include = ["src", "examples"]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+# Markdown code blocks are test data (mdtest, README) and must not be reformatted.
+extend-exclude = ["tests/typechecks", "*.md"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "SIM102", # nested if statements (can be more readable)
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.rumdl]
+# Long lines are tables and links; spaces in code spans show `--sql ` on purpose.
+disable = ["MD013", "MD038"]
+exclude = ["site", ".vale", ".github", "tests", "scripts/compat/reports", "PLAN-FUTURE.md", "rust/target", "proofs/.lake"]
+
+[tool.rumdl.per-file-ignores]
+# The demo GIF needs HTML for its width and centering.
+"README.md" = ["MD033"]