fastapi-boot 0.0.1__py3-none-any.whl

fastapi_boot/DI.py

@@ -0,0 +1,268 @@
+import time
+from collections.abc import Callable
+from inspect import Parameter, _empty, signature,isclass
+from typing import Annotated, Generic, TypeVar, get_args, get_origin, no_type_check, overload
+
+from fastapi_boot.const import NameDepRecord, TypeDepRecord, app_store, dep_store
+from fastapi_boot.model import AppRecord, DependencyNotFoundException, InjectFailException
+from fastapi_boot.util import get_call_filename
+
+T = TypeVar('T')
+
+# ------------------------------------------------------- public ------------------------------------------------------ #
+
+
+def _inject(app_record: AppRecord, tp: type[T], name: str | None = None) -> T:
+    """inject dependency by type or name
+
+    Args:
+        app_record (AppRecord)
+        tp (type[T])
+        name (str | None)
+
+    Returns:
+        T: instance
+    """
+    start = time.time()
+    while True:
+        if res := dep_store.inject_by_type(tp) if name is None else dep_store.inject_by_name(name, tp):
+            return res
+        time.sleep(app_record.inject_retry_step)
+        if time.time() - start > app_record.inject_timeout:
+            name_info=f"with name '{name}'" if name is not None else ''
+            raise DependencyNotFoundException(f"Dependency '{tp}' {name_info} not found")
+
+
+def inject_params_deps(app_record: AppRecord, params: list[Parameter]):
+    """find dependencies of params
+    Args:
+        app_record (AppRecord)
+        params (list[Parameter]): param list without self
+    """
+    params_dict = {}
+    for param in params:
+        # 1. with default
+        if param.default != _empty:
+            params_dict.update({param.name: param.default})
+        else:
+            # 2. no default
+            if param.annotation == _empty:
+                # 2.1 not annotation
+                raise InjectFailException(
+                    f'The annotation of param {param.name} is missing, add an annotation or give it a default value'
+                )
+            # 2.2. with annotation
+            if get_origin(param.annotation) == Annotated:
+                # 2.2.1 Annotated
+                tp, name, *_ = get_args(param.annotation)
+                if isinstance(name, str):
+                    # 2.2.1.1 name is str, as dependency's name to _inject
+                    params_dict.update({param.name: _inject(app_record, tp, name)})
+                else:
+                    # 2.2.1.2 name is not str
+                    params_dict.update({param.name: _inject(app_record, tp)})
+            else:
+                # 2.2.2 other
+                params_dict.update({param.name: _inject(app_record, param.annotation)})
+    return params_dict
+
+
+# ------------------------------------------------------- Bean ------------------------------------------------------- #
+
+
+def collect_bean(app_record: AppRecord, func: Callable, name: str | None = None):
+    """
+    1. run function decorated by Bean decorator
+    2. add the result to deps_store
+
+    Args:
+        app_record (AppRecord)
+        func (Callable): func
+        name (str | None, optional): name of dep
+    """
+    params: list[Parameter] = list(signature(func).parameters.values())
+    return_annotations = signature(func).return_annotation
+    instance = func(**inject_params_deps(app_record, params))
+    tp = return_annotations if return_annotations != _empty else type(instance)
+    if name is None:
+        dep_store.add_dep_by_type(TypeDepRecord(tp, instance))
+    else:
+        dep_store.add_dep_by_name(NameDepRecord(tp, instance, name))
+
+
+@overload
+def Bean(value: str): ...
+@overload
+def Bean(value: Callable[..., T]): ...
+@no_type_check
+def Bean(value: str | Callable[..., T]) -> Callable[..., T]:
+    """A decorator, will collect the return value of the func decorated by Bean
+    # Example
+    1. collect by `type`
+    ```python
+    @dataclass
+    class Foo:
+        bar: str
+
+    @Bean
+    def _():
+        return Foo('baz')
+    ```
+
+    2. collect by `name`
+    ```python
+    class User(BaseModel):
+        name: str = Field(max_length=20)
+        age: int = Field(gt=0)
+
+    @Bean('user1')
+    def _():
+        return User(name='zs', age=20)
+
+    @Bean('user2)
+    def _():
+        return User(name='zs', age=21)
+    ```
+    """
+    app_record = app_store.get(get_call_filename())
+
+    if callable(value):
+        collect_bean(app_record, value)
+        return value
+    else:
+
+        def wrapper(func: Callable[..., T]) -> Callable[..., T]:
+            collect_bean(app_record, func, value)
+            return func
+
+        return wrapper
+
+
+# ---------------------------------------------------- Injectable ---------------------------------------------------- #
+def inject_init_deps_and_get_instance(app_record: AppRecord, cls: type[T]) -> T:
+    """_inject cls's __init__ params and get params deps"""
+    old_params = list(signature(cls.__init__).parameters.values())[1:]  # self
+    new_params = [
+        i for i in old_params if i.kind not in (Parameter.VAR_KEYWORD, Parameter.VAR_POSITIONAL)
+    ]  # *args、**kwargs
+    return cls(**inject_params_deps(app_record, new_params))
+
+
+def collect_dep(app_record: AppRecord, cls: type, name: str | None = None):
+    """init class decorated by Inject decorator and collect it's instance as dependency"""
+    if hasattr(cls.__init__, '__globals__'):
+        cls.__init__.__globals__[cls.__name__] = cls  # avoid error when getting cls in __init__ method
+    instance = inject_init_deps_and_get_instance(app_record, cls)
+    if name is None:
+        dep_store.add_dep_by_type(TypeDepRecord(cls, instance))
+    else:
+        dep_store.add_dep_by_name(NameDepRecord(cls, instance, name))
+
+
+@overload
+def Injectable(value: str): ...
+@overload
+def Injectable(value: type[T]): ...
+
+
+@no_type_check
+def Injectable(value: str | type[T]) -> type[T]:
+    """decorate a class and collect it's instance as a dependency
+    # Example
+    ```python
+    @Injectable
+    class Foo:...
+
+    @Injectable('bar1')
+    class Bar:...
+    ```
+
+    """
+    app_record = app_store.get((get_call_filename()))
+    if isclass(value):
+        collect_dep(app_record, value)
+        return value
+    else:
+
+        def wrapper(cls: type[T]):
+            collect_dep(app_record, cls, value)
+            return cls
+
+        return wrapper
+
+
+# ------------------------------------------------------ Inject ------------------------------------------------------ #
+class AtUsable(type):
+    """support @"""
+
+    def __matmul__(self: type['Inject'], other: type[T]) -> T:
+        filename = get_call_filename()
+        app_record = app_store.get(filename)
+        return _inject(app_record, other, self.latest_named_deps_record.get(filename))
+
+    def __rmatmul__(self: type['Inject'], other: type[T]) -> T:
+        filename = get_call_filename()
+        app_record = app_store.get(filename)
+        return _inject(app_record, other, self.latest_named_deps_record.get(filename))
+
+
+class Inject(Generic[T], metaclass=AtUsable):
+    """inject dependency anywhere
+    # Example
+    - inject by **type**
+    ```python
+    a = Inject(Foo)
+    b = Inject @ Foo
+    c = Foo @ Inject
+
+    @Injectable
+    class Bar:
+        a = Inject(Foo)
+        b = Inject @ Foo
+        c = Foo @ Inject
+
+        def __init__(self,ia: Foo, ic: Foo):
+            self.ia = ia
+            self.ib = Inject @ Foo
+            self.ic = ic
+    ```
+
+    - inject by **name**
+    ```python
+    a = Inject(Foo, 'foo1')
+    b = Inject.Qualifier('foo2') @ Foo
+    c = Foo @ Inject.Qualifier('foo3')
+
+    @Injectable
+    class Bar:
+        a = Inject(Foo, 'foo1')
+        b = Inject.Qualifier('foo2') @ Foo
+        c = Foo @ Inject.Qualifier('foo3')
+
+        def __init__(self,ia: Annotated[Foo, 'foo1'], ic: Annotated[Foo, 'foo3']):
+            self.ia = ia
+            self.ib = Inject.Qualifier('foo2') @ Foo
+            self.ic = ic
+    ```
+    """
+
+    latest_named_deps_record: dict[str, str | None] = {}
+
+    def __new__(cls, tp: type[T], name: str | None = None) -> T:
+        """Inject(Type, name = None)"""
+        filename = get_call_filename()
+        cls.latest_named_deps_record.update({filename: name})
+        app_record = app_store.get(filename)
+        res = _inject(app_record, tp, name)
+        cls.latest_named_deps_record.update({filename: None})  # set name None
+        return res
+
+    @classmethod
+    def Qualifier(cls, name: str) -> type['Inject']:
+        """Inject.Qualifier(name)"""
+        filename = get_call_filename()
+
+        class Cls(cls):
+            latest_named_deps_record: dict[str, str] = {filename: name}
+
+        return Cls

