semolina 0.3.0__tar.gz

semolina-0.3.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.3
+Name: semolina
+Version: 0.3.0
+Summary: A Pythonic ORM for querying data warehouse semantic views (Snowflake, Databricks)
+Author: Anentropic
+Author-email: Anentropic <ego@anentropic.com>
+Requires-Dist: adbc-poolhouse>=1.2.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: sphinx-autobuild[dev]>=2025.8.25
+Requires-Dist: semolina[snowflake,databricks] ; extra == 'all'
+Requires-Dist: databricks-sql-connector[pyarrow]>=4.2.5 ; extra == 'databricks'
+Requires-Dist: adbc-poolhouse[snowflake] ; extra == 'snowflake'
+Requires-Dist: snowflake-connector-python>=4.3.0 ; extra == 'snowflake'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/anentropic/semolina
+Project-URL: Documentation, https://anentropic.github.io/semolina/
+Project-URL: Repository, https://github.com/anentropic/semolina
+Project-URL: Issues, https://github.com/anentropic/semolina/issues
+Project-URL: Changelog, https://anentropic.github.io/semolina/changelog/
+Provides-Extra: all
+Provides-Extra: databricks
+Provides-Extra: snowflake
+Description-Content-Type: text/markdown
+
+# Semolina
+
+A Python "OAM" (Object Analytics Model) for data warehouse Semantic Layer backends.

semolina-0.3.0/README.md

@@ -0,0 +1,3 @@
+# Semolina
+
+A Python "OAM" (Object Analytics Model) for data warehouse Semantic Layer backends.

semolina-0.3.0/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "semolina"
+version = "0.3.0"
+description = "A Pythonic ORM for querying data warehouse semantic views (Snowflake, Databricks)"
+readme = "README.md"
+authors = [
+    { name = "Anentropic", email = "ego@anentropic.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "adbc-poolhouse>=1.2.0",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "jinja2>=3.1.0",
+    "sphinx-autobuild[dev]>=2025.8.25",
+]
+
+[project.scripts]
+semolina = "semolina.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/anentropic/semolina"
+Documentation = "https://anentropic.github.io/semolina/"
+Repository = "https://github.com/anentropic/semolina"
+Issues = "https://github.com/anentropic/semolina/issues"
+Changelog = "https://anentropic.github.io/semolina/changelog/"
+
+[project.optional-dependencies]
+databricks = [
+    # Databricks ADBC driver is Foundry-distributed (not on PyPI).
+    # Keep databricks-sql-connector as fallback for non-ADBC usage.
+    "databricks-sql-connector[pyarrow]>=4.2.5",
+]
+snowflake = [
+    "adbc-poolhouse[snowflake]",
+    # SnowflakeEngine still uses snowflake-connector-python directly.
+    "snowflake-connector-python>=4.3.0",
+]
+all = [
+    "semolina[snowflake,databricks]",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.38.0",
+    "ipython>=9.10.0",
+    "pdbpp>=0.12.0.post1",
+    "pydantic-settings>=2.7.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=6.0.0",
+    "pytest-xdist>=3.6.0",
+    "ruff>=0.15.1",
+    "syrupy>=5.1.0",
+]
+docs = [
+    "sphinx>=8.0",
+    "shibuya>=2025.1.1",
+    "sphinx-autoapi>=3.6.0",
+    "sphinx-design>=0.6.0",
+    "sphinx-copybutton>=0.5.2",
+]
+
+[tool.basedpyright]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+include = ["src", "tests"]
+# Tests legitimately access private members (_metrics, _fields, etc.) for validation
+reportPrivateUsage = false
+# Field.__eq__ and __ne__ intentionally return Q objects instead of bool for query DSL
+reportIncompatibleMethodOverride = false
+# Field, Metric, Dimension, Fact are Generic[T] descriptors. Unsubscripted usage (e.g.
+# revenue = Metric()) is valid when the type parameter is irrelevant to the usage context
+# (tests, doctests, example models). Python 3.13 TypeVar defaults (PEP 696) would resolve
+# this at the language level; for 3.11/3.12 we suppress the cascade of Unknown errors.
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false
+# Lambda parameters in MagicMock.side_effect can't be annotated without wrapper function
+reportUnknownLambdaType = false
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "TCH", "D"]
+ignore = [
+    "D1",    # don't require docstrings everywhere
+    "D202",  # allow blank line after docstring (common in tests)
+    "D203",  # conflicts with D211 (no blank line before class docstring)
+    "D212",  # conflicts with D213 (multiline summary on second line)
+    "D401",  # imperative mood is awkward for dunder methods
+    "D413",  # blank line after last section not required
+]
+
+[tool.uv.workspace]
+members = ["semolina-jaffle-shop"]
+
+[tool.uv.sources]
+semolina = { workspace = true }
+
+[tool.pytest.ini_options]
+addopts = [
+    "-v",
+    "--doctest-modules",
+    "--doctest-continue-on-failure",
+]
+doctest_optionflags = ["ELLIPSIS", "NORMALIZE_WHITESPACE"]
+testpaths = ["tests", "src"]
+filterwarnings = [
+    "ignore::DeprecationWarning:syrupy.*",
+    "ignore:Field name .schema. in.*shadows an attribute in parent:UserWarning",
+]
+markers = [
+    "mock: Fast tests using MockEngine (no warehouse required)",
+    "unit: Pure unit tests with no external dependencies",
+    "warehouse: Integration tests against real warehouse (requires credentials)",
+    "snowflake: Snowflake-specific warehouse tests",
+    "databricks: Databricks-specific warehouse tests",
+]

