sprintapi 0.1.0__tar.gz

sprintapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lingqiao Zhao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sprintapi-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: sprintapi
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Lingqiao Zhao <forever.3g@hotmail.com>
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Dynamic: license-file

sprintapi-0.1.0/README.md

@@ -0,0 +1,78 @@
+# SprintAPI Framework
+
+A lightweight FastAPI-based framework that can be used like Spring Boot, with built-in dependency injection and lifecycle management.
+
+## Core features
+- **Configuration via environment variables** over config file,
+    which is friendly to containerized deployments and 12-factor apps;
+- **Built-in dependency injection**, which enables IoC and better handles dependency management for larger apps;
+- **Controller-based API design**, which is more intuitive for developers coming from other languages;
+- **Lifecycle hooks** called on same event loop as the server, and are called in dependency order;
+
+## Requirements
+
+- Python 3.12+
+
+## Install (editable)
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+Below is a minimal example of a controller exposing a single GET endpoint.
+
+```python
+# main.py
+
+from sprintapi import SprintApiServer, api_route, get_mapping, Controller
+
+
+@api_route('/simple')
+class SimpleController(Controller):
+    """A minimal controller exposing a single GET endpoint."""
+
+    @get_mapping('hello')
+    async def hello(self):
+        """Return a simple greeting."""
+        return 'Hello, World!'
+
+
+def main():
+    # Create and run the server; pass `port=8000` to change the default.
+    server = SprintApiServer()
+    server.run()
+
+
+if __name__ == '__main__':
+    main()
+```
+
+Run it:
+
+```bash
+python main.py
+```
+This runs a web server listening on `http://localhost:80`.
+Then open `http://localhost/simple/hello` in your browser, you will see:
+```
+Hello, World!
+```
+
+## With Dependency Injection
+
+```bash
+> cd examples/with-di
+> export APP_NAME="My Demo"
+> python main.py
+```
+
+Then open `http://localhost/app/name` in your browser and you will see:
+```
+This app is My Demo
+```
+
+## License
+
+MIT. See `LICENSE`.

sprintapi-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "sprintapi"
+version = "0.1.0"
+description = "Add your description here"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2",
+    "fastapi",
+    "uvicorn"
+]
+authors = [
+    {name = "Lingqiao Zhao", email = "forever.3g@hotmail.com"}
+]
+
+[tool.setuptools]
+package-data = { "gw_luna" = [
+    "static/redoc/*",
+    "static/swagger-ui/*"
+] }

sprintapi-0.1.0/setup.cfg

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

sprintapi-0.1.0/src/sprintapi/__init__.py

@@ -0,0 +1,12 @@
+from .config import Configuration, configuration
+from .controller import (
+    Controller,
+    api_route,
+    get_mapping,
+    post_mapping,
+    put_mapping,
+    delete_mapping
+)
+from .error import *
+from .server import *
+from .service import Service, service

sprintapi-0.1.0/src/sprintapi/config.py

@@ -0,0 +1,36 @@
+import os
+
+from pydantic import BaseModel
+from typing import Any, Mapping
+
+from .utility.type_registry import get_registry_decorator
+
+
+__all__ = [
+    'Configuration',
+    'configuration',
+    'get_configuration_types',
+]
+
+
+class Configuration(BaseModel):
+    @classmethod
+    def load(cls):
+        config_dict = cls._get_required_dict(os.environ)
+        return cls.model_validate(config_dict, by_alias=True)
+
+    @classmethod
+    def _get_required_dict(cls, d: Mapping[str, Any]):
+        res = {}
+        for key in cls.model_json_schema()['properties']:
+            if key in d:
+                res[key] = d[key]
+        return res
+
+
+_config_types: set[type[Configuration]] = set()
+configuration = get_registry_decorator(Configuration, _config_types)
+
+
+def get_configuration_types() -> set[type[Configuration]]:
+    return _config_types.copy()

sprintapi-0.1.0/src/sprintapi/controller.py

