ahi-sql 0.2.0__tar.gz

ahi_sql-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.dist/
+build/
+dist/
+
+# Virtual environments
+.venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDEs/OS
+.DS_Store
+.vscode/*.code-snippets
+
+# Docs build
+site/

ahi_sql-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/adaptivehealthintelligence/ahi-python-packages/compare/ahi-sql-v0.1.0...ahi-sql-v0.2.0) (2026-06-27)
+
+
+### Features
+
+* scaffold uv workspace with core, sql, aws packages ([8c42f2f](https://github.com/adaptivehealthintelligence/ahi-python-packages/commit/8c42f2f371284180bf0569785837640e39deb80b))

ahi_sql-0.2.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: ahi-sql
+Version: 0.2.0
+Summary: Small, dependency-light SQL helpers for AHI (safe identifiers, placeholders).
+Project-URL: Homepage, https://github.com/adaptivehealthintelligence/ahi-python-packages
+Project-URL: Documentation, https://adaptivehealthintelligence.github.io/ahi-python-packages/
+Project-URL: Repository, https://github.com/adaptivehealthintelligence/ahi-python-packages
+Author: Adaptive Health Intelligence
+License: MIT
+Keywords: ahi,sql
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ahi-sql
+
+Small, dependency-light SQL helpers — the bits people otherwise hand-roll and
+get subtly wrong.
+
+```python
+from ahi.sql import quote_identifier, placeholders
+
+quote_identifier("user table")          # '"user table"'
+placeholders(3, style="qmark")          # '?, ?, ?'   (Athena)
+placeholders(3, style="named")          # ':1, :2, :3' (Redshift Data API)
+```
+
+> Quote **identifiers** with `quote_identifier`. Quote **values** by passing them
+> as bind parameters to your driver — never by string-formatting them in.
+
+Part of [ahi-python-packages](https://github.com/adaptivehealthintelligence/ahi-python-packages).

ahi_sql-0.2.0/README.md

@@ -0,0 +1,17 @@
+# ahi-sql
+
+Small, dependency-light SQL helpers — the bits people otherwise hand-roll and
+get subtly wrong.
+
+```python
+from ahi.sql import quote_identifier, placeholders
+
+quote_identifier("user table")          # '"user table"'
+placeholders(3, style="qmark")          # '?, ?, ?'   (Athena)
+placeholders(3, style="named")          # ':1, :2, :3' (Redshift Data API)
+```
+
+> Quote **identifiers** with `quote_identifier`. Quote **values** by passing them
+> as bind parameters to your driver — never by string-formatting them in.
+
+Part of [ahi-python-packages](https://github.com/adaptivehealthintelligence/ahi-python-packages).

ahi_sql-0.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "ahi-sql"
+version = "0.2.0"
+description = "Small, dependency-light SQL helpers for AHI (safe identifiers, placeholders)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Adaptive Health Intelligence" }]
+keywords = ["ahi", "sql"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/adaptivehealthintelligence/ahi-python-packages"
+Documentation = "https://adaptivehealthintelligence.github.io/ahi-python-packages/"
+Repository = "https://github.com/adaptivehealthintelligence/ahi-python-packages"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ahi"]

ahi_sql-0.2.0/src/ahi/sql/__init__.py

@@ -0,0 +1,5 @@
+"""Small, dependency-light SQL helpers."""
+
+from ahi.sql.identifiers import placeholders, quote_identifier
+
+__all__ = ["placeholders", "quote_identifier"]

ahi_sql-0.2.0/src/ahi/sql/identifiers.py

@@ -0,0 +1,51 @@
+"""Helpers for building SQL fragments safely.
+
+These cover the two things people most often hand-roll (and get wrong):
+quoting an identifier, and generating the right number of bind placeholders.
+Both default to ANSI/PostgreSQL-style quoting, which also matches Redshift.
+"""
+
+from __future__ import annotations
+
+
+def quote_identifier(name: str, *, quote: str = '"') -> str:
+    """Safely quote a SQL identifier (table/column name).
+
+    Wraps ``name`` in ``quote`` characters and escapes any embedded quote by
+    doubling it, the ANSI rule. Use this for identifiers only — never for
+    values, which belong in bind parameters.
+
+    Args:
+        name: The identifier to quote. Must be non-empty.
+        quote: The quote character (``"`` for ANSI/Redshift, `` ` `` for MySQL).
+
+    Raises:
+        ValueError: If ``name`` is empty.
+    """
+    if not name:
+        raise ValueError("identifier must be non-empty")
+    escaped = name.replace(quote, quote * 2)
+    return f"{quote}{escaped}{quote}"
+
+
+def placeholders(count: int, *, style: str = "qmark") -> str:
+    """Return a comma-separated list of bind placeholders for an ``IN`` clause.
+
+    Args:
+        count: Number of placeholders (must be >= 1).
+        style: ``"qmark"`` -> ``?, ?, ?`` (Athena),
+            ``"named"`` -> ``:1, :2, :3`` (Redshift Data API),
+            ``"format"`` -> ``%s, %s, %s`` (psycopg).
+
+    Raises:
+        ValueError: If ``count`` < 1 or ``style`` is unknown.
+    """
+    if count < 1:
+        raise ValueError("count must be >= 1")
+    if style == "qmark":
+        return ", ".join(["?"] * count)
+    if style == "format":
+        return ", ".join(["%s"] * count)
+    if style == "named":
+        return ", ".join(f":{i}" for i in range(1, count + 1))
+    raise ValueError(f"unknown placeholder style: {style!r}")

ahi_sql-0.2.0/tests/test_identifiers.py

@@ -0,0 +1,42 @@
+import pytest
+
+from ahi.sql import placeholders, quote_identifier
+
+
+def test_quote_identifier_basic() -> None:
+    assert quote_identifier("users") == '"users"'
+
+
+def test_quote_identifier_escapes_embedded_quote() -> None:
+    assert quote_identifier('we"ird') == '"we""ird"'
+
+
+def test_quote_identifier_custom_quote() -> None:
+    assert quote_identifier("users", quote="`") == "`users`"
+
+
+def test_quote_identifier_rejects_empty() -> None:
+    with pytest.raises(ValueError):
+        quote_identifier("")
+
+
+@pytest.mark.parametrize(
+    ("count", "style", "expected"),
+    [
+        (3, "qmark", "?, ?, ?"),
+        (2, "format", "%s, %s"),
+        (3, "named", ":1, :2, :3"),
+    ],
+)
+def test_placeholders(count: int, style: str, expected: str) -> None:
+    assert placeholders(count, style=style) == expected
+
+
+def test_placeholders_rejects_zero() -> None:
+    with pytest.raises(ValueError):
+        placeholders(0)
+
+
+def test_placeholders_rejects_unknown_style() -> None:
+    with pytest.raises(ValueError):
+        placeholders(2, style="bogus")