starspring 0.1.0__tar.gz

starspring-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,247 @@
+# 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/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starspring"
+version = "0.1.0"
+description = "A Spring Boot-inspired Python web framework built on Starlette"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "StarSpring Contributors"}
+]
+keywords = ["web", "framework", "starlette", "spring-boot", "dependency-injection"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+dependencies = [
+    "starlette>=0.27.0",
+    "pydantic>=2.0.0",
+    "uvicorn[standard]>=0.23.0",
+    "python-multipart>=0.0.6",
+    "pyyaml>=6.0",
+    "httpx>=0.24.0",
+    "jinja2>=3.1.6",
+    "sqlalchemy>=2.0.46",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.7.0",
+    "mypy>=1.5.0",
+]
+sqlalchemy = [
+    "sqlalchemy>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/starspring"
+Documentation = "https://github.com/yourusername/starspring#readme"
+Repository = "https://github.com/yourusername/starspring"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["starspring*"]
+
+[tool.black]
+line-length = 100
+target-version = ['py310']
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

starspring-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+