@@ -0,0 +1,126 @@
+import fastapi
+import inspect
+
+
+__all__ = [
+    'api_route',
+    'get_controller_types',
+    'Controller',
+
+    'get_mapping',
+    'post_mapping',
+    'put_mapping',
+    'delete_mapping'
+]
+
+
+# APIs
+
+
+def _method_mapping(method: str, route: str, **kwargs):
+    if not route.startswith('/') and len(route) > 0:
+        route = '/' + route
+
+    def _inner(target):
+        if not inspect.isfunction(target):
+            return target
+
+        target._sprint_api_type = method
+        target._sprint_api_route = route
+        target._sprint_api_args = kwargs
+
+        return target
+
+    return _inner
+
+
+def get_mapping(route: str, **kwargs):
+    if not isinstance(route, str):
+        raise ValueError('Route is not specified.')
+    return _method_mapping('GET', route, **kwargs)
+
+
+def post_mapping(route: str, **kwargs):
+    if not isinstance(route, str):
+        raise ValueError('Route is not specified.')
+    return _method_mapping('POST', route, **kwargs)
+
+
+def put_mapping(route: str, **kwargs):
+    if not isinstance(route, str):
+        raise ValueError('Route is not specified.')
+    return _method_mapping('PUT', route, **kwargs)
+
+
+def delete_mapping(route: str, **kwargs):
+    if not isinstance(route, str):
+        raise ValueError('Route is not specified.')
+    return _method_mapping('DELETE', route, **kwargs)
+
+
+# Controllers
+
+
+class Controller:
+    def get_router(self):
+        route_prefix = getattr(self, '_sprint_api_route', '')
+        args = getattr(self, '_sprint_api_args', {})
+
+        router = fastapi.APIRouter(prefix=route_prefix, **args)
+
+        for method_name in dir(self):
+            if method_name.startswith('__'):
+                continue
+
+            method = getattr(self, method_name)
+            if not callable(method):
+                continue
+
+            api_type = getattr(method, '_sprint_api_type', None)
+            route = getattr(method, '_sprint_api_route', None)
+            args = getattr(method, '_sprint_api_args', {})
+
+            if api_type is None or route is None:
+                continue
+
+            if api_type in ('GET', 'POST', 'PUT', 'DELETE'):
+                router.api_route(path=route, methods=[api_type], **args)(method)
+
+        return router
+
+
+_controller_types: set[type[Controller]] = set()
+
+
+def api_route(route: str, **kwargs):
+    if not isinstance(route, str):
+        raise ValueError('Route is not specified.')
+
+    if route.endswith('/'):
+        route = route[:-1]
+
+    global _controller_types
+
+    def _inner(target):
+        if inspect.isfunction(target):
+            return target
+
+        if not isinstance(target, type):
+            raise TypeError(f'{target} is not a type.')
+        if not issubclass(target, Controller):
+            raise TypeError(f'{target.__name__} is not a subclass of Controller.')
+
+        if target in _controller_types:
+            raise ValueError(f'Controller class "{target.__name__}" is already registered.')
+
+        _controller_types.add(target)
+        target._sprint_api_route = route
+        target._sprint_api_args = kwargs
+
+        return target
+
+    return _inner
+
+
+def get_controller_types() -> set[type[Controller]]:
+    return _controller_types.copy()

sprintapi-0.1.0/src/sprintapi/error.py

