squonk-python

Python bindings for squonk: a maturin-built Rust extension plus typed Python views over a lazily materialized AST.

API

parse() returns a Document backed by an opaque Rust-owned parse result. Source metadata and parse → render stay native; mapping access, to_dict(), and typed node traversal materialize the JSON tree only when requested:

import squonk

doc = squonk.parse("select salary from employees", dialect="ansi")

assert doc.source == "select salary from employees"
assert doc.to_sql() == "SELECT salary FROM employees"
assert doc.statements[0].to_sql() == "SELECT salary FROM employees"

# Documents are live views: editing the raw tree changes subsequent rendering.
doc.to_dict()["statements"].clear()
assert doc.to_sql() == ""

idents = [ident.text for ident in doc.find_all(squonk.Ident)]
assert {"salary", "employees"}.issubset(idents)

Use parse_dict() when you want the raw serde-compatible JSON shape:

tree: squonk.ParseDocumentJson = squonk.parse_dict("select 1")
assert tree["statements"]

Dialect literals and aliases retain their canonical type: type checkers infer squonk.parse("select 1", "pg").dialect as Literal["postgres"]. Validate configuration strings with validate_dialect() before passing them to typed APIs.

Recovering parse keeps good statements and reports bad statements out of band:

result = squonk.parse_recovering("select 1; from broken; select 2")

for diagnostic in result.errors:
    print(diagnostic.kind, diagnostic.source_text(), diagnostic.location())

Tokenization returns discriminated token dictionaries. Trivia capture is opt-in:

tokens = squonk.tokenize("-- lead\nselect a + $1", "postgres", include_trivia=True)

assert tokens["tokens"][0]["kind"] == "Keyword"
assert tokens["tokens"][0]["keyword"] == "select"
assert tokens["trivia"][0]["kind"] == "LineComment"

Rendering and transpilation use Rust's renderer:

assert squonk.render("select 1") == "SELECT 1"
assert squonk.redact("select 123") != "SELECT 123"
assert squonk.transpile("select $1", "postgres", "postgres") == "SELECT $1"

When rendering a Document, the document's dialect is used unless you pass an override:

doc = squonk.parse("select $1", dialect="postgres")
assert squonk.render(doc) == "SELECT $1"

Types

The package ships py.typed plus stubs for the public API. The dict-returning helpers expose TypedDict shapes such as ParseDocumentJson, RecoveredDocumentJson, TokenizeResultJson, TokenJson, TriviaJson, and DiagnosticJson.

The materialized AST is represented as serde JSON. Document, Node, Ident, ObjectName, Diagnostic, and Trivia provide ergonomic wrappers without hiding the raw JSON: to_dict() returns Python structures and to_json() returns compact JSON text. The generated squonk.ast module exhaustively types the serialized node graph, while squonk.__schema_version__ identifies its wire-schema version. Generated child-node edges use a bounded JSON object type so mypy and Pyright do not recursively expand the entire AST graph; annotate a known node with its named type from squonk.ast when field-level precision is needed.

ObjectName is schema-aware: true qualified object-name fields wrap as ObjectName, while plain Ident lists such as column lists remain lists of Ident wrappers.

Node.to_sql() renders complete statements, queries, expressions, and data types. Check node.is_renderable first when traversing arbitrary nodes; context-dependent nodes raise UnsupportedNodeRenderError. All library failures derive from SquonkError, with structured subclasses for parsing, dialects, tokenization, rendering, formatting, and serialization.

Examples

Runnable scripts live in examples/:

  • metadata_report.py parses SQL and reports identifiers, table names, source snippets, and canonical SQL.
  • recovering_diagnostics.py shows statement-level recovery with byte-span diagnostics.
  • render_transpile_redact.py shows canonical render, redaction, and source/target dialect rendering.

From the Python crate directory after maturin develop:

cd crates/squonk-python
uv run python examples/metadata_report.py
uv run python examples/recovering_diagnostics.py
uv run python examples/render_transpile_redact.py

Development

From the Python crate directory:

cd crates/squonk-python
uv sync --group dev
uv run maturin develop
uv run pytest
uv run ruff check python
uv run mypy
uv run python -m mypy.stubtest squonk._ast squonk._exceptions squonk._native

The Rust boundary is checked by cargo check -p squonk-python; the Python tests live under crates/squonk-python/python/tests and smoke-run the examples.

Project links

Data verified by PyPI on Jul 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.0.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for moderately-ai from gravatar.com moderately-ai

Credits

Author: Moderately AI

GitHub Statistics

Data verified by PyPI on Jul 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

sql parser ast dialect sql-parser transpile

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

squonk-2.0.0.tar.gz (2.1 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

squonk-2.0.0-cp311-abi3-win_amd64.whl (6.1 MB view details)

Uploaded CPython 3.11+Windows x86-64

squonk-2.0.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.8 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

squonk-2.0.0-cp311-abi3-macosx_11_0_arm64.whl (5.3 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

squonk-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl (5.8 MB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file squonk-2.0.0.tar.gz.

File metadata

  • Download URL: squonk-2.0.0.tar.gz
  • Upload date:
  • Size: 2.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for squonk-2.0.0.tar.gz
Algorithm Hash digest
SHA256 e64331b4fdd5865b0b3cfb5b4139830dbf5372fbc4a67daae7a3a1bc80a0674b
MD5 80529348d6621e74f8ee4c4474ca2e8d
BLAKE2b-256 854068d4126867142ce67ea34377ceb33d5ad1fd3faf3496b2bd948e93057e06

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-2.0.0.tar.gz:

Publisher: release-python.yml on moderately-ai/squonk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file squonk-2.0.0-cp311-abi3-win_amd64.whl.

File metadata

  • Download URL: squonk-2.0.0-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 6.1 MB
  • Tags: CPython 3.11+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for squonk-2.0.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e9005804814ee7a75cf5cd77f9b6af0373745c849c61205281d972c19e086f48
MD5 101b11fbe2bf69410fb2a971505050ca
BLAKE2b-256 ef56a1f466f51823cc2f5a8b0b56bd49e51852370934872541c14fbe7b256571

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-2.0.0-cp311-abi3-win_amd64.whl:

Publisher: release-python.yml on moderately-ai/squonk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file squonk-2.0.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for squonk-2.0.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7b29280c6946f8fdaacc3df515bca309014b90c6cf6a311c823c073f37b7bb5a
MD5 268f3cd1d80d52319658a2b5e85bb3bc
BLAKE2b-256 5107103963cef7f13cf02a6dbc76171178a5105fbabedd9aabe91c13016fcc2f

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-2.0.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-python.yml on moderately-ai/squonk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file squonk-2.0.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for squonk-2.0.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0a2cbc9cf843a8fcf2a4f6ec9deca9f13d869e9273103d6635f89003036a0c1d
MD5 a3f0973b7b5819ba19aa7c9f4614be80
BLAKE2b-256 fc7fc88eb730ca29502aaa45a1872e305f1cd47ff4b83b7828f165933aa0cf9d

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-2.0.0-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release-python.yml on moderately-ai/squonk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file squonk-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for squonk-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 da143b6cefb06f57f3df9b7626230bfe1c3393b2ee4aeb3d8fbf3e1d489ec59f
MD5 5427b02e2e9e816a0707cac49baf4000
BLAKE2b-256 c1410262c130430a4e290139dd8a03537f23f626b4b009ca97efa90abaa9dead

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: release-python.yml on moderately-ai/squonk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.0.0

5 files

This release

2.0.0 This release

5 files

1.0.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page