sqlalchemy-load 0.2.0__py3-none-any.whl

sqlalchemy_load/__init__.py

@@ -0,0 +1,18 @@
+"""SQLAlchemy Load - Generate query optimization options from simplified syntax."""
+
+from .cache import ModelMetadata
+from .errors import FieldNotFoundError, ParseError, RelationshipNotFoundError
+from .generator import LoadGenerator
+from .parser import FieldSelection, parse_query_string
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "LoadGenerator",
+    "FieldSelection",
+    "ModelMetadata",
+    "parse_query_string",
+    "ParseError",
+    "FieldNotFoundError",
+    "RelationshipNotFoundError",
+]

sqlalchemy_load/cache.py

@@ -0,0 +1,20 @@
+"""Metadata caching utilities for SQLAlchemy models."""
+
+from dataclasses import dataclass
+from typing import Type
+
+
+@dataclass
+class ModelMetadata:
+    """Cached metadata for a SQLAlchemy model.
+
+    Attributes:
+        columns: Set of column names on the model
+        relationships: Set of relationship names on the model
+        primary_keys: Set of primary key column names
+        relationship_targets: Mapping of relationship name to target model class
+    """
+    columns: set[str]
+    relationships: set[str]
+    primary_keys: set[str]
+    relationship_targets: dict[str, Type]

sqlalchemy_load/errors.py

@@ -0,0 +1,19 @@
+"""Custom exceptions for sqlalchemy-load-generator."""
+
+
+class ParseError(Exception):
+    """Raised when the query string syntax is invalid."""
+
+    pass
+
+
+class FieldNotFoundError(Exception):
+    """Raised when a specified field does not exist on the model."""
+
+    pass
+
+
+class RelationshipNotFoundError(Exception):
+    """Raised when a specified relationship does not exist on the model."""
+
+    pass

sqlalchemy_load/generator.py