@@ -0,0 +1,119 @@
+import enum
+from pydantic import BaseModel
+
+
+__all__ = [
+    'Error',
+    'ErrorCode',
+    'ErrorModel',
+
+    'Ok',
+    'AlreadyExistsError',
+    'DeadlineExceededError',
+    'FailedPreconditionError',
+    'InternalError',
+    'InvalidArgumentError',
+    'NotFoundError',
+    'PermissionDeniedError',
+    'TooManyRequestsError',
+    'UnauthenticatedError',
+    'UnimplementedError'
+]
+
+
+class ErrorCode(enum.IntEnum):
+    """
+    错误代码。定义参照谷歌RPC错误代码定义。
+    """
+    OK = 0
+    CANCELLED = 1
+    UNKNOWN = 2
+    INVALID_ARGUMENT = 3
+    DEADLINE_EXCEEDED = 4
+    NOT_FOUND = 5
+    ALREADY_EXISTS = 6
+    PERMISSION_DENIED = 7
+    RESOURCE_EXHAUSTED = 8
+    FAILED_PRECONDITION = 9
+    ABORTED = 10
+    OUT_OF_RANGE = 11
+    UNIMPLEMENTED = 12
+    INTERNAL = 13
+    UNAVAILABLE = 14
+    DATA_LOSS = 15
+    UNAUTHENTICATED = 16
+
+
+class ErrorModel(BaseModel):
+    code: ErrorCode
+    message: str
+
+
+class Ok(ErrorModel):
+    def __init__(self):
+        super().__init__(code=ErrorCode.OK, message='Ok.')
+
+
+class Error(Exception):
+    def __init__(self, code: ErrorCode, message: str):
+        self.code = code
+        self.message = message
+
+    def json(self):
+        return self.model().model_dump_json()
+
+    def model(self):
+        return ErrorModel(
+            code=self.code,
+            message=self.message
+        )
+
+
+class AlreadyExistsError(Error):
+    def __init__(self, message: str = 'Requested resource already exists.'):
+        super().__init__(code=ErrorCode.ALREADY_EXISTS, message=message)
+
+
+class DeadlineExceededError(Error):
+    def __init__(self, message: str = 'Deadline exceeded.'):
+        super().__init__(code=ErrorCode.DEADLINE_EXCEEDED, message=message)
+
+
+class FailedPreconditionError(Error):
+    def __init__(self, message: str = 'Resource is not in a valid state.'):
+        super().__init__(code=ErrorCode.FAILED_PRECONDITION, message=message)
+
+
+class InternalError(Error):
+    def __init__(self, message: str = 'Internal error.'):
+        super().__init__(code=ErrorCode.INTERNAL, message=message)
+
+
+class InvalidArgumentError(Error):
+    def __init__(self, message: str = 'Invalid argument.'):
+        super().__init__(code=ErrorCode.INVALID_ARGUMENT, message=message)
+
+
+class NotFoundError(Error):
+    def __init__(self, message: str = 'Requested resource does not exist.'):
+        super().__init__(code=ErrorCode.NOT_FOUND, message=message)
+
+
+class PermissionDeniedError(Error):
+    def __init__(self, message: str = 'Permission denied.'):
+        super().__init__(code=ErrorCode.PERMISSION_DENIED, message=message)
+
+
+class TooManyRequestsError(Error):
+    def __init__(self, message: str = 'Too many requests.'):
+        super().__init__(code=ErrorCode.UNAVAILABLE, message=message)
+
+
+class UnauthenticatedError(Error):
+    def __init__(self, message: str = 'Unauthenticated request.'):
+        super().__init__(code=ErrorCode.UNAUTHENTICATED, message=message)
+
+
+class UnimplementedError(Error):
+    def __init__(self, message: str = 'Unimplemented method.'):
+        super().__init__(code=ErrorCode.UNIMPLEMENTED, message=message)

sprintapi-0.1.0/src/sprintapi/logging.py

