starspring 0.1.0__py3-none-any.whl

starspring/data/query_builder.py

@@ -0,0 +1,345 @@
+"""
+Query method parser and SQL generator
+
+Parses repository method names and generates SQL queries automatically.
+Similar to Spring Data JPA's query derivation.
+"""
+
+import re
+from typing import List, Tuple, Any, Optional, Type
+from enum import Enum
+
+
+class QueryOperation(Enum):
+    """Query operation types"""
+    FIND = "find"
+    COUNT = "count"
+    DELETE = "delete"
+    EXISTS = "exists"
+
+
+class QueryCondition(Enum):
+    """Query condition operators"""
+    EQUALS = ""
+    AND = "And"
+    OR = "Or"
+    GREATER_THAN = "GreaterThan"
+    LESS_THAN = "LessThan"
+    GREATER_THAN_EQUAL = "GreaterThanEqual"
+    LESS_THAN_EQUAL = "LessThanEqual"
+    LIKE = "Like"
+    CONTAINING = "Containing"
+    STARTING_WITH = "StartingWith"
+    ENDING_WITH = "EndingWith"
+    BETWEEN = "Between"
+    IN = "In"
+    NOT = "Not"
+    IS_NULL = "IsNull"
+    IS_NOT_NULL = "IsNotNull"
+    TRUE = "True"
+    FALSE = "False"
+
+
+class QueryPart:
+    """Represents a part of a query"""
+    
+    def __init__(
+        self,
+        field: str,
+        operator: QueryCondition,
+        connector: Optional[str] = None
+    ):
+        self.field = field
+        self.operator = operator
+        self.connector = connector  # AND or OR
+
+
+class ParsedQuery:
+    """Parsed query information"""
+    
+    def __init__(
+        self,
+        operation: QueryOperation,
+        parts: List[QueryPart],
+        order_by: Optional[List[Tuple[str, str]]] = None
+    ):
+        self.operation = operation
+        self.parts = parts
+        self.order_by = order_by or []
+
+
+class QueryMethodParser:
+    """
+    Parses repository method names into query components
+    
+    Supports patterns like:
+    - findByName
+    - findByEmailAndActive
+    - findByAgeGreaterThan
+    - findByNameContaining
+    - countByActive
+    - deleteByEmail
+    - existsByUsername
+    """
+    
+    # Regex patterns for parsing
+    OPERATION_PATTERN = r'^(find|count|delete|exists)By'
+    CONDITION_PATTERNS = {
+        'GreaterThanEqual': r'GreaterThanEqual',
+        'LessThanEqual': r'LessThanEqual',
+        'GreaterThan': r'GreaterThan',
+        'LessThan': r'LessThan',
+        'Containing': r'Containing',
+        'StartingWith': r'StartingWith',
+        'EndingWith': r'EndingWith',
+        'Between': r'Between',
+        'Like': r'Like',
+        'In': r'In',
+        'IsNull': r'IsNull',
+        'IsNotNull': r'IsNotNull',
+        'True': r'True',
+        'False': r'False',
+        'Not': r'Not',
+    }
+    
+    def parse(self, method_name: str) -> ParsedQuery:
+        """
+        Parse a repository method name into query components
+        
+        Args:
+            method_name: Method name to parse
+            
+        Returns:
+            ParsedQuery object
+            
+        Raises:
+            ValueError: If method name cannot be parsed
+        """
+        # Extract operation
+        operation_match = re.match(self.OPERATION_PATTERN, method_name)
+        if not operation_match:
+            raise ValueError(f"Invalid query method name: {method_name}")
+        
+        operation_str = operation_match.group(1)
+        operation = QueryOperation(operation_str)
+        
+        # Remove operation prefix
+        remainder = method_name[len(operation_match.group(0)):]
+        
+        # Check for OrderBy clause
+        order_by = []
+        if 'OrderBy' in remainder:
+            parts = remainder.split('OrderBy')
+            remainder = parts[0]
+            order_clause = parts[1]
+            order_by = self._parse_order_by(order_clause)
+        
+        # Parse conditions
+        query_parts = self._parse_conditions(remainder)
+        
+        return ParsedQuery(operation, query_parts, order_by)
+    
+    def _parse_conditions(self, condition_str: str) -> List[QueryPart]:
+        """Parse condition string into query parts"""
+        parts = []
+        
+        # Split by And/Or
+        tokens = re.split(r'(And|Or)', condition_str)
+        
+        current_connector = None
+        i = 0
+        while i < len(tokens):
+            token = tokens[i]
+            
+            if token in ['And', 'Or']:
+                current_connector = token.upper()
+                i += 1
+                continue
+            
+            if not token:
+                i += 1
+                continue
+            
+            # Parse this condition
+            field, operator = self._parse_single_condition(token)
+            parts.append(QueryPart(field, operator, current_connector))
+            
+            i += 1
+        
+        return parts
+    
+    def _parse_single_condition(self, condition: str) -> Tuple[str, QueryCondition]:
+        """Parse a single condition into field and operator"""
+        # Check for operators
+        for op_name, op_pattern in self.CONDITION_PATTERNS.items():
+            if condition.endswith(op_name):
+                field = condition[:-len(op_name)]
+                return self._camel_to_snake(field), QueryCondition[op_name.upper().replace('THAN', '_THAN')]
+        
+        # No operator means equals
+        return self._camel_to_snake(condition), QueryCondition.EQUALS
+    
+    def _parse_order_by(self, order_str: str) -> List[Tuple[str, str]]:
+        """Parse OrderBy clause"""
+        orders = []
+        parts = re.split(r'(And)', order_str)
+        
+        for part in parts:
+            if part == 'And' or not part:
+                continue
+            
+            # Check for Asc/Desc
+            if part.endswith('Desc'):
+                field = part[:-4]
+                direction = 'DESC'
+            elif part.endswith('Asc'):
+                field = part[:-3]
+                direction = 'ASC'
+            else:
+                field = part
+                direction = 'ASC'
+            
+            orders.append((self._camel_to_snake(field), direction))
+        
+        return orders
+    
+    def _camel_to_snake(self, name: str) -> str:
+        """Convert CamelCase to snake_case"""
+        s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
+        return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
+
+
+class SQLQueryGenerator:
+    """
+    Generates SQL queries from parsed query information
+    """
+    
+    def __init__(self, table_name: str):
+        self.table_name = table_name
+    
+    def generate(self, parsed_query: ParsedQuery) -> Tuple[str, List[str]]:
+        """
+        Generate SQL query from parsed query
+        
+        Args:
+            parsed_query: Parsed query information
+            
+        Returns:
+            Tuple of (SQL query string, list of parameter placeholders)
+        """
+        if parsed_query.operation == QueryOperation.FIND:
+            return self._generate_select(parsed_query)
+        elif parsed_query.operation == QueryOperation.COUNT:
+            return self._generate_count(parsed_query)
+        elif parsed_query.operation == QueryOperation.DELETE:
+            return self._generate_delete(parsed_query)
+        elif parsed_query.operation == QueryOperation.EXISTS:
+            return self._generate_exists(parsed_query)
+        
+        raise ValueError(f"Unsupported operation: {parsed_query.operation}")
+    
+    def _generate_select(self, parsed_query: ParsedQuery) -> Tuple[str, List[str]]:
+        """Generate SELECT query"""
+        sql = f"SELECT * FROM {self.table_name}"
+        params = []
+        
+        if parsed_query.parts:
+            where_clause, params = self._build_where_clause(parsed_query.parts)
+            sql += f" WHERE {where_clause}"
+        
+        if parsed_query.order_by:
+            order_parts = [f"{field} {direction}" for field, direction in parsed_query.order_by]
+            sql += f" ORDER BY {', '.join(order_parts)}"
+        
+        return sql, params
+    
+    def _generate_count(self, parsed_query: ParsedQuery) -> Tuple[str, List[str]]:
+        """Generate COUNT query"""
+        sql = f"SELECT COUNT(*) FROM {self.table_name}"
+        params = []
+        
+        if parsed_query.parts:
+            where_clause, params = self._build_where_clause(parsed_query.parts)
+            sql += f" WHERE {where_clause}"
+        
+        return sql, params
+    
+    def _generate_delete(self, parsed_query: ParsedQuery) -> Tuple[str, List[str]]:
+        """Generate DELETE query"""
+        sql = f"DELETE FROM {self.table_name}"
+        params = []
+        
+        if parsed_query.parts:
+            where_clause, params = self._build_where_clause(parsed_query.parts)
+            sql += f" WHERE {where_clause}"
+        
+        return sql, params
+    
+    def _generate_exists(self, parsed_query: ParsedQuery) -> Tuple[str, List[str]]:
+        """Generate EXISTS query"""
+        sql = f"SELECT EXISTS(SELECT 1 FROM {self.table_name}"
+        params = []
+        
+        if parsed_query.parts:
+            where_clause, params = self._build_where_clause(parsed_query.parts)
+            sql += f" WHERE {where_clause}"
+        
+        sql += ")"
+        return sql, params
+    
+    def _build_where_clause(self, parts: List[QueryPart]) -> Tuple[str, List[str]]:
+        """Build WHERE clause from query parts"""
+        conditions = []
+        params = []
+        
+        for part in parts:
+            condition, part_params = self._build_condition(part)
+            
+            if part.connector and conditions:
+                conditions.append(f" {part.connector} {condition}")
+            else:
+                conditions.append(condition)
+            
+            params.extend(part_params)
+        
+        return ''.join(conditions), params
+    
+    def _build_condition(self, part: QueryPart) -> Tuple[str, List[str]]:
+        """Build a single condition"""
+        field = part.field
+        operator = part.operator
+        
+        if operator == QueryCondition.EQUALS:
+            return f"{field} = ?", [field]
+        elif operator == QueryCondition.GREATER_THAN:
+            return f"{field} > ?", [field]
+        elif operator == QueryCondition.LESS_THAN:
+            return f"{field} < ?", [field]
+        elif operator == QueryCondition.GREATER_THAN_EQUAL:
+            return f"{field} >= ?", [field]
+        elif operator == QueryCondition.LESS_THAN_EQUAL:
+            return f"{field} <= ?", [field]
+        elif operator == QueryCondition.LIKE:
+            return f"{field} LIKE ?", [field]
+        elif operator == QueryCondition.CONTAINING:
+            return f"{field} LIKE ?", [field]  # Will add % in executor
+        elif operator == QueryCondition.STARTING_WITH:
+            return f"{field} LIKE ?", [field]  # Will add % in executor
+        elif operator == QueryCondition.ENDING_WITH:
+            return f"{field} LIKE ?", [field]  # Will add % in executor
+        elif operator == QueryCondition.BETWEEN:
+            return f"{field} BETWEEN ? AND ?", [field, field]
+        elif operator == QueryCondition.IN:
+            return f"{field} IN (?)", [field]
+        elif operator == QueryCondition.IS_NULL:
+            return f"{field} IS NULL", []
+        elif operator == QueryCondition.IS_NOT_NULL:
+            return f"{field} IS NOT NULL", []
+        elif operator == QueryCondition.TRUE:
+            return f"{field} = TRUE", []
+        elif operator == QueryCondition.FALSE:
+            return f"{field} = FALSE", []
+        elif operator == QueryCondition.NOT:
+            return f"{field} != ?", [field]
+        
+        raise ValueError(f"Unsupported operator: {operator}")