fastapi_boot/__init__.py

@@ -0,0 +1,18 @@
+from .DI import Bean
+from .DI import Inject
+from .DI import Inject as Autowired
+from .DI import Injectable
+from .DI import Injectable as Component
+from .DI import Injectable as Repository
+from .DI import Injectable as Service
+from .helper import (
+    ExceptionHandler,
+    OnAppProvided,
+    provide_app,
+    use_dep,
+    use_http_middleware,
+    use_ws_middleware,
+    HTTPMiddleware,
+)
+from .routing import Controller, Delete, Get, Head, Options, Patch, Post, Prefix, Put, Req, Trace
+from .routing import WebSocket as WS

fastapi_boot/const.py

@@ -0,0 +1,120 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from fastapi import FastAPI
+
+from fastapi_boot.model import AppNotFoundException, AppRecord, DependencyDuplicatedException
+
+T = TypeVar('T')
+
+# ---------------------------------------------------- constant ---------------------------------------------------- #
+# use_dep placeholder
+REQ_DEP_PLACEHOLDER = "fastapi_boot___dependency_placeholder"
+
+
+# route record's key in controller
+CONTROLLER_ROUTE_RECORD = "fastapi_boot___controller_route_record"
+
+# prefix of use_dep params in endpoint
+USE_DEP_PREFIX_IN_ENDPOINT = 'fastapi_boot__use_dep_prefix'
+
+
+# use_middleware placeholder
+USE_MIDDLEWARE_FIELD_PLACEHOLDER = 'fastapi_boot__use_middleware_field_placeholder'
+
+
+class BlankPlaceholder: ...
+
+
+# PRIORITY OF EXCEPTION_HANDLER
+EXCEPTION_HANDLER_PRIORITY = 1
+
+
+# ------------------------------------------------------- store ------------------------------------------------------ #
+
+
+@dataclass
+class TypeDepRecord(Generic[T]):
+    tp: type[T]
+    value: T
+
+
+@dataclass
+class NameDepRecord(Generic[T], TypeDepRecord[T]):
+    name: str
+
+
+class DependencyStore(Generic[T]):
+    def __init__(self):
+        self.type_deps: dict[type[T], TypeDepRecord[T]] = {}
+        self.name_deps: dict[str, NameDepRecord[T]] = {}
+
+    def add_dep_by_type(self, dep: TypeDepRecord[T]):
+        if dep.tp in self.type_deps:
+            raise DependencyDuplicatedException(f'Dependency {dep.tp} duplicated')
+        self.type_deps.update({dep.tp: dep})
+
+    def add_dep_by_name(self, dep: NameDepRecord[T]):
+        if self.name_deps.get(dep.name):
+            raise DependencyDuplicatedException(f'Dependency name {dep.name} duplicated')
+        self.name_deps.update({dep.name: dep})
+
+    def inject_by_type(self, tp: type[T]) -> T | None:
+        if res := self.type_deps.get(tp):
+            return res.value
+
+    def inject_by_name(self, name: str, tp: type[T]) -> T | None:
+        if find := self.name_deps.get(name):
+            if find.tp == tp:
+                return find.value
+
+    def clear(self):
+        self.type_deps.clear()
+        self.name_deps.clear()
+
+
+class AppStore(Generic[T]):
+    def __init__(self):
+        self.app_dic: dict[str, AppRecord] = {}
+
+    def add(self, path: str, app_record: AppRecord):
+        self.app_dic.update({path: app_record})
+
+    def get(self, path: str) -> AppRecord:
+        path = path[0].upper() + path[1:]
+        for k, v in self.app_dic.items():
+            if path.startswith(k):
+                return v
+        raise AppNotFoundException(f'Can"t find app of "{path}"')
+
+    def clear(self):
+        self.app_dic.clear()
+
+
+class TaskStore:
+    def __init__(self):
+        # will be called after the app becomes available
+        self.late_tasks: dict[str, list[tuple[Callable[[FastAPI], None], int]]] = {}
+
+    def add_late_task(self, path: str, task: Callable[[FastAPI], None], priority: int):
+        if curr_tasks := self.late_tasks.get(path):
+            self.late_tasks.update({path: [*curr_tasks, (task, priority)]})
+        else:
+            self.late_tasks.update({path: [(task, priority)]})
+            
+
+    def run_late_tasks(self):
+        for path, late_tasks in self.late_tasks.items():
+            app = app_store.get(path).app
+            late_tasks.sort(key=lambda x: x[1], reverse=True)
+            for record in late_tasks:
+                record[0](app)
+
+    def clear(self):
+        self.late_tasks.clear()
+
+
+dep_store = DependencyStore()
+app_store = AppStore()
+task_store = TaskStore()