@@ -0,0 +1,68 @@
+import logging
+import sys
+
+
+__all__ = [
+    'get_sprintapi_logger',
+    'set_global_level_to_debug',
+    'set_global_level_to_info'
+]
+
+
+_log_formatter = logging.Formatter(
+    fmt='%(asctime)s.%(msecs)03d [%(levelname)s] [%(name)s] %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S'
+)
+
+
+_stdout_handler = logging.StreamHandler(sys.stdout)
+_stdout_handler.setFormatter(_log_formatter)
+_stdout_handler.setLevel(logging.DEBUG)
+_stdout_filter = logging.Filter()
+_stdout_filter.filter = lambda record: record.levelno <= logging.INFO
+_stdout_handler.addFilter(_stdout_filter)
+
+_stderr_handler = logging.StreamHandler(sys.stderr)
+_stderr_handler.setFormatter(_log_formatter)
+_stderr_handler.setLevel(logging.WARNING)
+_stderr_filter = logging.Filter()
+_stderr_filter.filter = lambda record: record.levelno > logging.INFO
+
+
+_managed_loggers: dict[str, logging.Logger] = {}
+_current_level = logging.INFO
+
+
+def get_sprintapi_logger(name: str):
+    logger = _managed_loggers.get(name, None)
+    if logger is not None:
+        return logger
+
+    logger = logging.getLogger(name)
+    logger.propagate = False
+    logger.setLevel(_current_level)
+    logger.addHandler(_stdout_handler)
+    logger.addHandler(_stderr_handler)
+    _managed_loggers[name] = logger
+
+    return logger
+
+
+_logger = get_sprintapi_logger('LogCtrl')
+
+
+def _set_global_level(level: int):
+    global _current_level
+    _current_level = level
+
+    for logger in _managed_loggers.values():
+        _logger.info(f'Logger "{logger.name} set to level: {level}."')
+        logger.setLevel(_current_level)
+
+
+def set_global_level_to_debug():
+    _set_global_level(logging.DEBUG)
+
+
+def set_global_level_to_info():
+    _set_global_level(logging.INFO)

sprintapi-0.1.0/src/sprintapi/middleware/__init__.py

@@ -0,0 +1 @@
+from .cors import CorsMiddleware

sprintapi-0.1.0/src/sprintapi/middleware/cors.py

@@ -0,0 +1,19 @@
+import fastapi
+
+from starlette.middleware.base import BaseHTTPMiddleware
+
+
+__all__ = ['CorsMiddleware']
+
+
+class CorsMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        if request.method != 'OPTIONS':
+            response = await call_next(request)
+            response.headers['Access-Control-Allow-Origin'] = '*'
+            return response
+        return fastapi.Response(status_code=200, headers={
+            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+            'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+            'Access-Control-Allow-Origin': '*',
+        })

sprintapi-0.1.0/src/sprintapi/middleware/error_handler.py

@@ -0,0 +1,75 @@
+import fastapi
+
+from ..error import (
+    Error,
+    ErrorCode,
+    InvalidArgumentError,
+)
+from pydantic import ValidationError
+
+
+__all__ = [
+    'register_sprintapi_errors'
+]
+
+
+
+_error_code_map = {
+    ErrorCode.OK: 200,
+    ErrorCode.CANCELLED: 499,
+    ErrorCode.UNKNOWN: 500,
+    ErrorCode.INVALID_ARGUMENT: 400,
+    ErrorCode.DEADLINE_EXCEEDED: 504,
+    ErrorCode.NOT_FOUND: 404,
+    ErrorCode.ALREADY_EXISTS: 409,
+    ErrorCode.PERMISSION_DENIED: 403,
+    ErrorCode.RESOURCE_EXHAUSTED: 429,
+    ErrorCode.FAILED_PRECONDITION: 400,
+    ErrorCode.ABORTED: 409,
+    ErrorCode.OUT_OF_RANGE: 400,
+    ErrorCode.UNIMPLEMENTED: 501,
+    ErrorCode.INTERNAL: 500,
+    ErrorCode.UNAVAILABLE: 503,
+    ErrorCode.DATA_LOSS: 500,
+    ErrorCode.UNAUTHENTICATED: 401
+}
+
+
+def _register_sprintapi_error_handler(app: fastapi.FastAPI):
+    def _handler(request: fastapi.Request, exc: Error):
+        if request.headers.get('accept') == 'text/event-stream':
+            return fastapi.Response(
+                status_code=200,
+                headers={
+                    'Content-Type': 'text/event-stream',
+                },
+                content=f'event: abort\ndata: {exc.json()}\n\n'
+            )
+        return fastapi.Response(
+            status_code=_error_code_map.get(exc.code, 500),
+            content=exc.json()
+        )
+    app.add_exception_handler(Error, _handler)
+
+
+def _register_pydantic_validation_error(app: fastapi.FastAPI):
+    def _handler(request: fastapi.Request, _):
+        exc = InvalidArgumentError()
+        if request.headers.get('accept') == 'text/event-stream':
+            return fastapi.Response(
+                status_code=200,
+                headers={
+                    'Content-Type': 'text/event-stream',
+                },
+                content=f'event: abort\ndata: {exc.json()}\n\n'
+            )
+        return fastapi.Response(
+            status_code=400,
+            content=exc.json()
+        )
+    app.add_exception_handler(ValidationError, _handler)
+
+
+def register_sprintapi_errors(app: fastapi.FastAPI):
+    _register_sprintapi_error_handler(app)
+    _register_pydantic_validation_error(app)

