t-sql 4.12.0__tar.gz → 4.13.0__tar.gz

t_sql-4.12.0/README.md → t_sql-4.13.0/PKG-INFO

@@ -1,3 +1,14 @@
+Metadata-Version: 2.4
+Name: t-sql
+Version: 4.13.0
+Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
+Project-URL: Homepage, https://github.com/nhumrich/t-sql
+License-File: LICENSE
+Requires-Python: >=3.14
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
 # t-sql
 
 A lightweight SQL templating library that leverages Python 3.14's t-strings (PEP 750).
@@ -300,6 +311,31 @@ query = (Posts.select()
          .left_join(Users, on=Posts.user_id == Users.id))
 ```
 
+### Raw JOIN clauses (escape hatch)
+
+For join shapes the typed `join()`/`left_join()`/`right_join()` can't express —
+LATERAL subqueries, ON-less cross joins, set-returning functions — use
+`join_raw()` to splice a complete JOIN clause Template verbatim. The Template
+must carry the **whole** clause including the join keyword; nothing is added
+around it. Parameters inside the Template are still parameterized and renumber
+correctly alongside the rest of the query.
+
+```python
+query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+         .select(t't.*')
+         .join_raw(t'CROSS JOIN LATERAL unnest(t.tags) AS tag'))
+
+# Parameterized raw join, composed with a WHERE clause
+query = (SelectQueryBuilder.from_table('records', alias='t')
+         .select(t't.*')
+         .join_raw(t'LEFT JOIN other o ON o.id = t.ref AND o.kind = {"x"}')
+         .where(t't.active = {True}'))
+```
+
+> ⚠️ **Not advised.** `join_raw()` bypasses the builder's join structure. Prefer
+> the typed `join()`/`left_join()`/`right_join()` with a Table + Condition
+> wherever they suffice.
+
 ## Query Features
 
 ### Selecting All Columns from a Table
@@ -323,6 +359,34 @@ query = Posts.select(Posts.ALL, Users.ALL).join(Users, Posts.user_id == Users.id
 
 This is particularly useful when joining tables where you want all columns from one table but only specific columns from others.
 
+### DISTINCT ON (PostgreSQL)
+
+`distinct_on()` emits a `SELECT DISTINCT ON (...)` clause. It accepts Column
+objects, string column names, or raw Templates — coerced exactly like
+`select()`.
+
+```python
+query = Users.select(Users.id, Users.username).distinct_on('username')
+# ('SELECT DISTINCT ON (username) users.id, users.username FROM users', [])
+
+# Multiple columns are comma-joined inside the parens
+query = Users.select(Users.id).distinct_on('username', 'email')
+# ('SELECT DISTINCT ON (username, email) users.id FROM users', [])
+```
+
+### FROM ONLY and Table Aliases
+
+When building from a string table name, `from_table()` accepts `only=True` to
+emit `FROM ONLY {table}` (excludes inheriting child tables in PostgreSQL) and
+`alias=...` to emit `FROM {table} AS {alias}` (the alias is identifier-validated):
+
+```python
+query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t', only=True)
+         .select(t't.*')
+         .where(t't.active = {True}'))
+# ('SELECT t.* FROM ONLY dataset.records AS t WHERE (t.active = $1)', [True])
+```
+
 ### NULL Checks and Other Operators
 
 ```python
@@ -349,6 +413,11 @@ query = Posts.select().order_by(Posts.id)  # defaults to ASC
 query = Posts.select().order_by(Posts.id.desc())
 query = Posts.select().order_by(Posts.created_at.asc(), Posts.id.desc())
 
+# ORDER BY / GROUP BY also accept raw Templates, emitted verbatim
+# (parity with where()/having()/select()), for computed expressions:
+query = Posts.select().order_by(t'lower(title) DESC')
+query = Posts.select().group_by(t"date_trunc('day', created_at)")
+
 # LIMIT and OFFSET
 query = Posts.select().limit(10).offset(20)
 
@@ -579,6 +648,8 @@ pip install t-sql[sqlalchemy]
 uv add t-sql --optional sqlalchemy
 ```
 
+> Note: the `sqlalchemy` extra installs SQLAlchemy only. Alembic is not a t-sql dependency — if you use alembic autogenerate, add `alembic` to your own project's dependencies (it's your migration tooling, not ours).
+
 ### Two Ways to Define Columns
 
 **1. Simple Column annotations** (for query builder only):

t_sql-4.12.0/PKG-INFO → t_sql-4.13.0/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.4
-Name: t-sql
-Version: 4.12.0
-Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
-Project-URL: Homepage, https://github.com/nhumrich/t-sql
-License-File: LICENSE
-Requires-Python: >=3.14
-Requires-Dist: alembic>=1.17.0
-Description-Content-Type: text/markdown
-
 # t-sql
 
 A lightweight SQL templating library that leverages Python 3.14's t-strings (PEP 750).
@@ -310,6 +300,31 @@ query = (Posts.select()
          .left_join(Users, on=Posts.user_id == Users.id))
 ```
 
