PySpring

PySpring — Spring Boot-inspired Python framework ecosystem with type-safe dependency injection, ORM, scheduling, and more.

GitHub: https://github.com/PythonSpring

PySpring is a Python web framework inspired by Spring Boot. It gives you a structured, type-safe approach to building scalable web applications — with automatic dependency injection, configuration management, and an ASGI web server built on FastAPI.

The ecosystem¶

PySpring is a family of modules that work together:

Package	Description
py-spring-core	The foundation — DI, components, controllers, properties, events, middleware
pyspring-model	ORM and data access — CRUD repositories, dynamic queries, transactions
pyspring-scheduler	Background scheduling — interval, cron, and combined triggers with DI

Each module is installed separately and integrated via the Starters pattern.

Core features¶

Type-safe: Dependency injection resolved entirely from Python type hints. No decorators, no magic strings — your editor knows everything.
Spring Boot-inspired: Familiar patterns — Components, Properties, Controllers, Bean Collections — for developers who appreciate structured architecture.
Built on FastAPI: Automatic OpenAPI docs, high performance, and async support out of the box.
Auto configuration: Load and validate configuration from JSON/YAML using Pydantic models.
Lifecycle management: post_construct and pre_destroy hooks for clean resource management.
Event-driven: Built-in thread-safe event system with typed Pydantic events.
ORM with dynamic queries: Spring Data JPA-style repositories with auto-implemented query methods and @Transactional support.
Background scheduling: Cron, interval, and combined triggers with full DI integration.

Requirements¶

Python 3.10+

PySpring builds on top of:

FastAPI — for the web server layer.
Pydantic — for data validation and configuration.

Installation¶

$ pip install py-spring-core

---> 100%

Example¶

Create it¶

Create a file main.py with:

from py_spring_core import PySpringApplication


def main():
    app = PySpringApplication("./app-config.json")
    app.run()


if __name__ == "__main__":
    main()

Now create a component with dependency injection in services.py:

from py_spring_core import Component, Properties


class DatabaseProperties(Properties):
    __key__ = "database"
    host: str
    port: int
    name: str


class DatabaseService(Component):
    database_properties: DatabaseProperties  # Auto-injected!

    def post_construct(self):
        print(f"Connected to {self.database_properties.host}")

And a REST controller in controllers.py:

from py_spring_core import RestController
from py_spring_core.core.entities.controllers.rest_controller import GetMapping


class UserController(RestController):
    class Config:
        prefix = "/api/users"

    database_service: DatabaseService  # Auto-injected!

    @GetMapping("/")
    def get_users(self):
        return {"users": []}

That's the entire application. You declared types — PySpring resolved and injected everything.

Run it¶

$ python main.py

Check it¶

Open your browser at http://127.0.0.1:8000/docs.

You get automatic interactive API documentation (Swagger UI) with your routes already defined — because PySpring builds on FastAPI. ✨

You also get ReDoc at /redoc.

Recap¶

In that small example, you:

Declared dependencies using type hints — PySpring resolved and injected them.
Defined configuration as a Pydantic model — loaded and validated automatically.
Built a REST API using decorators — with automatic OpenAPI docs.

All with type safety, editor support, and minimal boilerplate.

To learn everything step by step, head to the Tutorial - User Guide.

License¶

This project is licensed under the terms of the MIT license.