sprintapi-0.1.0/src/sprintapi/server.py

@@ -0,0 +1,133 @@
+import logging
+
+import fastapi
+import importlib.resources
+import uvicorn
+
+from fastapi.openapi.docs import get_swagger_ui_html, get_redoc_html
+from fastapi.staticfiles import StaticFiles
+from typing import Optional
+
+from .config import get_configuration_types
+from .controller import get_controller_types
+from .logging import get_sprintapi_logger
+from .middleware import CorsMiddleware
+from .middleware.error_handler import register_sprintapi_errors
+from .service import get_service_types
+from .utility.di import DependencyContainer
+
+
+__all__ = ['SprintApiServer']
+
+
+_logger = get_sprintapi_logger('SprintApiServer')
+_static_dir = importlib.resources.files('sprintapi') / 'static'
+
+
+class SprintApiServer(uvicorn.Server):
+    def __init__(
+            self,
+            host: str = '0.0.0.0',
+            port: int = 80,
+            /,
+            enable_docs: bool = False,
+            app_name: str = None,
+            version: str = None,
+            uvicorn_log_level: int = logging.INFO
+    ):
+        super().__init__(config=uvicorn.Config(
+            app=self._setup_app(app_name, version),
+            host=host,
+            port=port,
+            log_level=uvicorn_log_level
+        ))
+        self._app_name = app_name
+        self._app.add_middleware(CorsMiddleware)
+        self._controller_types = get_controller_types()
+
+        # component registration
+        self._di_container = DependencyContainer()
+        for c in get_configuration_types():
+            self._di_container.register(c, c.load, is_singleton=True)
+        for c in self._controller_types:
+            self._di_container.register(c, c, is_singleton=True)
+
+        service_types = get_service_types()
+        for s in service_types:
+            self._di_container.register(s, s, is_singleton=True)
+
+        self._managed_services = self._di_container.resolve_with_order(service_types)
+
+        # register error handlers
+        register_sprintapi_errors(self._app)
+
+        # bind controllers
+        for c in self._controller_types:
+            controller = self._di_container.resolve(c)
+            router = controller.get_router()
+            class_name = controller.__class__.__name__
+            self._app.include_router(router)
+            _logger.info(f'Bind controller {class_name} with route prefix "{router.prefix}".')
+
+        # bind static files
+        self._app.mount('/static', StaticFiles(directory=_static_dir), name='static')
+        if enable_docs:
+            self._app.get('/docs', include_in_schema=False)(self._swagger_ui_html)
+            self._app.get('/redoc', include_in_schema=False)(self._redoc_ui_html)
+
+    @property
+    def app(self):
+        return self._app
+
+    async def startup(self, sockets = None):
+        await self._pre_startup()
+        await super().startup(sockets)
+
+    async def shutdown(self, sockets = None):
+        await self._pre_shutdown()
+        await super().shutdown(sockets)
+        await self._post_shutdown()
+
+    def _redoc_ui_html(self):
+        return get_redoc_html(
+            openapi_url=self._app.openapi_url,
+            title=f'{self._app_name} - Redoc' if self._app_name else 'Redoc',
+            redoc_js_url='/static/redoc/redoc.standalone.js',
+        )
+
+    def _swagger_ui_html(self):
+        return get_swagger_ui_html(
+            openapi_url=self._app.openapi_url,
+            title=f'{self._app_name} - Swagger UI' if self._app_name else 'Swagger UI',
+            swagger_favicon_url='/static/swagger-ui/favicon-32x32.png',
+            swagger_js_url='/static/swagger-ui/swagger-ui-bundle.js',
+            swagger_css_url='/static/swagger-ui/swagger-ui.css',
+        )
+
+    async def _pre_startup(self):
+        # init services
+        for s in self._managed_services:
+            await s.init()
+        _logger.info('Managers init complete.')
+
+        # start services
+        for s in self._managed_services:
+            await s.start()
+        _logger.info('Managers start complete.')
+
+    async def _pre_shutdown(self):
+        pass
+
+    async def _post_shutdown(self):
+        for s in self._managed_services[::-1]:
+            await s.stop()
+        _logger.info('Managers stop complete.')
+
+    def _setup_app(self, app_name: Optional[str], version: Optional[str]):
+        extra_args = {}
+        if app_name:
+            extra_args['title'] = app_name
+        if version:
+            extra_args['version'] = version
+        self._app = fastapi.FastAPI(docs_url=None, redoc_url=None, **extra_args)
+        return self._app

