starspring 0.1.0__py3-none-any.whl

starspring/template/engine.py

@@ -0,0 +1,168 @@
+"""
+Template engine for rendering HTML templates
+
+Integrates Jinja2 with Spring Boot-style patterns.
+"""
+
+from typing import Dict, Any, Optional
+from pathlib import Path
+import os
+
+
+try:
+    from jinja2 import Environment, FileSystemLoader, select_autoescape, Template
+    JINJA2_AVAILABLE = True
+except ImportError:
+    JINJA2_AVAILABLE = False
+    Environment = None
+    FileSystemLoader = None
+
+
+class TemplateEngine:
+    """
+    Template rendering engine
+    
+    Wraps Jinja2 with Spring Boot-style configuration.
+    """
+    
+    def __init__(
+        self,
+        template_dir: str = "templates",
+        auto_reload: bool = True,
+        cache_size: int = 400
+    ):
+        """
+        Initialize template engine
+        
+        Args:
+            template_dir: Directory containing templates
+            auto_reload: Whether to reload templates on change
+            cache_size: Template cache size
+        """
+        if not JINJA2_AVAILABLE:
+            raise ImportError(
+                "Jinja2 is required for template rendering. "
+                "Install it with: pip install jinja2"
+            )
+        
+        self.template_dir = template_dir
+        
+        # Create template directory if it doesn't exist
+        Path(template_dir).mkdir(parents=True, exist_ok=True)
+        
+        # Initialize Jinja2 environment
+        self.env = Environment(
+            loader=FileSystemLoader(template_dir),
+            autoescape=select_autoescape(['html', 'xml']),
+            auto_reload=auto_reload,
+            cache_size=cache_size
+        )
+        
+        # Add custom filters and functions
+        self._setup_filters()
+    
+    def _setup_filters(self):
+        """Setup custom Jinja2 filters"""
+        # Add custom filters here
+        self.env.filters['format_date'] = self._format_date
+        self.env.filters['format_currency'] = self._format_currency
+    
+    def _format_date(self, value, format='%Y-%m-%d'):
+        """Format datetime objects"""
+        if value is None:
+            return ''
+        try:
+            return value.strftime(format)
+        except:
+            return str(value)
+    
+    def _format_currency(self, value, currency='$'):
+        """Format currency values"""
+        if value is None:
+            return ''
+        try:
+            return f"{currency}{value:,.2f}"
+        except:
+            return str(value)
+    
+    def render(self, template_name: str, context: Dict[str, Any] = None) -> str:
+        """
+        Render a template
+        
+        Args:
+            template_name: Template file name
+            context: Template context variables
+            
+        Returns:
+            Rendered HTML string
+        """
+        context = context or {}
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+    
+    def render_string(self, template_string: str, context: Dict[str, Any] = None) -> str:
+        """
+        Render a template from string
+        
+        Args:
+            template_string: Template content as string
+            context: Template context variables
+            
+        Returns:
+            Rendered HTML string
+        """
+        context = context or {}
+        template = self.env.from_string(template_string)
+        return template.render(**context)
+    
+    def add_global(self, name: str, value: Any):
+        """
+        Add a global variable to all templates
+        
+        Args:
+            name: Variable name
+            value: Variable value
+        """
+        self.env.globals[name] = value
+    
+    def add_filter(self, name: str, func: callable):
+        """
+        Add a custom filter
+        
+        Args:
+            name: Filter name
+            func: Filter function
+        """
+        self.env.filters[name] = func
+
+
+# Global template engine instance
+_template_engine: Optional[TemplateEngine] = None
+
+
+def get_template_engine() -> TemplateEngine:
+    """Get the global template engine instance"""
+    global _template_engine
+    if _template_engine is None:
+        _template_engine = TemplateEngine()
+    return _template_engine
+
+
+def set_template_engine(engine: TemplateEngine):
+    """Set the global template engine instance"""
+    global _template_engine
+    _template_engine = engine
+
+
+def render_template(template_name: str, context: Dict[str, Any] = None) -> str:
+    """
+    Convenience function to render a template
+    
+    Args:
+        template_name: Template file name
+        context: Template context variables
+        
+    Returns:
+        Rendered HTML string
+    """
+    return get_template_engine().render(template_name, context)

starspring/template/model_and_view.py