starspring/data/repository.py

@@ -0,0 +1,324 @@
+"""
+Repository pattern implementation
+
+Provides Spring Boot-style repository pattern for data access with automatic query generation.
+"""
+
+from typing import TypeVar, Generic, List, Optional, Any, Type
+from starspring.data.orm_gateway import get_orm_gateway
+import inspect
+import logging
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+
+class Repository(Generic[T]):
+    """
+    Generic repository base class
+    
+    Provides CRUD operations for entities.
+    Similar to Spring Data JPA's Repository interface.
+    
+    Example:
+        @Repository
+        class UserRepository(Repository[User]):
+            def find_by_email(self, email: str) -> Optional[User]:
+                # Custom query method
+                pass
+    """
+    
+    def __init__(self, entity_class: Type[T]):
+        """
+        Initialize repository
+        
+        Args:
+            entity_class: The entity class this repository manages
+        """
+        self.entity_class = entity_class
+        self._gateway_instance = None  # Lazy initialization
+    
+    @property
+    def _gateway(self):
+        """Lazy-load the ORM gateway"""
+        if self._gateway_instance is None:
+            self._gateway_instance = get_orm_gateway()
+        return self._gateway_instance
+    
+    async def save(self, entity: T) -> T:
+        """
+        Save an entity
+        
+        Args:
+            entity: Entity to save
+            
+        Returns:
+            Saved entity
+        """
+        return await self._gateway.save(entity)
+    
+    async def find_by_id(self, id: Any) -> Optional[T]:
+        """
+        Find an entity by ID
+        
+        Args:
+            id: Entity ID
+            
+        Returns:
+            Entity if found, None otherwise
+        """
+        return await self._gateway.find_by_id(self.entity_class, id)
+    
+    async def find_all(self) -> List[T]:
+        """
+        Find all entities
+        
+        Returns:
+            List of all entities
+        """
+        return await self._gateway.find_all(self.entity_class)
+    
+    async def delete(self, entity: T) -> None:
+        """
+        Delete an entity
+        
+        Args:
+            entity: Entity to delete
+        """
+        await self._gateway.delete(entity)
+    
+    async def delete_by_id(self, id: Any) -> bool:
+        """
+        Delete an entity by ID
+        
+        Args:
+            id: Entity ID
+            
+        Returns:
+            True if deleted, False if not found
+        """
+        entity = await self.find_by_id(id)
+        if entity:
+            await self.delete(entity)
+            return True
+        return False
+    
+    async def update(self, entity: T) -> T:
+        """
+        Update an entity
+        
+        Args:
+            entity: Entity to update
+            
+        Returns:
+            Updated entity
+        """
+        return await self._gateway.update(entity)
+    
+    async def exists(self, id: Any) -> bool:
+        """
+        Check if an entity exists
+        
+        Args:
+            id: Entity ID
+            
+        Returns:
+            True if exists, False otherwise
+        """
+        return await self._gateway.exists(self.entity_class, id)
+    
+    async def count(self) -> int:
+        """
+        Count all entities
+        
+        Returns:
+            Number of entities
+        """
+        entities = await self.find_all()
+        return len(entities)
+
+
+class CrudRepository(Repository[T]):
+    """
+    Alias for Repository
+    
+    Provides Spring Data JPA-style naming.
+    """
+    pass
+
+
+class StarRepository(Repository[T]):
+    """
+    StarSpring repository with additional batch operations and automatic query generation
+    
+    Extends the base Repository with:
+    - Batch operations for multiple entities
+    - Automatic query method execution (findBy*, countBy*, deleteBy*, existsBy*)
+    
+    Example:
+        @Repository
+        class UserRepository(StarRepository[User]):
+            # These methods are auto-implemented!
+            async def findByEmail(self, email: str) -> Optional[User]:
+                pass
+            
+            async def findByActive(self, active: bool) -> List[User]:
+                pass
+    """
+    
+    def __init__(self, entity_class: Type[T] = None):
+        """
+        Initialize StarRepository
+        
+        Args:
+            entity_class: Optional entity class. If not provided, will be extracted from generic type.
+        """
+        # If entity_class not provided, try to extract from generic type
+        if entity_class is None:
+            entity_class = self._extract_entity_class()
+        
+        # Call parent constructor
+        super().__init__(entity_class)
+    
+    def _extract_entity_class(self) -> Type[T]:
+        """
+        Extract entity class from generic type parameter
+        
+        Returns:
+            Entity class type
+        """
+        import typing
+        
+        # Get the class's __orig_bases__ to find the generic parameter
+        for base in getattr(self.__class__, '__orig_bases__', []):
+            # Check if this is a generic type
+            if hasattr(base, '__origin__') and hasattr(base, '__args__'):
+                # Get the first type argument (the entity class)
+                if base.__args__:
+                    return base.__args__[0]
+        
+        # Fallback: raise error if we can't determine entity class
+        raise ValueError(
+            f"Could not determine entity class for {self.__class__.__name__}. "
+            f"Please specify it as a generic parameter: class MyRepo(StarRepository[MyEntity])"
+        )
+    
+    def __getattribute__(self, name: str):
+        """
+        Magic method to intercept attribute access
+        
+        Automatically implements query methods based on method name.
+        """
+        # Get the attribute normally first
+        try:
+            attr = object.__getattribute__(self, name)
+            
+            # If it's a method and it's defined (not just 'pass'), return it
+            if callable(attr) and hasattr(attr, '__func__'):
+                # Check if method has actual implementation (more than just 'pass')
+                source = inspect.getsource(attr.__func__)
+                if 'pass' not in source or len(source.strip().split('\n')) > 3:
+                    return attr
+        except AttributeError:
+            pass
+        
+        # Check if this is a query method that should be auto-implemented
+        if name.startswith(('findBy', 'countBy', 'deleteBy', 'existsBy')):
+            logger.debug(f"Auto-implementing query method: {name}")
+            return self._create_query_method(name)
+        
+        # Default behavior for everything else
+        return object.__getattribute__(self, name)
+    
+    def _create_query_method(self, method_name: str):
+        """
+        Create a query method dynamically
+        
+        Args:
+            method_name: Name of the method (e.g., 'findByEmail')
+            
+        Returns:
+            Async function that executes the query
+        """
+        from starspring.data.query_builder import QueryMethodParser, SQLQueryGenerator, QueryOperation
+        
+        # Parse the method name
+        try:
+            parser = QueryMethodParser()
+            parsed_query = parser.parse(method_name)
+        except Exception as e:
+            logger.error(f"Failed to parse query method '{method_name}': {e}")
+            raise ValueError(f"Invalid query method name: {method_name}")
+        
+        # Get table name from entity metadata
+        if hasattr(self.entity_class, '_entity_metadata'):
+            table_name = self.entity_class._entity_metadata.table_name
+        else:
+            # Fallback: convert class name to snake_case
+            import re
+            name = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', self.entity_class.__name__)
+            table_name = re.sub('([a-z0-9])([A-Z])', r'\1_\2', name).lower()
+        
+        # Generate SQL
+        generator = SQLQueryGenerator(table_name)
+        sql, param_names = generator.generate(parsed_query)
+        
+        # Create the async function
+        async def query_executor(*args, **kwargs):
+            """Auto-generated query executor"""
+            # Build parameter dictionary
+            params = {}
+            for i, param_name in enumerate(param_names):
+                if i < len(args):
+                    params[param_name] = args[i]
+                elif param_name in kwargs:
+                    params[param_name] = kwargs[param_name]
+            
+            # Execute the query through the gateway
+            result = await self._gateway.execute_query(
+                sql,
+                params,
+                self.entity_class,
+                parsed_query.operation
+            )
+            
+            return result
+        
+        return query_executor
+    
+    async def save_all(self, entities: List[T]) -> List[T]:
+        """
+        Save multiple entities
+        
+        Args:
+            entities: List of entities to save
+            
+        Returns:
+            List of saved entities
+        """
+        result = []
+        for entity in entities:
+            saved = await self.save(entity)
+            result.append(saved)
+        return result
+    
+    async def delete_all(self, entities: List[T]) -> None:
+        """
+        Delete multiple entities
+        
+        Args:
+            entities: List of entities to delete
+        """
+        for entity in entities:
+            await self.delete(entity)
+    
+    async def delete_all_by_id(self, ids: List[Any]) -> None:
+        """
+        Delete multiple entities by ID
+        
+        Args:
+            ids: List of entity IDs
+        """
+        for id in ids:
+            await self.delete_by_id(id)