starspring 0.1.0__py3-none-any.whl

starspring/client/rest_client.py

@@ -0,0 +1,220 @@
+"""
+REST client utilities
+
+Provides Spring Boot-style RestTemplate for HTTP requests.
+"""
+
+from typing import Optional, Type, TypeVar, Dict, Any
+from pydantic import BaseModel
+import httpx
+
+
+T = TypeVar('T')
+
+
+class RestTemplate:
+    """
+    REST client template
+    
+    Similar to Spring Boot's RestTemplate.
+    Provides convenient methods for making HTTP requests with automatic
+    JSON serialization/deserialization and Pydantic model support.
+    
+    Example:
+        rest = RestTemplate(base_url="https://api.example.com")
+        user = rest.get("/users/1", response_model=User)
+        new_user = rest.post("/users", body=user_data, response_model=User)
+    """
+    
+    def __init__(
+        self,
+        base_url: str = "",
+        timeout: float = 30.0,
+        headers: Optional[Dict[str, str]] = None
+    ):
+        """
+        Initialize REST template
+        
+        Args:
+            base_url: Base URL for all requests
+            timeout: Request timeout in seconds
+            headers: Default headers for all requests
+        """
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        self.default_headers = headers or {}
+    
+    def _build_url(self, path: str) -> str:
+        """Build full URL from path"""
+        if path.startswith('http://') or path.startswith('https://'):
+            return path
+        return f"{self.base_url}{path}"
+    
+    def _merge_headers(self, headers: Optional[Dict[str, str]]) -> Dict[str, str]:
+        """Merge default headers with request headers"""
+        merged = self.default_headers.copy()
+        if headers:
+            merged.update(headers)
+        return merged
+    
+    def _serialize_body(self, body: Any) -> Dict[str, Any]:
+        """Serialize request body"""
+        if isinstance(body, BaseModel):
+            return body.model_dump()
+        elif hasattr(body, 'dict'):
+            return body.dict()
+        return body
+    
+    def _deserialize_response(
+        self,
+        response: httpx.Response,
+        response_model: Optional[Type[T]] = None
+    ) -> T:
+        """Deserialize response"""
+        if response_model:
+            data = response.json()
+            if isinstance(data, list):
+                return [response_model(**item) for item in data]  # type: ignore
+            return response_model(**data)
+        return response.json()  # type: ignore
+    
+    async def get(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None
+    ) -> T:
+        """
+        Make a GET request
+        
+        Args:
+            path: Request path
+            params: Query parameters
+            headers: Request headers
+            response_model: Pydantic model for response deserialization
+            
+        Returns:
+            Response data
+        """
+        url = self._build_url(path)
+        merged_headers = self._merge_headers(headers)
+        
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(url, params=params, headers=merged_headers)
+            response.raise_for_status()
+            return self._deserialize_response(response, response_model)
+    
+    async def post(
+        self,
+        path: str,
+        body: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None
+    ) -> T:
+        """
+        Make a POST request
+        
+        Args:
+            path: Request path
+            body: Request body
+            headers: Request headers
+            response_model: Pydantic model for response deserialization
+            
+        Returns:
+            Response data
+        """
+        url = self._build_url(path)
+        merged_headers = self._merge_headers(headers)
+        serialized_body = self._serialize_body(body) if body else None
+        
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(url, json=serialized_body, headers=merged_headers)
+            response.raise_for_status()
+            return self._deserialize_response(response, response_model)
+    
+    async def put(
+        self,
+        path: str,
+        body: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None
+    ) -> T:
+        """
+        Make a PUT request
+        
+        Args:
+            path: Request path
+            body: Request body
+            headers: Request headers
+            response_model: Pydantic model for response deserialization
+            
+        Returns:
+            Response data
+        """
+        url = self._build_url(path)
+        merged_headers = self._merge_headers(headers)
+        serialized_body = self._serialize_body(body) if body else None
+        
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.put(url, json=serialized_body, headers=merged_headers)
+            response.raise_for_status()
+            return self._deserialize_response(response, response_model)
+    
+    async def delete(
+        self,
+        path: str,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None
+    ) -> Optional[T]:
+        """
+        Make a DELETE request
+        
+        Args:
+            path: Request path
+            headers: Request headers
+            response_model: Pydantic model for response deserialization
+            
+        Returns:
+            Response data (if any)
+        """
+        url = self._build_url(path)
+        merged_headers = self._merge_headers(headers)
+        
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.delete(url, headers=merged_headers)
+            response.raise_for_status()
+            
+            # DELETE might not return content
+            if response.status_code == 204 or not response.content:
+                return None
+            
+            return self._deserialize_response(response, response_model)
+    
+    async def patch(
+        self,
+        path: str,
+        body: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        response_model: Optional[Type[T]] = None
+    ) -> T:
+        """
+        Make a PATCH request
+        
+        Args:
+            path: Request path
+            body: Request body
+            headers: Request headers
+            response_model: Pydantic model for response deserialization
+            
+        Returns:
+            Response data
+        """
+        url = self._build_url(path)
+        merged_headers = self._merge_headers(headers)
+        serialized_body = self._serialize_body(body) if body else None
+        
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.patch(url, json=serialized_body, headers=merged_headers)
+            response.raise_for_status()
+            return self._deserialize_response(response, response_model)