@@ -0,0 +1,69 @@
+"""
+Template engine integration
+
+Provides Jinja2 template rendering with Spring Boot-style patterns.
+"""
+
+from typing import Dict, Any, Optional
+from pathlib import Path
+import os
+
+
+class ModelAndView:
+    """
+    Container for model and view name
+    
+    Similar to Spring MVC's ModelAndView.
+    
+    Example:
+        @GetMapping("/users")
+        def list_users(self) -> ModelAndView:
+            users = self.user_service.find_all()
+            return ModelAndView("users/list.html", {"users": users})
+    """
+    
+    def __init__(self, view_name: str, model: Optional[Dict[str, Any]] = None):
+        """
+        Initialize ModelAndView
+        
+        Args:
+            view_name: Template file name
+            model: Dictionary of model attributes
+        """
+        self.view_name = view_name
+        self.model = model or {}
+    
+    def add_object(self, key: str, value: Any) -> 'ModelAndView':
+        """
+        Add an object to the model
+        
+        Args:
+            key: Attribute name
+            value: Attribute value
+            
+        Returns:
+            Self for method chaining
+        """
+        self.model[key] = value
+        return self
+    
+    def add_all_objects(self, objects: Dict[str, Any]) -> 'ModelAndView':
+        """
+        Add multiple objects to the model
+        
+        Args:
+            objects: Dictionary of attributes
+            
+        Returns:
+            Self for method chaining
+        """
+        self.model.update(objects)
+        return self
+    
+    def get_model(self) -> Dict[str, Any]:
+        """Get the model dictionary"""
+        return self.model
+    
+    def get_view_name(self) -> str:
+        """Get the view name"""
+        return self.view_name

