Metadata-Version: 2.4
Name: namedquery
Version: 0.1.0
Summary: Named SQL parameters with once-at-definition parsing
Author-email: Gustavo Venturini <gustavo.c.venturini@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Gustavo Venturini
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/vottini/namedquery
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file


# namedquery

A minimal Python utility that converts named SQL parameters (`:name` style) into
positional `$N` parameters, parsing the query once at definition time so repeated
executions pay no parsing cost.

> Most named-parameter libraries re-parse the SQL string on every call. `namedquery`
> exists because that's unnecessary work — if your queries are fixed at startup,
> the regex should run exactly once. Every subsequent execution is just a list lookup.

---

## Installation

```bash
pip install namedquery
```

---

## Why

Most Python SQL drivers that target PostgreSQL (`asyncpg`, `psycopg3`) expect
positional parameters (`$1`, `$2`, …), but writing positional SQL by hand is
error-prone — parameter order must match the argument list exactly.

Named parameters (`:id`, `:active`) are readable and order-independent, but need
to be converted before the driver sees them.

`namedquery` does that conversion **once**, at the time you define the query. Every
subsequent execution is a plain list lookup — no regex, no re-parsing.

---

## Usage

```python
from namedquery import named

GET_USER = named("SELECT * FROM users WHERE id = :id AND active = :active")

# Transformed SQL, ready for the driver
GET_USER.sql
# 'SELECT * FROM users WHERE id = $1 AND active = $2'

# Arguments in the correct positional order
GET_USER.args({'id': 7, 'active': True})
# [7, True]
```

Pass directly to your driver:

```python
await conn.fetch(GET_USER.sql, *GET_USER.args({'id': 7, 'active': True}))
```

### Defining queries at startup

The intended pattern is to define all queries once as module-level constants and
reuse them throughout the application lifetime:

```python
# queries.py
from namedquery import named

GET_USER    = named("SELECT * FROM users WHERE id = :id")
LIST_ACTIVE = named("SELECT * FROM users WHERE active = :active ORDER BY :order_by")
INSERT_USER = named("INSERT INTO users (name, email) VALUES (:name, :email) RETURNING id")
```

### PostgreSQL cast syntax

`::type` casts are left untouched:

```python
named("SELECT col::text FROM t WHERE id = :id").sql
# 'SELECT col::text FROM t WHERE id = $1'
```

---

## API

### `named(sql) -> NamedQuery`

Parses `sql`, replaces every `:name` placeholder with a `$N` positional parameter,
and returns a `NamedQuery` instance.

### `NamedQuery.sql`

The transformed SQL string with `$N` placeholders. Pass this to your driver.

### `NamedQuery.args(kwargs) -> list`

Returns the values from `kwargs` in the order the corresponding parameters appear
in the SQL. Pass the result as positional arguments to your driver call.

---

## License

MIT