starspring/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration management components"""

starspring/config/environment.py

@@ -0,0 +1,81 @@
+"""
+Environment configuration
+
+Provides environment-based configuration support.
+"""
+
+import os
+from enum import Enum
+from typing import Optional
+
+
+class Profile(Enum):
+    """Application profiles"""
+    DEVELOPMENT = "dev"
+    PRODUCTION = "prod"
+    TEST = "test"
+
+
+class Environment:
+    """
+    Environment configuration manager
+    
+    Manages application profiles and environment-specific settings.
+    Similar to Spring Boot's @Profile and Environment.
+    """
+    
+    def __init__(self, active_profile: Optional[Profile] = None):
+        self._active_profile = active_profile or self._detect_profile()
+    
+    def _detect_profile(self) -> Profile:
+        """Detect active profile from environment"""
+        profile_str = os.environ.get('STARSPRING_PROFILE', 'dev').lower()
+        
+        for profile in Profile:
+            if profile.value == profile_str:
+                return profile
+        
+        return Profile.DEVELOPMENT
+    
+    @property
+    def active_profile(self) -> Profile:
+        """Get the active profile"""
+        return self._active_profile
+    
+    def is_development(self) -> bool:
+        """Check if running in development mode"""
+        return self._active_profile == Profile.DEVELOPMENT
+    
+    def is_production(self) -> bool:
+        """Check if running in production mode"""
+        return self._active_profile == Profile.PRODUCTION
+    
+    def is_test(self) -> bool:
+        """Check if running in test mode"""
+        return self._active_profile == Profile.TEST
+    
+    def get_env(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """Get environment variable"""
+        return os.environ.get(key, default)
+    
+    def set_profile(self, profile: Profile) -> None:
+        """Set the active profile"""
+        self._active_profile = profile
+
+
+# Global environment instance
+_environment: Optional[Environment] = None
+
+
+def get_environment() -> Environment:
+    """Get the global environment instance"""
+    global _environment
+    if _environment is None:
+        _environment = Environment()
+    return _environment
+
+
+def set_environment(env: Environment) -> None:
+    """Set the global environment instance"""
+    global _environment
+    _environment = env

starspring/config/properties.py

@@ -0,0 +1,146 @@
+"""
+Application properties management
+
+Provides configuration loading from YAML and properties files.
+"""
+
+import os
+import yaml
+from typing import Any, Dict, Optional
+from pathlib import Path
+
+
+class ApplicationProperties:
+    """
+    Application properties manager
+    
+    Loads configuration from application.yaml or application.properties files.
+    Similar to Spring Boot's application properties.
+    """
+    
+    def __init__(self, config_path: Optional[str] = None):
+        self._properties: Dict[str, Any] = {}
+        self._config_path = config_path
+        
+        if config_path:
+            self.load(config_path)
+    
+    def load(self, config_path: str) -> None:
+        """
+        Load configuration from a file
+        
+        Args:
+            config_path: Path to configuration file (YAML or properties)
+        """
+        path = Path(config_path)
+        
+        if not path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {config_path}")
+        
+        if path.suffix in ['.yaml', '.yml']:
+            self._load_yaml(path)
+        elif path.suffix == '.properties':
+            self._load_properties(path)
+        else:
+            raise ValueError(f"Unsupported configuration file format: {path.suffix}")
+    
+    def _load_yaml(self, path: Path) -> None:
+        """Load YAML configuration"""
+        with open(path, 'r') as f:
+            data = yaml.safe_load(f)
+            if data:
+                self._properties = self._flatten_dict(data)
+    
+    def _load_properties(self, path: Path) -> None:
+        """Load properties file"""
+        with open(path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith('#'):
+                    if '=' in line:
+                        key, value = line.split('=', 1)
+                        self._properties[key.strip()] = value.strip()
+    
+    def _flatten_dict(self, d: Dict, parent_key: str = '', sep: str = '.') -> Dict:
+        """Flatten nested dictionary with dot notation"""
+        items = []
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+            if isinstance(v, dict):
+                items.extend(self._flatten_dict(v, new_key, sep=sep).items())
+            else:
+                items.append((new_key, v))
+        return dict(items)
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a property value
+        
+        Args:
+            key: Property key (supports dot notation)
+            default: Default value if key not found
+            
+        Returns:
+            Property value or default
+        """
+        # Check environment variable override
+        env_key = key.upper().replace('.', '_')
+        env_value = os.environ.get(env_key)
+        if env_value is not None:
+            return env_value
+        
+        return self._properties.get(key, default)
+    
+    def get_int(self, key: str, default: int = 0) -> int:
+        """Get property as integer"""
+        value = self.get(key, default)
+        return int(value) if value is not None else default
+    
+    def get_bool(self, key: str, default: bool = False) -> bool:
+        """Get property as boolean"""
+        value = self.get(key, default)
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.lower() in ('true', 'yes', '1', 'on')
+        return bool(value)
+    
+    def get_list(self, key: str, default: list = None) -> list:
+        """Get property as list"""
+        value = self.get(key, default or [])
+        if isinstance(value, list):
+            return value
+        if isinstance(value, str):
+            return [item.strip() for item in value.split(',')]
+        return default or []
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set a property value"""
+        self._properties[key] = value
+    
+    def get_all(self) -> Dict[str, Any]:
+        """Get all properties"""
+        return self._properties.copy()
+
+
+# Global properties instance
+_app_properties: Optional[ApplicationProperties] = None
+
+
+def get_properties() -> ApplicationProperties:
+    """Get the global application properties instance"""
+    global _app_properties
+    if _app_properties is None:
+        _app_properties = ApplicationProperties()
+    return _app_properties
+
+
+def set_properties(properties: ApplicationProperties) -> None:
+    """Set the global application properties instance"""
+    global _app_properties
+    _app_properties = properties
+
+
+def get_property(key: str, default: Any = None) -> Any:
+    """Convenience function to get a property"""
+    return get_properties().get(key, default)

starspring/core/__init__.py

@@ -0,0 +1 @@
+"""Core framework components"""

starspring/core/context.py

@@ -0,0 +1,180 @@
+"""
+Application context and dependency injection container
+
+Provides Spring Boot-style dependency injection with automatic component scanning
+and dependency resolution.
+"""
+
+from typing import Dict, Any, Type, TypeVar, Optional, Callable, get_type_hints
+import inspect
+from enum import Enum
+
+
+T = TypeVar('T')
+
+
+class BeanScope(Enum):
+    """Bean scope types"""
+    SINGLETON = "singleton"
+    PROTOTYPE = "prototype"
+
+
+class BeanDefinition:
+    """Metadata for a registered bean"""
+    
+    def __init__(
+        self,
+        bean_class: Type,
+        scope: BeanScope = BeanScope.SINGLETON,
+        factory: Optional[Callable] = None,
+        name: Optional[str] = None
+    ):
+        self.bean_class = bean_class
+        self.scope = scope
+        self.factory = factory
+        self.name = name or bean_class.__name__
+        self.instance: Optional[Any] = None
+
+
+class ApplicationContext:
+    """
+    Application context for managing beans and dependency injection
+    
+    Similar to Spring's ApplicationContext, this class manages the lifecycle
+    of components and handles dependency injection.
+    """
+    
+    def __init__(self):
+        self._beans: Dict[str, BeanDefinition] = {}
+        self._instances: Dict[str, Any] = {}
+        self._type_to_name: Dict[Type, str] = {}
+    
+    def register_bean(
+        self,
+        bean_class: Type[T],
+        scope: BeanScope = BeanScope.SINGLETON,
+        factory: Optional[Callable] = None,
+        name: Optional[str] = None
+    ) -> None:
+        """
+        Register a bean in the application context
+        
+        Args:
+            bean_class: The class to register
+            scope: Bean scope (singleton or prototype)
+            factory: Optional factory function to create the bean
+            name: Optional custom name for the bean
+        """
+        bean_name = name or bean_class.__name__
+        bean_def = BeanDefinition(bean_class, scope, factory, bean_name)
+        self._beans[bean_name] = bean_def
+        self._type_to_name[bean_class] = bean_name
+    
+    def get_bean(self, bean_class: Type[T], name: Optional[str] = None) -> T:
+        """
+        Get a bean instance from the context
+        
+        Args:
+            bean_class: The class type to retrieve
+            name: Optional bean name
+            
+        Returns:
+            Instance of the requested bean
+            
+        Raises:
+            ValueError: If bean is not registered
+        """
+        bean_name = name or self._type_to_name.get(bean_class)
+        
+        if not bean_name or bean_name not in self._beans:
+            raise ValueError(f"No bean registered for {bean_class.__name__}")
+        
+        bean_def = self._beans[bean_name]
+        
+        # For singleton scope, return cached instance
+        if bean_def.scope == BeanScope.SINGLETON:
+            if bean_def.instance is None:
+                bean_def.instance = self._create_bean(bean_def)
+            return bean_def.instance
+        
+        # For prototype scope, create new instance each time
+        return self._create_bean(bean_def)
+    
+    def _create_bean(self, bean_def: BeanDefinition) -> Any:
+        """
+        Create a bean instance with dependency injection
+        
+        Args:
+            bean_def: Bean definition
+            
+        Returns:
+            New instance of the bean with dependencies injected
+        """
+        # Use factory if provided
+        if bean_def.factory:
+            return bean_def.factory()
+        
+        # Get constructor parameters
+        sig = inspect.signature(bean_def.bean_class.__init__)
+        params = {}
+        
+        # Get type hints for constructor
+        try:
+            type_hints = get_type_hints(bean_def.bean_class.__init__)
+        except Exception:
+            type_hints = {}
+        
+        # Inject dependencies
+        for param_name, param in sig.parameters.items():
+            if param_name == 'self':
+                continue
+            
+            # Get the type annotation
+            param_type = type_hints.get(param_name)
+            
+            if param_type and param_type in self._type_to_name:
+                # Recursively get the dependency
+                params[param_name] = self.get_bean(param_type)
+            elif param.default != inspect.Parameter.empty:
+                # Use default value if available
+                params[param_name] = param.default
+        
+        # Create instance with injected dependencies
+        return bean_def.bean_class(**params)
+    
+    def has_bean(self, bean_class: Type, name: Optional[str] = None) -> bool:
+        """Check if a bean is registered"""
+        bean_name = name or self._type_to_name.get(bean_class)
+        return bean_name is not None and bean_name in self._beans
+    
+    def get_all_beans(self) -> Dict[str, Any]:
+        """Get all singleton bean instances"""
+        result = {}
+        for name, bean_def in self._beans.items():
+            if bean_def.scope == BeanScope.SINGLETON:
+                result[name] = self.get_bean(bean_def.bean_class, name)
+        return result
+    
+    def clear(self) -> None:
+        """Clear all beans from the context"""
+        self._beans.clear()
+        self._instances.clear()
+        self._type_to_name.clear()
+
+
+# Global application context instance
+_app_context: Optional[ApplicationContext] = None
+
+
+def get_application_context() -> ApplicationContext:
+    """Get the global application context"""
+    global _app_context
+    if _app_context is None:
+        _app_context = ApplicationContext()
+    return _app_context
+
+
+def set_application_context(context: ApplicationContext) -> None:
+    """Set the global application context"""
+    global _app_context
+    _app_context = context

starspring/core/controller.py

@@ -0,0 +1,47 @@
+"""
+Base controller class
+
+Provides common functionality for all controllers.
+"""
+
+from typing import Optional
+from starlette.requests import Request
+
+
+class BaseController:
+    """
+    Base class for all controllers
+    
+    Provides access to common utilities and request context.
+    Similar to Spring Boot's base controller pattern.
+    """
+    
+    def __init__(self):
+        self._request: Optional[Request] = None
+    
+    @property
+    def request(self) -> Optional[Request]:
+        """Get the current request object"""
+        return self._request
+    
+    def set_request(self, request: Request) -> None:
+        """Set the current request object (called by framework)"""
+        self._request = request
+    
+    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Get a request header value"""
+        if self._request:
+            return self._request.headers.get(name, default)
+        return default
+    
+    def get_query_param(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Get a query parameter value"""
+        if self._request:
+            return self._request.query_params.get(name, default)
+        return default
+    
+    def get_path_param(self, name: str) -> Optional[str]:
+        """Get a path parameter value"""
+        if self._request:
+            return self._request.path_params.get(name)
+        return None