fastapi_boot/helper.py

@@ -0,0 +1,301 @@
+import concurrent
+import concurrent.futures
+from dataclasses import asdict, is_dataclass
+import os
+from collections.abc import  Callable, Coroutine
+from concurrent.futures import Future, ThreadPoolExecutor
+from pathlib import Path
+import sys
+from typing import Any, TypeVar
+from inspect import iscoroutinefunction
+from pydantic import BaseModel
+
+from fastapi import Depends, FastAPI, Request, Response, WebSocket
+
+from fastapi.responses import JSONResponse
+from fastapi_boot.const import REQ_DEP_PLACEHOLDER, USE_MIDDLEWARE_FIELD_PLACEHOLDER,EXCEPTION_HANDLER_PRIORITY, BlankPlaceholder, app_store, task_store,dep_store
+from fastapi_boot.model import AppRecord,UseMiddlewareRecord
+from fastapi_boot.util import get_call_filename
+T = TypeVar('T')
+
+
+def use_dep(dependency: Callable[..., T] | None, use_cache: bool = True) -> T:
+    """Depends of FastAPI with type hint
+    - use it as value of a controller's classvar
+
+    # Example
+    ```python
+    def get_ua(request: Request):
+        return request.headers.get('user-agent','')
+
+    @Controller('/foo')
+    class Foo:
+        ua = use_dep(get_ua)
+
+        @Get('/ua')
+        def foo(self):
+            return self.ua
+
+    ```
+    """
+    value: T = Depends(dependency=dependency, use_cache=use_cache)
+    setattr(value, REQ_DEP_PLACEHOLDER, True)
+    return value
+
+
+
+def _create_bp_from_record(record:UseMiddlewareRecord):
+    bp=BlankPlaceholder()
+    setattr(bp, USE_MIDDLEWARE_FIELD_PLACEHOLDER, record)
+    return bp
+
+def use_http_middleware(*dispatches: Callable[[Request, Callable[[Request], Coroutine[Any, Any, Response]]], Any]):
+    """add http middlewares for current Controller or Prefix with http endpoint, exclude inner Prefix
+
+    ```python
+    
+    from collections.abc import Callable
+    from typing import Any
+    from fastapi import Request
+    from fastapi_boot import Controller, use_http_middleware
+
+
+    async def middleware_foo(request: Request, call_next: Callable[[Request], Any]):
+        print('middleware_foo before')
+        resp = await call_next(request)
+        print('middleware_foo after')
+        return resp
+
+    async def middleware_bar(request: Request, call_next: Callable[[Request], Any]):
+        print('middleware_bar before')
+        resp = await call_next(request)
+        print('middleware_bar after')
+        return resp
+
+    @Controller('/foo')
+    class FooController:
+        _ = use_http_middleware(middleware_foo, middleware_bar)
+        
+        # 1. middleware_bar before
+        # 2. middleware_foo before
+        # 3. call endpoint
+        # 4. middleware_foo after
+        # 5. middleware_bar after
+
+        # ...
+    ```
+
+    """
+    record=UseMiddlewareRecord(http_dispatches=list(dispatches))
+    return _create_bp_from_record(record)
+
+def use_ws_middleware(*dispatches: Callable[[WebSocket,Callable[[WebSocket],Coroutine[Any,Any,None]]],Any],only_message:bool=False):
+    """add websocket middlewares for current Controller or Prefix with websocket endpoint, exclude inner Prefix
+    - if `only_message` and message's type != 'websocket.senf': will ignore dispatches
+    
+    ```python 
+    
+    from collections.abc import Callable
+    from typing import Any
+    from fastapi import Request, WebSocket
+    from fastapi_boot import Controller, use_http_middleware, middleware_ws_foo
+    
+    async def middleware_ws_foo(websocket: WebSocket, call_next: Callable):
+        print('before ws send data foo') # as pos a
+        res = await call_next(websocket)
+        print('after ws send data foo') # as pos b
+        return res
+
+    async def middleware_ws_bar(websocket: WebSocket, call_next: Callable):
+        print('before ws send data bar') # as pso c
+        res = await call_next()
+        print('after ws send data bar') # as pso d
+        return res
+    
+    async def middleware_bar(request: Request, call_next: Callable[[Request], Any]):
+        print('middleware_bar before') # as pos e
+        resp = await call_next(request)
+        print('middleware_bar after') # as pos f
+        return resp
+     
+     
+    @Controller('/chat')
+    class WsController:
+        _ = use_http_middleware(middleware_bar)
+        ___ = use_ws_middleware(middleware_ws_bar, middleware_ws_foo, only_message=True)
+        
+        @Socket('/chat')
+        async def chat(self, websocket: WebSocket):
+            try:
+                await websocket.accept()
+                while True:
+                    message = await websocket.receive_text()
+                    # a c
+                    await self.send_text(message)
+                    # d b
+            except:
+                ...
+
+        
+        # e a c d b f
+        @Post('/broadcast')
+        async def send_broadcast_msg(self, msg: str = Query()):
+            await self.broadcast(msg)
+            return 'ok'
+    ```
+    
+    """
+    record=UseMiddlewareRecord(ws_dispatches=list(dispatches),ws_only_message=only_message)
+    return _create_bp_from_record(record)
+
+
+def HTTPMiddleware(dispatch:Callable[[Request, Callable[[Request], Coroutine[Any, Any, Response]]], Any]):
+    """Add global http middleware
+
+    Args:
+        dispatch (Callable[[Request, Callable[[Request], Coroutine[Any, Any, Response]]], Any]): middleware handler
+    Example:
+    ```python
+    from collections.abc import Callable
+    from fastapi import Request
+    from fastapi_boot import HTTPMiddleware
+
+    @HTTPMiddleware
+    async def barMiddleware(request: Request, call_next: Callable):
+        print("before")
+        res = await call_next(request)
+        print("after")
+        return res
+
+    ```
+    """
+    app_store.get(get_call_filename()).app.middleware('http')(dispatch)
+    return dispatch
+
+def provide_app(app: FastAPI, max_workers: int = 20, inject_timeout: float = 20, inject_retry_step: float = 0.05):
+    """enable scan project to collect dependencies which can't been collected automatically
+
+    Args:
+        app (FastAPI): FastAPI instance
+        max_workers (int, optional): workers' num to scan project. Defaults to 20.
+        inject_timeout (float, optional): will raise DependencyNotFoundException if time > inject_timeout. Defaults to 20.
+        inject_pause_step (float, optional): Retry interval after failing to find a dependency . Defaults to 0.05.
+
+    Returns:
+        _type_: original app
+    """
+    # clear store before init
+    app_store.clear()
+    dep_store.clear()
+    task_store.clear()
+    
+    provide_filepath = get_call_filename()
+    # the file which provides app
+    app_root_dir = os.path.dirname(provide_filepath)
+    app_record = AppRecord(app, inject_timeout, inject_retry_step)
+    app_store.add(os.path.dirname(provide_filepath), app_record)
+    # app's prefix in project
+    proj_root_dir = os.getcwd()
+    app_parts = Path(app_root_dir).parts
+    proj_parts = Path(proj_root_dir).parts
+    prefix_parts = app_parts[len(proj_parts) :]
+    # scan
+    dot_paths = []
+    for root, _, files in os.walk(app_root_dir):
+        for file in files:
+            if file.endswith('.py'):
+                fullpath = os.path.join(root, file)
+                if fullpath == provide_filepath:
+                    continue
+                dot_path = '.'.join(
+                    prefix_parts + Path(fullpath.replace('.py', '').replace(app_root_dir, '')).parts[1:]
+                )
+                dot_paths.append(dot_path)
+                # clear module cache if exists
+                if dot_path in sys.modules:
+                    sys.modules.pop(dot_path)
+    
+    futures: list[Future] = []
+    with ThreadPoolExecutor(max_workers) as executor:
+        for dot_path in dot_paths:
+            future = executor.submit(__import__,dot_path)
+            futures.append(future)
+        concurrent.futures.wait(futures)
+        # wait all future finished
+        for future in futures:
+            future.result()
+    # before return , run tasks
+    task_store.run_late_tasks()
+    return app
+
+
+def OnAppProvided(priority: int = 1):
+    """Methods to be executed after the app is provided
+    - decorated function should be sync.
+    ```python
+    @OnAppProvided()
+    def _(app:FastAPI):
+        print('foo')
+
+    @OnAppProvided(priority=10):
+    def func():
+        print('bar')
+
+    # bar >> foo
+    ```
+    """
+
+    def wrapper(func: Callable[[FastAPI], None]):
+        task_store.add_late_task(get_call_filename(), func, priority)
+        return func
+
+    return wrapper
+
+
+# -------------------------------------------------------------------------------------------------------------------- #
+E = TypeVar('E', bound=Exception)
+
+HttpHandler = Callable[[Request, E], Any]
+WsHandler = Callable[[WebSocket, E],Any]
+
+
+def ExceptionHandler(exp: int | type[E]):
+    """The return value can be BaseModel instance、dataclass、dict or JSONResponse.
+    ```python
+    @ExceptionHandler(MyException)
+    async def _(req: Request, exp: AException):
+        ...
+    ```
+    Declarative style of the following code:
+    ```python
+    @app.exception_handler(AException)
+    async def _(req: Request, exp: AException):
+        ...
+    @app.exception_handler(BException)
+    def _(req: Request, exp: BException):
+        ...
+
+    @app.exception_handler(CException)
+    async def _(req: WebSocket, exp: CException):
+        ...
+    @app.exception_handler(DException)
+    def _(req: WebSocket, exp: DException):
+        ...
+    ```
+    """
+
+    def decorator(handler: HttpHandler | WsHandler):
+        # wrap handler
+        async def wrapper(*args,**kwds):
+            resp=await handler(*args,**kwds) if iscoroutinefunction(handler) else handler(*args,**kwds)
+            if isinstance(resp,BaseModel):
+                resp=resp.model_dump()
+            elif is_dataclass(resp):
+                resp=asdict(resp)
+            if isinstance(resp,dict):
+                resp=JSONResponse(resp)
+            return resp
+        task_store.add_late_task(get_call_filename(), lambda app: app.add_exception_handler(exp, wrapper), EXCEPTION_HANDLER_PRIORITY)
+        return handler
+
+    return decorator