@@ -0,0 +1,196 @@
+"""LoadGenerator core class."""
+
+from __future__ import annotations
+
+from typing import Any, Type
+
+from sqlalchemy.orm import DeclarativeBase, load_only, selectinload
+
+from .cache import ModelMetadata
+from .errors import FieldNotFoundError, RelationshipNotFoundError
+from .parser import FieldSelection, parse_query_string_cached
+
+
+class LoadGenerator:
+    """
+    Generate SQLAlchemy query optimization options from simplified field selection syntax.
+
+    Example:
+        generator = LoadGenerator(Base)  # Pass DeclarativeBase
+        options = generator.generate(User, "{ id name posts { title } }")
+        stmt = select(User).options(*options)
+    """
+
+    def __init__(self, base_class: type[DeclarativeBase]):
+        """
+        Initialize LoadGenerator with a SQLAlchemy DeclarativeBase.
+
+        Preloads metadata for all models in the registry for better performance.
+
+        Args:
+            base_class: SQLAlchemy DeclarativeBase class
+
+        Raises:
+            TypeError: If base_class is not a valid DeclarativeBase
+        """
+        self._base_class = base_class
+        self._metadata_cache: dict[type, ModelMetadata] = {}
+        self._options_cache: dict[str, list[Any]] = {}
+        self._preload_all_metadata()
+
+    def _is_declarative_base(self, cls: type) -> bool:
+        """Check if class is a DeclarativeBase subclass."""
+        try:
+            registry = getattr(cls, 'registry', None)
+            return registry is not None and hasattr(registry, 'mappers')
+        except AttributeError:
+            return False
+
+    def _preload_all_metadata(self) -> None:
+        """Preload metadata for all models in the registry."""
+        if not self._is_declarative_base(self._base_class):
+            raise TypeError(
+                f"{self._base_class.__name__} is not a valid DeclarativeBase. "
+                "Please pass the Base class that your models inherit from."
+            )
+
+        for mapper in self._base_class.registry.mappers:
+            model_class = mapper.class_
+            self._metadata_cache[model_class] = ModelMetadata(
+                columns={col.key for col in mapper.columns},
+                relationships={rel.key for rel in mapper.relationships},
+                primary_keys={pk.key for pk in mapper.primary_key},
+                relationship_targets={
+                    rel.key: rel.mapper.class_
+                    for rel in mapper.relationships
+                }
+            )
+
+    def _get_metadata(self, model_class: type) -> ModelMetadata:
+        """Get cached metadata for a model."""
+        if model_class not in self._metadata_cache:
+            raise TypeError(
+                f"Model {model_class.__name__} not found in registry. "
+                f"Make sure it inherits from {self._base_class.__name__}."
+            )
+        return self._metadata_cache[model_class]
+
+    def generate(self, model_class: type, query_string: str) -> list[Any]:
+        """
+        Generate SQLAlchemy query options from field selection string.
+
+        Args:
+            model_class: SQLAlchemy model class to generate options for
+            query_string: Simplified field selection syntax, e.g. "{ id name posts { title } }"
+
+        Returns:
+            List of SQLAlchemy options that can be passed to .options(*options)
+
+        Raises:
+            ParseError: If the query string syntax is invalid
+            FieldNotFoundError: If a specified field doesn't exist
+            RelationshipNotFoundError: If a specified relationship doesn't exist
+        """
+        # Check cache
+        cache_key = self._make_cache_key(model_class, query_string)
+        if cache_key in self._options_cache:
+            return self._options_cache[cache_key]
+
+        # Parse and build
+        selection = parse_query_string_cached(query_string)
+        options = self._build_options(model_class, selection)
+
+        # Cache and return
+        self._options_cache[cache_key] = options
+        return options
+
+    def _make_cache_key(self, model_class: type, query_string: str) -> str:
+        """Create a cache key for the generate result."""
+        return f"{model_class.__module__}.{model_class.__name__}:{query_string}"
+
+    def _build_options(self, model_class: type, selection: FieldSelection) -> list[Any]:
+        """
+        Recursively build SQLAlchemy options from a FieldSelection.
+
+        Args:
+            model_class: The SQLAlchemy model class for this level
+            selection: Parsed field selection
+
+        Returns:
+            List of SQLAlchemy options
+        """
+        options = []
+        metadata = self._get_metadata(model_class)
+
+        # Validate and separate fields from relationships
+        valid_fields = set()
+        for field_name in selection.fields:
+            if field_name in metadata.relationships:
+                # User forgot to add braces for relationship
+                raise RelationshipNotFoundError(
+                    f"'{field_name}' is a relationship, use '{field_name} {{ ... }}' syntax"
+                )
+            if field_name not in metadata.columns:
+                raise FieldNotFoundError(
+                    f"Field '{field_name}' does not exist on {model_class.__name__}"
+                )
+            valid_fields.add(field_name)
+
+        # Validate relationships
+        for rel_name in selection.relationships:
+            if rel_name not in metadata.relationships:
+                if rel_name in metadata.columns:
+                    raise FieldNotFoundError(
+                        f"'{rel_name}' is a column, not a relationship"
+                    )
+                raise RelationshipNotFoundError(
+                    f"Relationship '{rel_name}' does not exist on {model_class.__name__}"
+                )
+
+        # 1. Build load_only for scalar fields (with primary key)
+        if valid_fields:
+            columns = self._ensure_primary_key(model_class, valid_fields, metadata)
+            options.append(load_only(*columns))
+
+        # 2. Build selectinload for relationships (recursive)
+        for rel_name, nested_selection in selection.relationships.items():
+            target_model = metadata.relationship_targets[rel_name]
+            rel_attr = getattr(model_class, rel_name)
+
+            nested_options = self._build_options(target_model, nested_selection)
+            loader = selectinload(rel_attr).options(*nested_options)
+            options.append(loader)
+
+        return options
+
+    def _ensure_primary_key(
+        self,
+        model_class: type,
+        field_names: set[str],
+        metadata: ModelMetadata
+    ) -> list[Any]:
+        """
+        Ensure primary key columns are included in load_only.
+
+        SQLAlchemy needs primary keys to properly construct objects.
+
+        Args:
+            model_class: SQLAlchemy model class
+            field_names: Set of field names to load
+            metadata: Cached model metadata
+
+        Returns:
+            List of column attributes for load_only
+        """
+        columns = []
+
+        # Add primary keys first
+        for pk_name in sorted(metadata.primary_keys):
+            columns.append(getattr(model_class, pk_name))
+
+        # Add other requested fields
+        for field_name in sorted(field_names):
+            if field_name not in metadata.primary_keys:
+                columns.append(getattr(model_class, field_name))
+
+        return columns

sqlalchemy_load/parser.py