semolina-0.3.0/src/semolina/__init__.py

@@ -0,0 +1,41 @@
+"""
+Semolina - A Pythonic ORM for querying data warehouse semantic views.
+
+Semolina provides typed model definitions and a fluent query API for
+Snowflake and Databricks semantic views.
+"""
+
+from .config import pool_from_config
+from .cursor import SemolinaCursor
+from .dialect import Dialect
+from .engines.base import SemolinaConnectionError, SemolinaViewNotFoundError
+from .fields import Dimension, Fact, Metric, NullsOrdering, OrderTerm
+from .filters import Predicate
+from .models import SemanticView
+from .pool import MockPool
+from .registry import get_engine, get_pool, register, unregister
+from .results import Row
+
+__version__ = __import__("importlib.metadata").metadata.version("semolina")
+
+__all__ = [
+    "__version__",
+    "Dialect",
+    "Dimension",
+    "Fact",
+    "Metric",
+    "MockPool",
+    "NullsOrdering",
+    "OrderTerm",
+    "Predicate",
+    "Row",
+    "SemolinaCursor",
+    "SemolinaConnectionError",
+    "SemolinaViewNotFoundError",
+    "SemanticView",
+    "get_engine",
+    "get_pool",
+    "pool_from_config",
+    "register",
+    "unregister",
+]

