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 31, 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:
Latest release

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 31, 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-3.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-3.0.0-cp311-abi3-win_amd64.whl (6.2 MB view details)

Uploaded CPython 3.11+Windows x86-64

squonk-3.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-3.0.0-cp311-abi3-macosx_11_0_arm64.whl (5.3 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

squonk-3.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-3.0.0.tar.gz.

File metadata

  • Download URL: squonk-3.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.14

File hashes

Hashes for squonk-3.0.0.tar.gz
Algorithm Hash digest
SHA256 da61f8e875eee667e83f7a2f8e35f9e3ce42b5ebf825dfb1f3bf2ed1e1ae9c6a
MD5 c8858108be8af9e8a244644cb1c303c8
BLAKE2b-256 1aa172b4898ea4e089d9071d8ab4b1c8bc042fc646ab88416872527827cb19f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-3.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-3.0.0-cp311-abi3-win_amd64.whl.

File metadata

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

File hashes

Hashes for squonk-3.0.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4d779795ba6ab277ca2978d96c873cc0d7dbfa4f51f4286a5e11144f3c89675a
MD5 f2385ae506251d143e6c7138a0101def
BLAKE2b-256 5a52e11e631f7e10240ad4503bd3127794ecbe2acf437d167545a1b2d7e3b474

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-3.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-3.0.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for squonk-3.0.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c2ad2af9214f6eb514ad929c38fb7053955fc9a63dd94d99aa79b5e33e4e496c
MD5 2504bbbbc20043c98d85ac4e45203e30
BLAKE2b-256 b89b130b16443584eb3622b8d228a2d9410e60f96153a9b7f78626a13f15d166

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-3.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-3.0.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for squonk-3.0.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9ce083c451fc78e95631dc6bd4adaff698fa44016f8303f3893d31e25b89e389
MD5 10d24b204d735be80030e962287877fb
BLAKE2b-256 218844a5f5b02e5f510790b04451875318554ac6ec45d1958060dc1d0f92322c

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-3.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-3.0.0-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for squonk-3.0.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 bd441b81fc453c335287e15572ac94fca89bdcb4c6f3ad2a20f91a96b9e234c4
MD5 b3b2264db78c19a703a1a305bf45a97c
BLAKE2b-256 c2cf9343364d41ffbd71de119b816217028d9879ad8608e4f084fc829417fb29

See more details on using hashes here.

Provenance

The following attestation bundles were made for squonk-3.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

This release

3.0.0 This release

5 files

2.0.0

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