sprintapi-0.1.0/src/sprintapi/service.py

@@ -0,0 +1,27 @@
+from .utility.type_registry import get_registry_decorator
+
+
+__all__ = [
+    'Service',
+    'service',
+    'get_service_types',
+]
+
+
+class Service:
+    async def init(self):
+        pass
+
+    async def start(self):
+        pass
+
+    async def stop(self):
+        pass
+
+
+_service_types: set[type[Service]] = set()
+
+service = get_registry_decorator(Service, _service_types)
+
+def get_service_types() -> set[type[Service]]:
+    return _service_types.copy()

sprintapi-0.1.0/src/sprintapi/utility/di.py

@@ -0,0 +1,112 @@
+import inspect
+from collections import defaultdict, deque
+from typing import Any, Callable, Iterable, get_type_hints
+
+
+__all__ = ['DependencyContainer']
+
+
+class DependencyContainer:
+    def __init__(self):
+        self._components: dict[type, tuple[Callable, bool]] = {}
+        self._singletons: dict[type, object] = {}
+
+    def check_circular(self):
+        # build indegree map with all related deps
+        indegree_map = self._build_indegree_map(self._components.keys())
+
+        unresolved = deque([c for c, count in indegree_map.items() if count == 0])
+        visit_count = 0
+
+        while unresolved:
+            interface = unresolved.popleft()
+            visit_count += 1
+
+            deps = list(self._get_direct_deps(interface).values())
+            for dep in deps:
+                indegree_map[dep] -= 1
+                if indegree_map[dep] == 0:
+                    unresolved.append(dep)
+
+        return visit_count != len(indegree_map)
+
+    def register(self, interface: type[object], impl: Callable, is_singleton: bool = False):
+        if interface in self._components:
+            raise TypeError(f'Type "{interface.__name__}" already registered."')
+        self._components[interface] = (impl, is_singleton)
+
+    def resolve(self, interface: type):
+        deps = self._get_direct_deps(interface)
+        dep_impls = {k: self.resolve(v) for k, v in deps.items()}
+        impl_info = self._components.get(interface, None)
+
+        if impl_info is None:
+            raise TypeError(f'Failed to resolve dependency of type: "{interface.__name__}".')
+
+        impl, is_singleton = impl_info
+        if is_singleton:
+            if interface not in self._singletons:
+                self._singletons[interface] = self._create_impl(interface, impl, dep_impls)
+            return self._singletons[interface]
+        return self._create_impl(interface, impl, dep_impls)
+
+    def resolve_with_order(self, interfaces: Iterable[type]) -> list[Any]:
+        target_interfaces = set(interfaces)
+
+        # find all related interfaces along the path
+        related_interfaces = set()
+        unresolved = deque(target_interfaces)
+
+        while unresolved:
+            interface = unresolved.popleft()
+            related_interfaces.add(interface)
+            for dep in self._get_direct_deps(interface).values():
+                if dep not in related_interfaces:
+                    unresolved.append(dep)
+
+        indegree_map = self._build_indegree_map(related_interfaces)
+
+        # start from no deps, simulate population, append node only if indegree depleted (Kahn's algo)
+        unresolved = deque([c for c, count in indegree_map.items() if count == 0])
+        res_interfaces = []
+
+        while unresolved:
+            interface = unresolved.popleft()
+
+            if interface in target_interfaces:
+                res_interfaces.append(interface)
+
+            for dep in self._get_direct_deps(interface).values():
+                indegree_map[dep] -= 1
+                if indegree_map[dep] == 0:
+                    unresolved.append(dep)
+
+        return [self.resolve(interface) for interface in res_interfaces[::-1]]
+
+    def _build_indegree_map(self, interfaces: Iterable[type]) -> dict[type, int]:
+        indegree_map = defaultdict(int)
+        for c in interfaces:
+            indegree_map[c] += 0
+            for dep in self._get_direct_deps(c).values():
+                indegree_map[dep] += 1
+        return indegree_map
+
+    @staticmethod
+    def _create_impl(interface, impl, deps):
+        try:
+            return impl(**deps)
+        except TypeError:
+            raise TypeError(f'Failed to resolve dependency of type: "{interface.__name__}".')
+
+    def _get_direct_deps(self, interface: type) -> dict[str, type]:
+        impl_info = self._components.get(interface, None)
+        if not impl_info:
+            raise TypeError(f'Failed to resolve dependency of type: "{interface.__name__}".')
+
+        impl_sig, _ = impl_info
+        if inspect.isclass(impl_sig):
+            type_hints = get_type_hints(impl_sig.__init__)
+        else:
+            type_hints = get_type_hints(impl_sig)
+
+        return { name: pt for name, pt in type_hints.items() if name != 'return' }