@@ -0,0 +1,111 @@
+"""Parser for simplified field selection syntax."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any
+
+from .errors import ParseError
+
+
+@dataclass
+class FieldSelection:
+    """Represents a parsed field selection."""
+
+    fields: set[str]
+    relationships: dict[str, FieldSelection]
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, FieldSelection):
+            return False
+        return self.fields == other.fields and self.relationships == other.relationships
+
+
+def parse_query_string(query_string: str) -> FieldSelection:
+    """
+    Parse a simplified field selection syntax.
+
+    Args:
+        query_string: Field selection like "{ id name posts { title } }"
+
+    Returns:
+        FieldSelection with fields and nested relationships
+
+    Raises:
+        ParseError: If the syntax is invalid
+    """
+    tokens = _tokenize(query_string)
+    if not tokens:
+        raise ParseError("Empty query string")
+
+    result, _ = _parse_selection(tokens, 0)
+    return result
+
+
+def _tokenize(query_string: str) -> list[str]:
+    """Tokenize the query string into meaningful tokens."""
+    # Match braces, identifiers, and skip whitespace/commas
+    pattern = r'(\{|\}|[a-zA-Z_][a-zA-Z0-9_]*)'
+    tokens = re.findall(pattern, query_string)
+    return tokens
+
+
+def _parse_selection(tokens: list[str], index: int) -> tuple[FieldSelection, int]:
+    """
+    Parse a selection set starting at the given index.
+
+    Returns:
+        Tuple of (FieldSelection, next_index)
+    """
+    if index >= len(tokens) or tokens[index] != '{':
+        raise ParseError(f"Expected '{{' at position {index}")
+
+    index += 1  # Skip opening brace
+
+    fields: set[str] = set()
+    relationships: dict[str, FieldSelection] = {}
+
+    while index < len(tokens) and tokens[index] != '}':
+        token = tokens[index]
+
+        if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', token):
+            raise ParseError(f"Invalid token '{token}' at position {index}")
+
+        # Look ahead to see if this is a relationship (followed by {)
+        if index + 1 < len(tokens) and tokens[index + 1] == '{':
+            # It's a relationship
+            nested_selection, index = _parse_selection(tokens, index + 1)
+            relationships[token] = nested_selection
+        else:
+            # It's a field
+            fields.add(token)
+            index += 1
+
+    if index >= len(tokens):
+        raise ParseError("Missing closing brace '}'")
+
+    # index is now at the closing brace
+    index += 1  # Skip closing brace
+
+    if not fields and not relationships:
+        raise ParseError("Empty selection set")
+
+    return FieldSelection(fields=fields, relationships=relationships), index
+
+
+@lru_cache(maxsize=None)
+def parse_query_string_cached(query_string: str) -> FieldSelection:
+    """
+    Parse and cache the result. Queries are often repeated.
+
+    Args:
+        query_string: Field selection like "{ id name posts { title } }"
+
+    Returns:
+        FieldSelection with fields and nested relationships
+    """
+    return parse_query_string(query_string)
+
+

sqlalchemy_load-0.2.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-load
+Version: 0.2.0
+Summary: Generate SQLAlchemy query optimization options from simplified field selection syntax
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SQLAlchemy Load Generator
+
+Generate SQLAlchemy query optimization options (`selectinload` + `load_only`) from simplified field selection syntax.
+
+## Why This Library?
+
+SQLAlchemy's query options (`selectinload`, `joinedload`, `load_only`) are powerful but **painful to write**, especially with nested relationships.
+
+### The Problem
+
+**1. Verbose nested syntax**
+
+```python
+# Loading User -> Posts -> Comments requires deep nesting
+stmt = select(User).options(
+    selectinload(User.posts).options(
+        load_only(Post.id, Post.title),
+        selectinload(Post.comments).options(
+            load_only(Comment.id, Comment.content)
+        )
+    )
+)
+```
+
+**2. Coupled with query logic**
+
+You must decide what to load at query time, mixing data requirements with query construction. Different API endpoints need different loading strategies, leading to duplicated query code.
+
+**3. Dynamic composition is awkward**
+
+```python
+# Conditionally adding options requires extra logic
+options = []
+if need_posts:
+    options.append(selectinload(User.posts))
+if need_comments:
+    options.append(selectinload(User.posts).selectinload(Post.comments))
+stmt = select(User).options(*options)
+```
+
+**4. Easy to cause N+1 or over-fetching**
+
+- Forget `selectinload` → N+1 queries
+- Load unnecessary fields → wasted memory
+
+### The Solution
+
+This library provides a **declarative syntax** similar to GraphQL:
+
+```python
+# Before: verbose, nested, error-prone
+stmt = select(User).options(
+    selectinload(User.posts).options(
+        load_only(Post.id, Post.title),
+        selectinload(Post.comments).options(
+            load_only(Comment.id, Comment.content)
+        )
+    )
+)
+
+# After: clean, declarative, optimized
+generator = LoadGenerator(Base)
+options = generator.generate(User, "{ id name posts { title comments { content } } }")
+stmt = select(User).options(*options)
+```
+
+## Installation
+
+```bash
+pip install sqlalchemy-load
+```
+
+## Usage
+
+```python
+from sqlalchemy import select
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy_load import LoadGenerator
+
+# Initialize with your DeclarativeBase
+generator = LoadGenerator(Base)
+
+# Generate options using simplified syntax
+options = generator.generate(User, "{ id name posts { title comments { content } } }")
+
+# Use with SQLAlchemy query
+stmt = select(User).options(*options)
+```
+
+## Syntax
+
+The simplified syntax is similar to GraphQL but without commas:
+
+```
+{ field1 field2 relationship { nested_field } }
+```
+
+- Fields are space-separated
+- Relationships use `{ }` for nested selection
+- Commas are optional and ignored
+
+### Examples
+
+```python
+# Simple fields
+generator.generate(User, "{ id name email }")
+
+# Nested relationships
+generator.generate(User, "{ id posts { title content } }")
+
+# Deeply nested
+generator.generate(User, "{ id posts { title comments { content author } } }")
+
+# Multiple relationships
+generator.generate(User, "{ name posts { title } profile { bio } }")
+
+# Different models with same generator
+generator.generate(Post, "{ title content author { name } }")
+generator.generate(Comment, "{ content post { title } }")
+```
+
+## API
+
+### `LoadGenerator(base_class)`
+
+Create a generator with a SQLAlchemy `DeclarativeBase`. Preloads metadata for all models in the registry for optimal performance.
+
+```python
+from sqlalchemy.orm import DeclarativeBase
+
+class Base(DeclarativeBase):
+    pass
+
+generator = LoadGenerator(Base)
+```
+
+### `generator.generate(model_class, query_string) -> list`
+
+Generate SQLAlchemy options from a query string.
+
+```python
+options = generator.generate(User, "{ id name posts { title } }")
+stmt = select(User).options(*options)
+```
+
+## Features
+
+- **Preloaded metadata**: All model metadata is cached at initialization for fast lookups
+- **Result caching**: Same query returns cached result, avoiding redundant computation
+- **Parse caching**: Query string parsing is cached with `lru_cache`
+- **Automatic primary key inclusion**: Primary keys are always included in `load_only`
+- **Relationship detection**: Automatically detects SQLAlchemy relationships
+- **Nested loading**: Recursively generates `selectinload` with nested `load_only`
+- **Error handling**: Clear errors for invalid fields, relationships, or syntax
+
+## Error Handling
+
+```python
+from sqlalchemy_load import (
+    LoadGenerator,
+    ParseError,
+    FieldNotFoundError,
+    RelationshipNotFoundError,
+)
+
+generator = LoadGenerator(Base)
+
+# Syntax error
+try:
+    generator.generate(User, "{ id name")  # Missing closing brace
+except ParseError as e:
+    print(f"Syntax error: {e}")
+
+# Field doesn't exist
+try:
+    generator.generate(User, "{ nonexistent }")
+except FieldNotFoundError as e:
+    print(f"Field not found: {e}")
+
+# Relationship doesn't exist
+try:
+    generator.generate(User, "{ notarelationship { id } }")
+except RelationshipNotFoundError as e:
+    print(f"Relationship not found: {e}")
+```
+
+## Requirements
+
+- Python >= 3.10
+- SQLAlchemy >= 2.0
+
+## License
+
+MIT

sqlalchemy_load-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sqlalchemy_load/__init__.py,sha256=uk-Mx4ToKl-xNWx5EeNjbPXp9GkaPgXhl8yFyoUP_24,493
+sqlalchemy_load/cache.py,sha256=Zo4jIS5uSks4-r-e0wTTtdIi18Rztbnv3s7jPCjiERY,587
+sqlalchemy_load/errors.py,sha256=1ZQ1MrPu_mMCZ7BbILkuwxoYLYn20-ZrtUo4k_KzdhQ,404
+sqlalchemy_load/generator.py,sha256=Jpi-ZbLuuLMdf2DtARLOFydoDe6VBkqKmdx7FzVIoUI,7380
+sqlalchemy_load/parser.py,sha256=76QFlDoXCsKir6ODFd5rGRoy_djlQ0J4G8uM81LwXnY,3137
+sqlalchemy_load-0.2.0.dist-info/METADATA,sha256=85lShGZIIA1GYPUY_ojprpyhPd6GbdbWDfnNh8bg8Go,5338
+sqlalchemy_load-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sqlalchemy_load-0.2.0.dist-info/RECORD,,

sqlalchemy_load-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any