namedquery 0.1.0__py3-none-any.whl

namedquery/__init__.py

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+namedquery/__init__.py,sha256=Yt64fNzWZNRhMjgaJnbZWnP6H3ZiteCZgqVFQcR1ttQ,53
+namedquery/core.py,sha256=9dADofx9LTWJ820jgBJdxO9PXaKfUSI1gNfLn9cKSII,372
+namedquery-0.1.0.dist-info/licenses/LICENSE,sha256=tYW3_ojXxJ8z3MdTV2oAvQgNq_THeGpvt5e0HFOJKTo,1074
+namedquery-0.1.0.dist-info/METADATA,sha256=DzArxQZrFe7r19AKqrbjAh0W6Vb2IOPfF5lvGv3ipRQ,4569
+namedquery-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+namedquery-0.1.0.dist-info/top_level.txt,sha256=SRU-bjnno4A11gBv_PSGWTsMMvFgzHaqwStaJGYZaOw,11
+namedquery-0.1.0.dist-info/RECORD,,

namedquery-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

namedquery-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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