namedquery 0.1.0__tar.gz

namedquery-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

namedquery-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+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

namedquery-0.1.0/README.md

@@ -0,0 +1,103 @@
+
+# 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

namedquery-0.1.0/namedquery/__init__.py

@@ -0,0 +1,2 @@
+from .core import NamedQuery
+from .core import named

namedquery-0.1.0/namedquery/core.py

@@ -0,0 +1,20 @@
+import re
+
+_named_param_re = re.compile(r'(?<!:):(\w+)')
+
+class NamedQuery:
+	def __init__(self, sql):
+		params = []
+		def replace(m):
+			params.append(m.group(1))
+			return f'${len(params)}'
+
+		self.sql = _named_param_re.sub(replace, sql)
+		self.params = params
+
+	def args(self, kwargs):
+		return [kwargs[p] for p in self.params]
+
+
+def named(sql):
+	return NamedQuery(sql)

namedquery-0.1.0/namedquery.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+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

namedquery-0.1.0/namedquery.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+namedquery/__init__.py
+namedquery/core.py
+namedquery.egg-info/PKG-INFO
+namedquery.egg-info/SOURCES.txt
+namedquery.egg-info/dependency_links.txt
+namedquery.egg-info/top_level.txt
+tests/test_namedquery.py

namedquery-0.1.0/namedquery.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

namedquery-0.1.0/namedquery.egg-info/top_level.txt

@@ -0,0 +1 @@
+namedquery

namedquery-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "namedquery"
+version = "0.1.0"
+description = "Named SQL parameters with once-at-definition parsing"
+authors = [
+	{ name = "Gustavo Venturini", email = "gustavo.c.venturini@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = []
+readme = { file = "README.md", content-type = "text/markdown" }
+license = {file = "LICENSE"}
+classifiers = [
+	"Development Status :: 4 - Beta",
+	"Intended Audience :: Developers",
+	"License :: OSI Approved :: MIT License",
+	"Operating System :: OS Independent",
+	"Programming Language :: Python :: 3 :: Only",
+	"Topic :: Database",
+	"Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/vottini/namedquery"

namedquery-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

namedquery-0.1.0/tests/test_namedquery.py

@@ -0,0 +1,19 @@
+from namedquery import NamedQuery, named
+
+
+def testNamedQuery():
+	q = named("SELECT * FROM t WHERE a = :a AND b = :b")
+	assert q.sql == "SELECT * FROM t WHERE a = $1 AND b = $2"
+	assert q.args({'a': 1, 'b': 2}) == [1, 2]
+
+
+def testNamedQueryRepeatedParam():
+	q = named("SELECT :x + :x AS double")
+	assert q.sql == "SELECT $1 + $2 AS double"
+	assert q.args({'x': 5}) == [5, 5]
+
+
+def testNamedQueryCastNotAffected():
+	q = named("SELECT col::text FROM t WHERE id = :id")
+	assert q.sql == "SELECT col::text FROM t WHERE id = $1"
+	assert q.args({'id': 42}) == [42]