sprintapi-0.1.0/src/sprintapi/utility/type_registry.py

@@ -0,0 +1,22 @@
+import inspect
+
+
+__all__ = ['get_registry_decorator']
+
+
+def get_registry_decorator(base_type: type, registry: set[type]):
+    def _inner(target):
+        if inspect.isfunction(target):
+            return target
+
+        if not isinstance(target, type):
+            raise TypeError(f'{target} is not a type.')
+        if not issubclass(target, base_type):
+            raise TypeError(f'{target.__name__} is not a subclass of {base_type.__name__}.')
+
+        if target in registry:
+            raise ValueError(f'{base_type.__name__} class "{target.__name__}" is already registered.')
+
+        registry.add(target)
+        return target
+    return _inner

sprintapi-0.1.0/src/sprintapi.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: sprintapi
+Version: 0.1.0
+Summary: Add your description here
+Author-email: Lingqiao Zhao <forever.3g@hotmail.com>
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Dynamic: license-file

sprintapi-0.1.0/src/sprintapi.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/sprintapi/__init__.py
+src/sprintapi/config.py
+src/sprintapi/controller.py
+src/sprintapi/error.py
+src/sprintapi/logging.py
+src/sprintapi/server.py
+src/sprintapi/service.py
+src/sprintapi.egg-info/PKG-INFO
+src/sprintapi.egg-info/SOURCES.txt
+src/sprintapi.egg-info/dependency_links.txt
+src/sprintapi.egg-info/requires.txt
+src/sprintapi.egg-info/top_level.txt
+src/sprintapi/middleware/__init__.py
+src/sprintapi/middleware/cors.py
+src/sprintapi/middleware/error_handler.py
+src/sprintapi/utility/__init__.py
+src/sprintapi/utility/di.py
+src/sprintapi/utility/type_registry.py

sprintapi-0.1.0/src/sprintapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sprintapi-0.1.0/src/sprintapi.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pydantic>=2
+fastapi
+uvicorn

sprintapi-0.1.0/src/sprintapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+sprintapi