starspring-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: starspring
+Version: 0.1.0
+Summary: A Spring Boot-inspired Python web framework built on Starlette
+Author: StarSpring Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/starspring
+Project-URL: Documentation, https://github.com/yourusername/starspring#readme
+Project-URL: Repository, https://github.com/yourusername/starspring
+Keywords: web,framework,starlette,spring-boot,dependency-injection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: starlette>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: sqlalchemy>=2.0.46
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.7.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0.0; extra == "sqlalchemy"
+
+# StarSpring Framework
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](https://pypi.org/project/starspring/)
+
+**StarSpring** is a production-grade, asynchronous web framework for Python that brings the robust architectural patterns of **Spring Boot** to the modern Python ecosystem. Built on top of **Starlette** and **SQLAlchemy**, it combines enterprise structure with Pythonic elegance.
+
+---
+
+## 🌟 Features
+
+*   **Dependency Injection (IoC)**: Fully typed, automatic constructor injection. No more global state or manual wiring.
+*   **Declarative Routing**: Use `@GetMapping`, `@PostMapping` decorators for clean, readable controllers.
+*   **Enterprise ORM**: Built on **SQLAlchemy** with **Imperative Mapping**. Define simple Python classes, and they become powerful database entities automatically.
+*   **Magic Repositories**: Define interfaces, and StarSpring implements the queries for you (e.g., `find_by_email_and_active(email, True)`).
+*   **Robust Transaction Management**: `@Transactional` decorators with support for robust nested transactions (`SAVEPOINT`s).
+*   **Production Ready**: Built-in support for CORS, Exception Handling, Logging, and Configuration Management (`application.yaml`).
+
+---
+
+## 📦 Installation
+
+StarSpring requires Python 3.10+.
+
+### Using pip
+```bash
+pip install starspring
+```
+
+### Using uv (Recommended for speed)
+```bash
+uv pip install starspring
+```
+
+### Database Drivers
+StarSpring uses SQLAlchemy. Install the driver for your database:
+```bash
+# SQLite (Standard)
+pip install starspring
+
+# PostgreSQL
+pip install psycopg2-binary
+# or
+pip install asyncpg
+```
+
+---
+
+## 🚀 Building Your First Application
+
+Here is a complete walkthrough of building a User Management API.
+
+### 1. Project Structure
+We recommend a standard layered architecture:
+```text
+my_app/
+├── __init__.py
+├── main.py              # Entry point
+├── application.yaml     # Configuration
+├── entities.py          # Database Models
+├── repositories.py      # Data Access
+├── services.py          # Business Logic
+└── controllers.py       # REST Endpoints
+```
+
+### 2. Configuration (`application.yaml`)
+Configure your server and database connection.
+
+```yaml
+server:
+  port: 8000
+  host: 0.0.0.0
+
+database:
+  url: "sqlite:///app.db"  # or postgresql://user:pass@localhost/db
+  ddl-auto: "create-if-not-exists" # Auto-creates tables from entities
+```
+
+### 3. Entities (`entities.py`)
+Define your database models using standard Python classes. StarSpring maps them automatically.
+
+```python
+from starspring import Entity, BaseEntity, Column, Id, GeneratedValue
+from datetime import datetime
+
+@Entity(table_name="users")
+class User(BaseEntity):
+    # BaseEntity automatically adds 'id', 'created_at', 'updated_at'
+    
+    username: str = Column(unique=True, length=50, nullable=False)
+    email: str = Column(unique=True, nullable=False)
+    is_active: bool = Column(default=True)
+    role: str = Column(default="USER")
+```
+
+### 4. Repositories (`repositories.py`)
+Create an interface for data access. Inherit from `StarRepository`.
+
+```python
+from starspring import Repository, StarRepository
+from my_app.entities import User
+
+@Repository
+class UserRepository(StarRepository[User, int]):
+    # StarSpring automatically implements standard CRUD (save, find_by_id, delete, etc.)
+    
+    # Define custom finders just by naming them!
+    async def find_by_username(self, username: str) -> User | None:
+        ...
+        
+    async def find_by_email_and_is_active(self, email: str, is_active: bool) -> User | None:
+        ...
+```
+
+### 5. Services (`services.py`)
+Encapsulate your business logic here. Use `@Transactional` to ensure data integrity.
+
+```python
+from starspring import Service, Transactional
+from my_app.repositories import UserRepository
+from my_app.entities import User
+
+@Service
+class UserService:
+    # Dependency Injection: Just mention the type in the constructor!
+    def __init__(self, user_repo: UserRepository):
+        self.user_repo = user_repo
+
+    @Transactional
+    async def register_user(self, username: str, email: str) -> User:
+        # Check if exists
+        existing = await self.user_repo.find_by_email_and_is_active(email, True)
+        if existing:
+            raise ValueError("User already exists")
+            
+        # Create new user
+        new_user = User(username=username, email=email)
+        return await self.user_repo.save(new_user)
+```
+
+### 6. Controllers (`controllers.py`)
+Expose your logic as a REST API.
+
+```python
+from starspring import RestController, GetMapping, PostMapping
+from starspring.web.response import ResponseEntity
+from my_app.services import UserService
+
+@RestController("/api/users")
+class UserController:
+    
+    def __init__(self, user_service: UserService):
+        self.user_service = user_service
+
+    @GetMapping("/{username}")
+    async def get_user(self, username: str) -> dict:
+        # You can return dicts, lists, or Entities directly
+        user = await self.user_service.user_repo.find_by_username(username)
+        return user.to_dict() if user else ResponseEntity.not_found()
+
+    @PostMapping("/register")
+    async def register(self, username: str, email: str) -> dict:
+        # Arguments are automatically extracted from JSON body or Query params
+        try:
+            user = await self.user_service.register_user(username, email)
+            return {"status": "success", "user_id": user.id}
+        except ValueError as e:
+            return ResponseEntity.bad_request(str(e))
+```
+
+### 7. Main Entry Point (`main.py`)
+Bootstrap the application.
+
+```python
+from starspring import StarSpringApplication
+
+# Initialize App
+app = StarSpringApplication(
+    title="My User API",
+    config_path="application.yaml"
+)
+
+# Scan for all your components (Controllers, Services, Repositories)
+app.scan_components("my_app")
+
+if __name__ == "__main__":
+    # Runs the server (default: localhost:8000)
+    app.run() 
+```
+
+---
+
+## 📚 Core Concepts
+
+### Dependency Injection (DI)
+StarSpring manages the lifecycle of your objects. When you ask for a `UserRepository` in your `UserService` constructor, the framework:
+1.  Finds the `UserRepository` class.
+2.  Creates an instance of it (Singleton by default).
+3.  Passes it to your `UserService`.
+
+This makes testing easier (you can mock repositories) and code cleaner.
+
+### Database & ORM
+We use a **Code-First** approach.
+1.  Define Python classes (`@Entity`).
+2.  StarSpring tells SQLAlchemy to map these classes to tables.
+3.  If `database.ddl-auto` is set to `create`, the framework creates the tables for you on startup.
+
+### Transaction Management
+Use the `@Transactional` decorator on any method (usually in Services).
+*   **Success**: The transaction commits automatically.
+*   **Reference Counter**: If you nest `@Transactional` methods, the inner one joins the outer transaction.
+*   **Error**: If an exception occurs, the entire transaction rolls back.
+
+---
+
+## 🛠 Advanced Configuration
+
+You can tune every part of the framework via `application.yaml`.
+
+```yaml
+server:
+  port: 8080
+  cors:
+    allowed-origins: ["*"]
+    allowed-methods: ["GET", "POST", "PUT", "DELETE"]
+
+logging:
+  level: INFO
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions!
+1.  Fork the repository.
+2.  Create a feature branch.
+3.  Submit a Pull Request.
+
+Please ensure all tests pass before submitting.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

starspring-0.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+starspring/__init__.py,sha256=erdKp-lAqhw9iFeIcVamGQAFLVhITCibPvHQFtgha5Q,3411
+starspring/application.py,sha256=J_xMTqwtEBhccTznJA2Be4j-qjh-tJhsOMLMHcE7bf4,14113
+starspring/client/__init__.py,sha256=Bomyz-O3w14OMozOLMa337TvRyEevj5m9bzkiswHnzk,29
+starspring/client/rest_client.py,sha256=ZoecH1eEor3aN9udxqWzjBsfPJcTuRPTTMBG22PzUSI,7298
+starspring/config/__init__.py,sha256=_OSjmqPwe35219tdibkRE7fdbWirb2G-Cz-CWPNC9rY,43
+starspring/config/environment.py,sha256=wSKMYvukbKccB_DVz6fk-BjtQsbnK1EtS9CAUbjLOco,2316
+starspring/config/properties.py,sha256=NEZcmGCSAJL9r69HybsoFeE75h00--M_uWPdGsOw7zI,4878
+starspring/core/__init__.py,sha256=u81P23ha-vTNh50kLwWZMSLinbE-DxSBluYaYIsn2Gk,33
+starspring/core/context.py,sha256=Ho6cLAhDlgCi5l3_mfvNsBUTQn6Z_3xd8C3UiXxvgsg,5914
+starspring/core/controller.py,sha256=IqRCTvKbebeRt5_HzIufK5jEO0qaRJ1ybvtvSytadD0,1459
+starspring/core/exceptions.py,sha256=9cu21pohqA1blzGN5dD5MBmggFc3em4M4vm36Hi1mx4,2879
+starspring/core/response.py,sha256=BMQxL6AcdTevHNQeszqVW0yHN1YNctUKa14AnA_NydA,4717
+starspring/data/__init__.py,sha256=0lBfm1wIj1caWDRF4bZGFtSDYJovMv6VwdmWhP6paBY,1102
+starspring/data/database_config.py,sha256=pQ5ChPap-0m8Kq1sissTjd9vw56yJ80BwuSI6waGzNQ,3656
+starspring/data/entity.py,sha256=gn6rH4VCPzn_oNK_TLxTiKMRKm-gI7vB3JrhYY0hBPU,12404
+starspring/data/orm_gateway.py,sha256=LZfASLvnpdFYguK7_LtV1OnuhqkMwkAmlelLREqqvEI,8558
+starspring/data/query_builder.py,sha256=1ef2S8oNa8tPpZ8qazsbVRglro2oJ7_7u2QhNCKeHCo,11690
+starspring/data/repository.py,sha256=8gjoZ4iImz3J4b_ADs8qQottbkTjNyd9mZ1iZ91j3ko,10075
+starspring/data/schema_generator.py,sha256=r6OqYjsW-HeDVAdlfKb2wAPC6XbedH-0E11pNmynKms,4834
+starspring/data/transaction.py,sha256=kFVrv3xA2EhOXnDcN88QPhLq6rYX9UXC_2EUG_sQGzg,1613
+starspring/decorators/__init__.py,sha256=WSJHi2c_4I1ZX6TzhGCvEgBkFWnCk9NbXKIyjH9ErqY,63
+starspring/decorators/components.py,sha256=wB2CMNnqoJ2VPhQ1Er9_heFQyPLjna7KYKpdmmym1Yw,5288
+starspring/decorators/configuration.py,sha256=XUkzZCusmaoGdQpm17d3x3zVTViXeC231RCfkfr35Ok,2901
+starspring/decorators/routing.py,sha256=rENfRuRkBlpFLn6KSZGIoqnDpMqR0IwriPB5rX9iIC8,10560
+starspring/decorators/validation.py,sha256=wsqvVA_IuGZprwLqbkoZ7Xg3qCK-om_Rxc4RqDU0Nhw,817
+starspring/middleware/__init__.py,sha256=jzho4eY5jLPyUH-kUm6K--RFIF_X1z2oA-I_8EZZ43o,29
+starspring/middleware/cors.py,sha256=74mmat0jYkvLi9x5iytxj4S-QupdH16r2r7k_Cw0iQk,2609
+starspring/middleware/exception.py,sha256=Fk5X5vS-BKNBn0wPzXKStH30Mi8wq1qXGhVjY56-JMI,2685
+starspring/middleware/logging.py,sha256=GXwAujaHcgMWigeS9Vv-cvEIw2E3G5hv15pebepfjmM,1667
+starspring/template/__init__.py,sha256=aNwQaFo8sG-p-Q4bNOHPi4s67jOUIcH845_xggki3MU,387
+starspring/template/engine.py,sha256=9xBcZDRnMdQN1I-ZWf_5tHkpuJhvYlsv-bo2f5boqEk,4794
+starspring/template/model_and_view.py,sha256=qEQblzl3WotfnFVWCF3IcB6AOpCJHS6Hh998m-YFkLU,1799
+starspring-0.1.0.dist-info/METADATA,sha256=R8MiBfqNbAcTL_AVlVzC0InqwD77EvLE1LmN65PCdEM,9572
+starspring-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+starspring-0.1.0.dist-info/top_level.txt,sha256=FWPAl1oRZXxoFa3ePRyY7lmXpde2KMYRX7CBTNDuZtI,11
+starspring-0.1.0.dist-info/RECORD,,

starspring-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

starspring-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+starspring