+### Raw JOIN clauses (escape hatch)
+
+For join shapes the typed `join()`/`left_join()`/`right_join()` can't express —
+LATERAL subqueries, ON-less cross joins, set-returning functions — use
+`join_raw()` to splice a complete JOIN clause Template verbatim. The Template
+must carry the **whole** clause including the join keyword; nothing is added
+around it. Parameters inside the Template are still parameterized and renumber
+correctly alongside the rest of the query.
+
+```python
+query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+         .select(t't.*')
+         .join_raw(t'CROSS JOIN LATERAL unnest(t.tags) AS tag'))
+
+# Parameterized raw join, composed with a WHERE clause
+query = (SelectQueryBuilder.from_table('records', alias='t')
+         .select(t't.*')
+         .join_raw(t'LEFT JOIN other o ON o.id = t.ref AND o.kind = {"x"}')
+         .where(t't.active = {True}'))
+```
+
+> ⚠️ **Not advised.** `join_raw()` bypasses the builder's join structure. Prefer
+> the typed `join()`/`left_join()`/`right_join()` with a Table + Condition
+> wherever they suffice.
+
 ## Query Features
 
 ### Selecting All Columns from a Table
@@ -333,6 +348,34 @@ query = Posts.select(Posts.ALL, Users.ALL).join(Users, Posts.user_id == Users.id
 
 This is particularly useful when joining tables where you want all columns from one table but only specific columns from others.
 
+### DISTINCT ON (PostgreSQL)
+
+`distinct_on()` emits a `SELECT DISTINCT ON (...)` clause. It accepts Column
+objects, string column names, or raw Templates — coerced exactly like
+`select()`.
+
+```python
+query = Users.select(Users.id, Users.username).distinct_on('username')
+# ('SELECT DISTINCT ON (username) users.id, users.username FROM users', [])
+
+# Multiple columns are comma-joined inside the parens
+query = Users.select(Users.id).distinct_on('username', 'email')
+# ('SELECT DISTINCT ON (username, email) users.id FROM users', [])
+```
+
+### FROM ONLY and Table Aliases
+
+When building from a string table name, `from_table()` accepts `only=True` to
+emit `FROM ONLY {table}` (excludes inheriting child tables in PostgreSQL) and
+`alias=...` to emit `FROM {table} AS {alias}` (the alias is identifier-validated):
+
+```python
+query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t', only=True)
+         .select(t't.*')
+         .where(t't.active = {True}'))
+# ('SELECT t.* FROM ONLY dataset.records AS t WHERE (t.active = $1)', [True])
+```
+
 ### NULL Checks and Other Operators
 
 ```python
@@ -359,6 +402,11 @@ query = Posts.select().order_by(Posts.id)  # defaults to ASC
 query = Posts.select().order_by(Posts.id.desc())
 query = Posts.select().order_by(Posts.created_at.asc(), Posts.id.desc())
 
+# ORDER BY / GROUP BY also accept raw Templates, emitted verbatim
+# (parity with where()/having()/select()), for computed expressions:
+query = Posts.select().order_by(t'lower(title) DESC')
+query = Posts.select().group_by(t"date_trunc('day', created_at)")
+
 # LIMIT and OFFSET
 query = Posts.select().limit(10).offset(20)
 
@@ -589,6 +637,8 @@ pip install t-sql[sqlalchemy]
 uv add t-sql --optional sqlalchemy
 ```
 
+> Note: the `sqlalchemy` extra installs SQLAlchemy only. Alembic is not a t-sql dependency — if you use alembic autogenerate, add `alembic` to your own project's dependencies (it's your migration tooling, not ours).
+
 ### Two Ways to Define Columns
 
 **1. Simple Column annotations** (for query builder only):

{t_sql-4.12.0 → t_sql-4.13.0}/pyproject.toml

@@ -4,13 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "t-sql"
-version = "4.12.0"
+version = "4.13.0"
 description = "Safe SQL. SQL queries for python t-strings (PEP 750)"
 readme = "README.md"
 requires-python = ">=3.14"
-dependencies = [
-    "alembic>=1.17.0",
-]
+dependencies = []
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0.0"]
 
 [project.urls]
 Homepage = "https://github.com/nhumrich/t-sql"
@@ -20,6 +21,7 @@ Homepage = "https://github.com/nhumrich/t-sql"
 dev = [
     "aiomysql>=0.2.0",
     "aiosqlite>=0.20.0",
+    "alembic>=1.17.0",
     "anyio>=4.9.0",
     "asyncpg>=0.30.0",
     "cryptography>=46.0.2",