sqlscope-rs 0.1.0__cp39-abi3-win_amd64.whl

sqlscope/__init__.py

@@ -0,0 +1,269 @@
+"""Scope-aware SQL analysis and rewriting.
+
+=====================  ==========================================================
+Function               Purpose
+=====================  ==========================================================
+apply_row_filter       Filter every in-scope table by a predicate.
+inject_ctes            Prepend CTE definitions to a query's root ``WITH``.
+rewrite_tables         Replace table references with derived tables.
+column_origins         Source columns whose values reach the result (lineage).
+output_columns         Names of the columns a statement outputs.
+referenced_columns     Columns referenced anywhere, per table.
+column_usages          Column references with the clause they appear in.
+=====================  ==========================================================
+
+Every function accepts ``dialect`` (default ``"trino"``). Functions release the
+GIL while they run and are safe to call from several threads.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence, Tuple, Union
+
+from . import _native
+from ._native import (
+    Error,
+    InternalError,
+    InvalidArgumentError,
+    ParseError,
+    UnsupportedError,
+)
+
+__version__: str = _native.__version__
+
+__all__ = [
+    "Clause",
+    "ColumnUsage",
+    "CteDef",
+    "Error",
+    "InternalError",
+    "InvalidArgumentError",
+    "ParseError",
+    "Schema",
+    "TableRef",
+    "TableRewrite",
+    "UnionRewrite",
+    "UnsupportedError",
+    "apply_row_filter",
+    "column_origins",
+    "column_usages",
+    "inject_ctes",
+    "output_columns",
+    "referenced_columns",
+    "rewrite_tables",
+]
+
+Schema = Mapping[str, Sequence[str]]
+"""Table name (bare, ``schema.table`` or ``catalog.schema.table``) -> ordered column names."""
+
+
+@dataclass(frozen=True)
+class CteDef:
+    """A common table expression ``name AS (query)``.
+
+    ``name`` is an identifier value, not SQL text; it is quoted as needed.
+    """
+
+    name: str
+    query: str
+
+
+@dataclass(frozen=True)
+class TableRef:
+    """A table name, optionally schema- and catalog-qualified."""
+
+    table: str
+    schema: Optional[str] = None
+    catalog: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class UnionRewrite:
+    """A derived table backed by ``UNION DISTINCT`` over ``branches``."""
+
+    table_alias: str
+    columns: Sequence[str]
+    branches: Sequence[TableRef]
+
+
+@dataclass(frozen=True)
+class TableRewrite:
+    """Replaces references to ``match_key`` (``schema.table``).
+
+    Set exactly one of ``inline`` (``(SELECT * FROM inline)``) or ``union``.
+    """
+
+    match_key: str
+    inline: Optional[TableRef] = None
+    union: Optional[UnionRewrite] = None
+
+
+class Clause(str, Enum):
+    """The SQL clause that contains a column reference."""
+
+    SELECT = "SELECT"
+    FROM = "FROM"
+    JOIN_ON = "JOIN_ON"
+    JOIN_USING = "JOIN_USING"
+    WHERE = "WHERE"
+    GROUP_BY = "GROUP_BY"
+    HAVING = "HAVING"
+    QUALIFY = "QUALIFY"
+    WINDOW = "WINDOW"
+    ORDER_BY = "ORDER_BY"
+    SORT_BY = "SORT_BY"
+    DISTRIBUTE_BY = "DISTRIBUTE_BY"
+    CLUSTER_BY = "CLUSTER_BY"
+    CONNECT_BY = "CONNECT_BY"
+    LATERAL_VIEW = "LATERAL_VIEW"
+    UPDATE_SET_TARGET = "UPDATE_SET_TARGET"
+    UPDATE_SET_VALUE = "UPDATE_SET_VALUE"
+    MERGE_ON = "MERGE_ON"
+    MERGE_WHEN = "MERGE_WHEN"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, order=True)
+class ColumnUsage:
+    """One distinct use of a root table column in a clause."""
+
+    table: str
+    column: str
+    clause: Clause = field(compare=True)
+
+
+def _schema(schema: Optional[Schema]) -> Optional[Dict[str, List[str]]]:
+    if schema is None:
+        return None
+    return {str(table): [str(column) for column in columns] for table, columns in schema.items()}
+
+
+def _list(values: Optional[Iterable[str]]) -> Optional[List[str]]:
+    if values is None:
+        return None
+    if isinstance(values, str):
+        return [values]
+    return list(values)
+
+
+def apply_row_filter(
+    sql: str,
+    predicate: str,
+    *,
+    dialect: Optional[str] = None,
+    table_names: Optional[Iterable[str]] = None,
+    table_patterns: Optional[Iterable[str]] = None,
+    default_db: Optional[str] = None,
+) -> str:
+    """Wrap every in-scope table of a query in a derived table filtered by ``predicate``.
+
+    ``SELECT * FROM a`` becomes ``SELECT * FROM (SELECT * FROM a WHERE <predicate>) AS a``.
+    By default every physical table is filtered; ``table_names`` (bare,
+    ``schema.table`` or ``catalog.schema.table``), ``table_patterns`` (regular
+    expressions) and ``default_db`` restrict the scope. CTE references, table
+    functions and ``DUAL`` are never wrapped. ``predicate`` is parsed as one
+    boolean expression; bind or escape its values before calling. Returns the
+    input unchanged when no table is in scope.
+    """
+    return _native.apply_row_filter(
+        sql,
+        predicate,
+        dialect=dialect,
+        table_names=_list(table_names),
+        table_patterns=_list(table_patterns),
+        default_db=default_db,
+    )
+
+
+def inject_ctes(
+    sql: str,
+    ctes: Iterable[Union[CteDef, Tuple[str, str]]],
+    *,
+    dialect: Optional[str] = None,
+) -> str:
+    """Add CTE definitions to the root ``WITH`` of a query, before existing CTEs.
+
+    Definitions keep their order, so each may use earlier ones. A name that
+    repeats another definition or an existing root CTE is rejected.
+    """
+    pairs = [(cte.name, cte.query) if isinstance(cte, CteDef) else (cte[0], cte[1]) for cte in ctes]
+    return _native.inject_ctes(sql, pairs, dialect=dialect)
+
+
+def _table(ref: TableRef) -> Tuple[str, Optional[str], Optional[str]]:
+    return (ref.table, ref.schema, ref.catalog)
+
+
+def rewrite_tables(
+    sql: str,
+    rewrites: Iterable[TableRewrite],
+    *,
+    dialect: Optional[str] = None,
+    strip_catalogs: Optional[Iterable[str]] = None,
+) -> str:
+    """Replace physical table references according to ``rewrites``.
+
+    Matched references become derived tables that keep their alias (or bare
+    name); qualified column references are rebound onto it. Catalogs listed in
+    ``strip_catalogs`` are transparent while matching. Returns the input
+    unchanged when nothing matches.
+    """
+    plan = [
+        (
+            rewrite.match_key,
+            _table(rewrite.inline) if rewrite.inline is not None else None,
+            (
+                rewrite.union.table_alias,
+                list(rewrite.union.columns),
+                [_table(branch) for branch in rewrite.union.branches],
+            )
+            if rewrite.union is not None
+            else None,
+        )
+        for rewrite in rewrites
+    ]
+    return _native.rewrite_tables(sql, plan, dialect=dialect, strip_catalogs=_list(strip_catalogs))
+
+
+def column_origins(
+    sql: str, *, dialect: Optional[str] = None, schema: Optional[Schema] = None
+) -> Dict[str, List[str]]:
+    """Source columns whose values flow into the result, keyed by root table.
+
+    Filter-only positions (WHERE, JOIN ON, GROUP BY, HAVING, ORDER BY) and the
+    right side of INTERSECT / EXCEPT are excluded. Every table read is present,
+    possibly with an empty list.
+    """
+    return _native.column_origins(sql, dialect=dialect, schema=_schema(schema))
+
+
+def output_columns(
+    sql: str, *, dialect: Optional[str] = None, schema: Optional[Schema] = None
+) -> Optional[List[str]]:
+    """Names of the columns a statement outputs, in order.
+
+    Unaliased expressions are named ``_col{i}``; ``*`` expands from ``schema``
+    or stays ``"*"``. Returns ``None`` for statements without columns.
+    """
+    return _native.output_columns(sql, dialect=dialect, schema=_schema(schema))
+
+
+def referenced_columns(
+    sql: str, *, dialect: Optional[str] = None, schema: Optional[Schema] = None
+) -> Dict[str, List[str]]:
+    """Columns referenced anywhere in a statement (including filters), keyed by root table."""
+    return _native.referenced_columns(sql, dialect=dialect, schema=_schema(schema))
+
+
+def column_usages(
+    sql: str, *, dialect: Optional[str] = None, schema: Optional[Schema] = None
+) -> List[ColumnUsage]:
+    """Every distinct ``(table, column, clause)`` use in a statement, sorted."""
+    return [
+        ColumnUsage(table, column, Clause(clause))
+        for table, column, clause in _native.column_usages(sql, dialect=dialect, schema=_schema(schema))
+    ]

sqlscope/_native.pyi

@@ -0,0 +1,39 @@
+from typing import Dict, List, Optional, Tuple
+
+__version__: str
+
+class Error(Exception): ...
+class InvalidArgumentError(Error): ...
+class ParseError(Error): ...
+class UnsupportedError(Error): ...
+class InternalError(Error): ...
+
+_Table = Tuple[str, Optional[str], Optional[str]]
+
+def apply_row_filter(
+    sql: str,
+    predicate: str,
+    dialect: Optional[str] = ...,
+    table_names: Optional[List[str]] = ...,
+    table_patterns: Optional[List[str]] = ...,
+    default_db: Optional[str] = ...,
+) -> str: ...
+def inject_ctes(sql: str, ctes: List[Tuple[str, str]], dialect: Optional[str] = ...) -> str: ...
+def rewrite_tables(
+    sql: str,
+    rewrites: List[Tuple[str, Optional[_Table], Optional[Tuple[str, List[str], List[_Table]]]]],
+    dialect: Optional[str] = ...,
+    strip_catalogs: Optional[List[str]] = ...,
+) -> str: ...
+def column_origins(
+    sql: str, dialect: Optional[str] = ..., schema: Optional[Dict[str, List[str]]] = ...
+) -> Dict[str, List[str]]: ...
+def output_columns(
+    sql: str, dialect: Optional[str] = ..., schema: Optional[Dict[str, List[str]]] = ...
+) -> Optional[List[str]]: ...
+def referenced_columns(
+    sql: str, dialect: Optional[str] = ..., schema: Optional[Dict[str, List[str]]] = ...
+) -> Dict[str, List[str]]: ...
+def column_usages(
+    sql: str, dialect: Optional[str] = ..., schema: Optional[Dict[str, List[str]]] = ...
+) -> List[Tuple[str, str, str]]: ...

sqlscope_rs-0.1.0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: sqlscope-rs
+Version: 0.1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Summary: Scope-aware SQL analysis and rewriting: row filters, CTE injection, table rewrites, column lineage.
+Keywords: sql,lineage,row-level-security,parser
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/dcalsky/sqlscope
+
+# sqlscope (Python)
+
+Scope-aware SQL analysis and rewriting, backed by the Rust
+[sqlscope](https://github.com/dcalsky/sqlscope) crate.
+
+```bash
+pip install sqlscope-rs
+```
+
+```python
+import sqlscope
+
+sqlscope.apply_row_filter("SELECT id FROM orders", "tenant_id = 7", dialect="postgres")
+# 'SELECT id FROM (SELECT * FROM orders WHERE tenant_id = 7) AS orders'
+
+sqlscope.column_origins(
+    "SELECT o.id, p.amount FROM orders o JOIN payments p ON o.id = p.order_id WHERE o.status = 'PAID'"
+)
+# {'orders': ['id'], 'payments': ['amount']}
+```
+
+See the [project README](https://github.com/dcalsky/sqlscope#readme) for the
+full API.
+

sqlscope_rs-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sqlscope/__init__.py,sha256=Gg4nRMgnge-uYVd-_LKoZwf7qZl0bzKL9CxOqiIZp0A,8686
+sqlscope/_native.pyd,sha256=LnR5_g6oV8FQaS7wQ-L9wRFkhH0e-I41MYlfzujNamY,16678912
+sqlscope/_native.pyi,sha256=ucOBAAwzGXujAw69NXvl3sJagS4BuNe0v_dBNVDmiCM,1443
+sqlscope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlscope_rs-0.1.0.dist-info/METADATA,sha256=7CmBd7jtovbZJG8EDclKNm7z6BxRp3sb6ChknDeFhgk,1188
+sqlscope_rs-0.1.0.dist-info/WHEEL,sha256=xe4_tbg8wYdeh4O7nLbnWckzIQtCR4nODDgwke_TKy8,95
+sqlscope_rs-0.1.0.dist-info/sboms/sqlscope-python.cyclonedx.json,sha256=ZsG9PZRuQJjHkkZChjHtX6JjC8lOZyese8IkWxc0Me8,49224
+sqlscope_rs-0.1.0.dist-info/RECORD,,

sqlscope_rs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp39-abi3-win_amd64