semolina-0.3.0/src/semolina/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m semolina`."""
+
+from semolina.cli import app
+
+if __name__ == "__main__":
+    app()

semolina-0.3.0/src/semolina/cli/__init__.py

@@ -0,0 +1,51 @@
+"""
+Semolina command-line interface.
+
+Entry point for the `semolina` CLI command. Registers subcommands
+for code generation and future tooling.
+"""
+
+import typer
+
+from .codegen import codegen
+
+app = typer.Typer(
+    name="semolina",
+    help="Semolina — warehouse-native semantic view tooling.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.command(
+    "codegen",
+    epilog=(
+        "[bold]Exit codes[/bold]\n\n"
+        "  [green]0[/green]  Success\n\n"
+        "  [yellow]1[/yellow]  Unexpected error\n\n"
+        "  [yellow]2[/yellow]  Invalid [bold]--backend[/bold] value (or omitted)\n\n"
+        "  [red]3[/red]  View not found in the warehouse\n\n"
+        "  [red]4[/red]  Connection or authentication failure"
+    ),
+)(codegen)
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        from semolina import __version__
+
+        typer.echo(f"semolina {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Semolina — warehouse-native semantic view tooling."""

semolina-0.3.0/src/semolina/cli/codegen.py

@@ -0,0 +1,119 @@
+"""Codegen subcommand: introspect warehouse semantic views and generate Python model classes."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.console import Console
+
+if TYPE_CHECKING:
+    from semolina.codegen.introspector import IntrospectedView
+    from semolina.engines.base import Engine
+
+# Diagnostics-only console: writes to stderr
+# NOTE: _stderr is module-level for error messages outside the command function.
+# Python source output uses typer.echo() so CliRunner captures it correctly.
+_stderr = Console(file=sys.stderr, stderr=True)
+
+# Exit code constants for scripted callers.
+# Note: Typer also uses exit code 2 for missing required arguments (fires earlier).
+# EXIT_INVALID_BACKEND=2 fires when --backend value is provided but unrecognized.
+EXIT_INVALID_BACKEND = 2
+EXIT_VIEW_NOT_FOUND = 3
+EXIT_CONNECTION_ERROR = 4
+
+
+def _resolve_backend(backend_spec: str) -> Engine:
+    """
+    Resolve a backend specifier string to an Engine instance.
+
+    Recognises the shorthand aliases ``'snowflake'`` and ``'databricks'``, and
+    also accepts any fully-qualified ``dotted.path.ClassName`` string which is
+    dynamically imported and instantiated with no arguments.
+
+    Args:
+        backend_spec: One of ``'snowflake'``, ``'databricks'``, or a dotted
+            import path such as ``'mypackage.backends.CustomEngine'``.
+
+    Returns:
+        Engine: An instantiated engine ready for introspection calls.
+
+    Raises:
+        typer.BadParameter: If the specifier is not recognised or cannot be
+            imported.
+    """
+    if backend_spec == "snowflake":
+        from semolina.engines.snowflake import SnowflakeEngine
+        from semolina.testing.credentials import SnowflakeCredentials
+
+        creds = SnowflakeCredentials.load()
+        params = creds.model_dump(by_alias=True)
+        params["password"] = creds.password.get_secret_value()
+        return SnowflakeEngine(**params)
+    elif backend_spec == "databricks":
+        from semolina.engines.databricks import DatabricksEngine
+        from semolina.testing.credentials import DatabricksCredentials
+
+        creds = DatabricksCredentials.load()
+        params = creds.model_dump(by_alias=True)
+        params["access_token"] = creds.access_token.get_secret_value()
+        return DatabricksEngine(**params)
+    else:
+        import importlib
+
+        module_path, _, class_name = backend_spec.rpartition(".")
+        if not module_path:
+            raise typer.BadParameter(
+                f"Unknown backend {backend_spec!r}. "
+                "Use 'snowflake', 'databricks', or a dotted import path."
+            )
+        try:
+            module = importlib.import_module(module_path)
+            cls = getattr(module, class_name)
+            return cls()  # type: ignore[no-any-return]
+        except (ImportError, AttributeError) as e:
+            raise typer.BadParameter(f"Cannot import backend {backend_spec!r}: {e}") from e
+
+
+def codegen(
+    views: Annotated[
+        list[str],
+        typer.Argument(help="Schema-qualified view names (e.g. my_schema.my_view)"),
+    ],
+    backend: Annotated[
+        str,
+        typer.Option(
+            "--backend", "-b", help="Backend: snowflake, databricks, or dotted.path.ClassName"
+        ),
+    ],
+) -> None:
+    """Introspect warehouse semantic views and generate Semolina model classes."""
+    from semolina.engines.base import SemolinaConnectionError, SemolinaViewNotFoundError
+
+    try:
+        engine = _resolve_backend(backend)
+    except typer.BadParameter as e:
+        _stderr.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=EXIT_INVALID_BACKEND) from e
+
+    introspected_views: list[IntrospectedView] = []
+    for view_name in views:
+        try:
+            introspected = engine.introspect(view_name)
+            introspected_views.append(introspected)
+        except SemolinaViewNotFoundError as e:
+            _stderr.print(f"[bold red]Error:[/bold red] {e}")
+            raise typer.Exit(code=EXIT_VIEW_NOT_FOUND) from e
+        except SemolinaConnectionError as e:
+            _stderr.print(f"[bold red]Error:[/bold red] {e}")
+            raise typer.Exit(code=EXIT_CONNECTION_ERROR) from e
+        except RuntimeError as e:
+            _stderr.print(f"[bold red]Error:[/bold red] {e}")
+            raise typer.Exit(code=1) from e
+
+    from semolina.codegen.python_renderer import render_and_format
+
+    source = render_and_format(introspected_views)
+    typer.echo(source)

semolina-0.3.0/src/semolina/cli/utils.py

@@ -0,0 +1,98 @@
+"""
+CLI utility functions for Semolina codegen commands.
+
+Provides path resolution, stderr console creation, and progress helpers.
+"""
+
+from __future__ import annotations
+
+import glob as _glob
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+
+def make_stderr_console(verbose: bool = False) -> Console:
+    """
+    Create a Rich Console writing to stderr for diagnostic output.
+
+    Args:
+        verbose: If True, suppress no output (show everything). If False, only
+            show warnings and errors.
+
+    Returns:
+        Configured Rich Console for stderr.
+    """
+    return Console(file=sys.stderr, stderr=True)
+
+
+def resolve_input_paths(input_spec: str, stderr: Console) -> list[Path]:
+    """
+    Resolve an input specification to a list of Python file paths.
+
+    Handles three forms:
+    - Explicit file path: must exist, returned as single-element list
+    - Directory path: scanned recursively for *.py files
+    - Glob pattern: expanded via pathlib from cwd
+
+    Fails immediately (raises SystemExit via typer.Exit) if an explicit
+    file path doesn't exist or can't be read.
+
+    Args:
+        input_spec: File path, directory path, or glob pattern string.
+        stderr: Rich Console for diagnostic messages.
+
+    Returns:
+        Sorted list of resolved .py file paths.
+
+    Raises:
+        typer.Exit: If an explicit path doesn't exist or is unreadable.
+    """
+    path = Path(input_spec)
+
+    # If input contains glob special characters, treat as glob regardless of suffix.
+    # This handles patterns like '/path/to/*.py' which have suffix '.py' but aren't
+    # explicit file paths.
+    _GLOB_CHARS = {"*", "?", "["}
+    is_glob = any(ch in input_spec for ch in _GLOB_CHARS)
+
+    if not is_glob:
+        # Explicit file: must exist
+        if path.suffix == ".py":
+            if not path.exists():
+                stderr.print(
+                    f"[bold red]Error:[/bold red] File not found: [cyan]{path}[/cyan]\n"
+                    f"  Check the path and try again."
+                )
+                raise typer.Exit(code=1)
+            if not path.is_file():
+                stderr.print(f"[bold red]Error:[/bold red] Not a file: [cyan]{path}[/cyan]")
+                raise typer.Exit(code=1)
+            return [path.resolve()]
+
+        # Directory: scan recursively for *.py files
+        if path.is_dir():
+            files = sorted(path.rglob("*.py"))
+            # Exclude __pycache__ and hidden directories
+            files = [
+                f
+                for f in files
+                if "__pycache__" not in f.parts and not any(p.startswith(".") for p in f.parts)
+            ]
+            return files
+
+        # Explicit directory path that doesn't exist: fail immediately
+        if not path.suffix and not path.exists():
+            stderr.print(
+                f"[bold red]Error:[/bold red] Directory not found: [cyan]{path}[/cyan]\n"
+                f"  Check the path and try again."
+            )
+            raise typer.Exit(code=1)
+
+    # Glob pattern: expand via glob.glob which handles both relative and absolute patterns.
+    # Path.cwd().glob() raises NotImplementedError for absolute patterns in Python 3.14+.
+    matched = sorted(Path(m) for m in _glob.glob(input_spec, recursive=True))
+    py_files = [f for f in matched if f.suffix == ".py" and f.is_file()]
+    return py_files

semolina-0.3.0/src/semolina/codegen/__init__.py

@@ -0,0 +1 @@
+"""Semolina code generation engine."""

semolina-0.3.0/src/semolina/codegen/introspector.py

@@ -0,0 +1,65 @@
+"""
+Intermediate representation dataclasses for reverse codegen introspection.
+
+Defines the frozen dataclasses that form the contract between warehouse
+introspection engines and the Python code renderer.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class IntrospectedField:
+    """
+    Intermediate representation of a single field from an introspected semantic view.
+
+    Produced by warehouse introspection engines and consumed by the Python code
+    renderer to generate Metric, Dimension, or Fact field declarations.
+
+    Attributes:
+        name: Python attribute name for the field (e.g., 'revenue', 'country').
+            Always lowercase (Pythonic). For Snowflake views, this is the
+            warehouse column name lowercased.
+        field_type: Semantic role of the field: 'metric', 'dimension', or 'fact'.
+        data_type: Python annotation string (e.g., 'int', 'str', 'datetime.date'),
+            or None if the SQL type has no clean Python equivalent (triggers a
+            TODO comment in the generated output).
+        description: Human-readable description of the field. Defaults to empty
+            string if the warehouse provides no description metadata.
+        source_name: Original warehouse column name when it differs from what
+            ``normalize_identifier`` would produce. Set only when the column
+            was created with a quoted identifier (e.g., ``"order_id"`` in
+            Snowflake, stored as lowercase). None for standard columns that
+            round-trip correctly through normalize_identifier.
+    """
+
+    name: str
+    field_type: Literal["metric", "dimension", "fact"]
+    data_type: str | None
+    description: str = ""
+    source_name: str | None = None
+
+
+@dataclass(frozen=True)
+class IntrospectedView:
+    """
+    Intermediate representation of a semantic view returned by engine introspection.
+
+    Produced by Engine.introspect() and consumed by the Python code renderer to
+    generate a complete SemanticView subclass.
+
+    Attributes:
+        view_name: Warehouse identifier for the view (e.g., 'sales_view'). Used
+            as the ``view=`` parameter in the generated SemanticView subclass.
+        class_name: Python class name to use in the generated code (e.g., 'Sales').
+            Derived from view_name by the introspection layer (snake_case → PascalCase).
+        fields: All fields discovered in the view, in the order returned by the
+            warehouse API. Includes metrics, dimensions, and facts.
+    """
+
+    view_name: str
+    class_name: str
+    fields: list[IntrospectedField] = field(default_factory=list)