hypern 0.3.0__cp311-cp311-win_amd64.whl

hypern/__init__.py

@@ -0,0 +1,4 @@
+from .application import Hypern
+from .hypern import Request, Response
+
+__all__ = ["Hypern", "Request", "Response"]

hypern/application.py

@@ -0,0 +1,405 @@
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, List, TypeVar
+
+import orjson
+from typing_extensions import Annotated, Doc
+
+from hypern.datastructures import Contact, HTTPMethod, Info, License
+from hypern.hypern import FunctionInfo, Router, Route as InternalRoute, WebsocketRouter
+from hypern.openapi import SchemaGenerator, SwaggerUI
+from hypern.processpool import run_processes
+from hypern.response import HTMLResponse, JSONResponse
+from hypern.routing import Route
+from hypern.scheduler import Scheduler
+from hypern.middleware import Middleware
+from hypern.args_parser import ArgsConfig
+from hypern.ws import WebsocketRoute
+
+AppType = TypeVar("AppType", bound="Hypern")
+
+
+class Hypern:
+    def __init__(
+        self: AppType,
+        routes: Annotated[
+            List[Route] | None,
+            Doc(
+                """
+                A list of routes to serve incoming HTTP and WebSocket requests.
+                You can define routes using the `Route` class from `Hypern.routing`.
+                **Example**
+                ---
+                ```python
+                class DefaultRoute(HTTPEndpoint):
+                    async def get(self, global_dependencies):
+                        return PlainTextResponse("/hello")
+                Route("/test", DefaultRoute)
+
+                # Or you can define routes using the decorator
+                route = Route("/test)
+                @route.get("/route")
+                def def_get():
+                    return PlainTextResponse("Hello")
+                ```
+                """
+            ),
+        ] = None,
+        websockets: Annotated[
+            List[WebsocketRoute] | None,
+            Doc(
+                """
+                A list of routes to serve incoming WebSocket requests.
+                You can define routes using the `WebsocketRoute` class from `Hypern
+                """
+            ),
+        ] = None,
+        title: Annotated[
+            str,
+            Doc(
+                """
+                The title of the API.
+
+                It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+                Read more in the
+                """
+            ),
+        ] = "Hypern",
+        summary: Annotated[
+            str | None,
+            Doc(
+                """"
+                A short summary of the API.
+
+                It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+                """
+            ),
+        ] = None,
+        description: Annotated[
+            str,
+            Doc(
+                """
+                A description of the API. Supports Markdown (using
+                [CommonMark syntax](https://commonmark.org/)).
+
+                It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+                """
+            ),
+        ] = "",
+        version: Annotated[
+            str,
+            Doc(
+                """
+                The version of the API.
+
+                **Note** This is the version of your application, not the version of
+                the OpenAPI specification nor the version of Application being used.
+
+                It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+                """
+            ),
+        ] = "0.0.1",
+        contact: Annotated[
+            Contact | None,
+            Doc(
+                """
+                A dictionary with the contact information for the exposed API.
+
+                It can contain several fields.
+
+                * `name`: (`str`) The name of the contact person/organization.
+                * `url`: (`str`) A URL pointing to the contact information. MUST be in
+                    the format of a URL.
+                * `email`: (`str`) The email address of the contact person/organization.
+                    MUST be in the format of an email address.            
+                """
+            ),
+        ] = None,
+        openapi_url: Annotated[
+            str | None,
+            Doc(
+                """
+                The URL where the OpenAPI schema will be served from.
+
+                If you set it to `None`, no OpenAPI schema will be served publicly, and
+                the default automatic endpoints `/docs` and `/redoc` will also be
+                disabled.
+            """
+            ),
+        ] = "/openapi.json",
+        docs_url: Annotated[
+            str | None,
+            Doc(
+                """
+                The path to the automatic interactive API documentation.
+                It is handled in the browser by Swagger UI.
+
+                The default URL is `/docs`. You can disable it by setting it to `None`.
+
+                If `openapi_url` is set to `None`, this will be automatically disabled.
+            """
+            ),
+        ] = "/docs",
+        license_info: Annotated[
+            License | None,
+            Doc(
+                """
+                A dictionary with the license information for the exposed API.
+
+                It can contain several fields.
+
+                * `name`: (`str`) **REQUIRED** (if a `license_info` is set). The
+                    license name used for the API.
+                * `identifier`: (`str`) An [SPDX](https://spdx.dev/) license expression
+                    for the API. The `identifier` field is mutually exclusive of the `url`
+                    field. Available since OpenAPI 3.1.0
+                * `url`: (`str`) A URL to the license used for the API. This MUST be
+                    the format of a URL.
+
+                It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+                **Example**
+
+                ```python
+                app = Hypern(
+                    license_info={
+                        "name": "Apache 2.0",
+                        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
+                    }
+                )
+                ```
+                """
+            ),
+        ] = None,
+        scheduler: Annotated[
+            Scheduler | None,
+            Doc(
+                """
+                A scheduler to run background tasks.
+                """
+            ),
+        ] = None,
+        default_injectables: Annotated[
+            dict[str, Any] | None,
+            Doc(
+                """
+                A dictionary of default injectables to be passed to all routes.
+                """
+            ),
+        ] = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.router = Router(path="/")
+        self.websocket_router = WebsocketRouter(path="/")
+        self.scheduler = scheduler
+        self.injectables = default_injectables or {}
+        self.middleware_before_request = []
+        self.middleware_after_request = []
+        self.response_headers = {}
+        self.args = ArgsConfig()
+
+        for route in routes or []:
+            self.router.extend_route(route(app=self).routes)
+
+        for websocket_route in websockets or []:
+            self.websocket_router.add_route(websocket_route)
+
+        if openapi_url and docs_url:
+            self.__add_openapi(
+                info=Info(
+                    title=title,
+                    summary=summary,
+                    description=description,
+                    version=version,
+                    contact=contact,
+                    license=license_info,
+                ),
+                openapi_url=openapi_url,
+                docs_url=docs_url,
+            )
+
+    def __add_openapi(
+        self,
+        info: Info,
+        openapi_url: str,
+        docs_url: str,
+    ):
+        """
+        Adds OpenAPI schema and documentation routes to the application.
+
+        Args:
+            info (Info): An instance of the Info class containing metadata about the API.
+            openapi_url (str): The URL path where the OpenAPI schema will be served.
+            docs_url (str): The URL path where the Swagger UI documentation will be served.
+
+        The method defines two internal functions:
+            - schema: Generates and returns the OpenAPI schema as a JSON response.
+            - template_render: Renders and returns the Swagger UI documentation as an HTML response.
+
+        The method then adds routes to the application for serving the OpenAPI schema and the Swagger UI documentation.
+        """
+
+        def schema(*args, **kwargs):
+            schemas = SchemaGenerator(
+                {
+                    "openapi": "3.0.0",
+                    "info": info.model_dump(),
+                    "components": {"securitySchemes": {}},
+                }
+            )
+            return JSONResponse(content=orjson.dumps(schemas.get_schema(self)))
+
+        def template_render(*args, **kwargs):
+            swagger = SwaggerUI(
+                title="Swagger",
+                openapi_url=openapi_url,
+            )
+            template = swagger.get_html_content()
+            return HTMLResponse(template)
+
+        self.add_route(HTTPMethod.GET, openapi_url, schema)
+        self.add_route(HTTPMethod.GET, docs_url, template_render)
+
+    def add_response_header(self, key: str, value: str):
+        """
+        Adds a response header to the response headers dictionary.
+
+        Args:
+            key (str): The header field name.
+            value (str): The header field value.
+        """
+        self.response_headers[key] = value
+
+    def before_request(self):
+        """
+        A decorator to register a function to be executed before each request.
+
+        This decorator can be used to add middleware functions that will be
+        executed before the main request handler. The function can be either
+        synchronous or asynchronous.
+
+        Returns:
+            function: The decorator function that registers the middleware.
+        """
+
+        def decorator(func):
+            is_async = asyncio.iscoroutinefunction(func)
+            func_info = FunctionInfo(handler=func, is_async=is_async)
+            self.middleware_before_request.append(func_info)
+            return func
+
+        return decorator
+
+    def after_request(self):
+        """
+        Decorator to register a function to be called after each request.
+
+        This decorator can be used to register both synchronous and asynchronous functions.
+        The registered function will be wrapped in a FunctionInfo object and appended to the
+        middleware_after_request list.
+
+        Returns:
+            function: The decorator function that registers the given function.
+        """
+
+        def decorator(func):
+            is_async = asyncio.iscoroutinefunction(func)
+            func_info = FunctionInfo(handler=func, is_async=is_async)
+            self.middleware_after_request.append(func_info)
+            return func
+
+        return decorator
+
+    def inject(self, key: str, value: Any):
+        """
+        Injects a key-value pair into the injectables dictionary.
+
+        Args:
+            key (str): The key to be added to the injectables dictionary.
+            value (Any): The value to be associated with the key.
+
+        Returns:
+            self: Returns the instance of the class to allow method chaining.
+        """
+        self.injectables[key] = value
+        return self
+
+    def add_middleware(self, middleware: Middleware):
+        """
+        Adds middleware to the application.
+
+        This method attaches the middleware to the application instance and registers
+        its `before_request` and `after_request` hooks if they are defined.
+
+        Args:
+            middleware (Middleware): The middleware instance to be added.
+
+        Returns:
+            self: The application instance with the middleware added.
+        """
+        setattr(middleware, "app", self)
+        before_request = getattr(middleware, "before_request", None)
+        after_request = getattr(middleware, "after_request", None)
+
+        if before_request:
+            self.before_request()(before_request)
+        if after_request:
+            self.after_request()(after_request)
+        return self
+
+    def start(
+        self,
+    ):
+        """
+        Starts the server with the specified configuration.
+        Raises:
+            ValueError: If an invalid port number is entered when prompted.
+
+        """
+        if self.scheduler:
+            self.scheduler.start()
+
+        run_processes(
+            host=self.args.host,
+            port=self.args.port,
+            workers=self.args.workers,
+            processes=self.args.processes,
+            max_blocking_threads=self.args.max_blocking_threads,
+            router=self.router,
+            websocket_router=self.websocket_router,
+            injectables=self.injectables,
+            before_request=self.middleware_before_request,
+            after_request=self.middleware_after_request,
+            response_headers=self.response_headers,
+            reload=self.args.reload,
+        )
+
+    def add_route(self, method: HTTPMethod, endpoint: str, handler: Callable[..., Any]):
+        """
+        Adds a route to the router.
+
+        Args:
+            method (HTTPMethod): The HTTP method for the route (e.g., GET, POST).
+            endpoint (str): The endpoint path for the route.
+            handler (Callable[..., Any]): The function that handles requests to the route.
+
+        """
+        is_async = asyncio.iscoroutinefunction(handler)
+        func_info = FunctionInfo(handler=handler, is_async=is_async)
+        route = InternalRoute(path=endpoint, function=func_info, method=method.name)
+        self.router.add_route(route=route)
+
+    def add_websocket(self, ws_route: WebsocketRoute):
+        """
+        Adds a WebSocket route to the WebSocket router.
+
+        Args:
+            ws_route (WebsocketRoute): The WebSocket route to be added to the router.
+        """
+        for route in ws_route.routes:
+            self.websocket_router.add_route(route=route)

hypern/args_parser.py

@@ -0,0 +1,59 @@
+import argparse
+
+
+class ArgsConfig:
+    def __init__(self) -> None:
+        parser = argparse.ArgumentParser(description="Hypern: A Versatile Python and Rust Framework")
+        self.parser = parser
+        parser.add_argument(
+            "--host",
+            type=str,
+            default=None,
+            required=False,
+            help="Choose the host. [Defaults to `127.0.0.1`]",
+        )
+
+        parser.add_argument(
+            "--port",
+            type=int,
+            default=None,
+            required=False,
+            help="Choose the port. [Defaults to `5000`]",
+        )
+
+        parser.add_argument(
+            "--processes",
+            type=int,
+            default=None,
+            required=False,
+            help="Choose the number of processes. [Default: 1]",
+        )
+        parser.add_argument(
+            "--workers",
+            type=int,
+            default=None,
+            required=False,
+            help="Choose the number of workers. [Default: 1]",
+        )
+
+        parser.add_argument(
+            "--max-blocking-threads",
+            type=int,
+            default=None,
+            required=False,
+            help="Choose the maximum number of blocking threads. [Default: 100]",
+        )
+
+        parser.add_argument(
+            "--reload",
+            action="store_true",
+            help="It restarts the server based on file changes.",
+        )
+        args, _ = parser.parse_known_args()
+
+        self.host = args.host or "127.0.0.1"
+        self.port = args.port or 5000
+        self.max_blocking_threads = args.max_blocking_threads or 100
+        self.processes = args.processes or 1
+        self.workers = args.workers or 1
+        self.reload = args.reload or False

hypern/auth/authorization.py

@@ -0,0 +1,2 @@
+class Authorization:
+    pass

hypern/background.py

@@ -0,0 +1,4 @@
+from .hypern import BackgroundTask
+from .hypern import BackgroundTasks
+
+__all__ = ["BackgroundTask", "BackgroundTasks"]

hypern/caching/base/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+from .backend import BaseBackend
+from .key_maker import BaseKeyMaker
+
+__all__ = [
+    "BaseKeyMaker",
+    "BaseBackend",
+]

hypern/caching/base/backend.py

@@ -0,0 +1,3 @@
+from hypern.hypern import BaseBackend
+
+__all__ = ["BaseBackend"]

hypern/caching/base/key_maker.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+from abc import ABC, abstractmethod
+from typing import Callable
+
+
+class BaseKeyMaker(ABC):
+    @abstractmethod
+    async def make(self, function: Callable, prefix: str, identify_key: str) -> str: ...

hypern/caching/cache_manager.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+from functools import wraps
+from typing import Callable, Dict, Type
+
+from .base import BaseBackend, BaseKeyMaker
+from .cache_tag import CacheTag
+import orjson
+
+
+class CacheManager:
+    def __init__(self):
+        self.backend = None
+        self.key_maker = None
+
+    def init(self, backend: BaseBackend, key_maker: BaseKeyMaker) -> None:
+        self.backend = backend
+        self.key_maker = key_maker
+
+    def cached(self, tag: CacheTag, ttl: int = 60, identify: Dict = {}) -> Type[Callable]:
+        def _cached(function):
+            @wraps(function)
+            async def __cached(*args, **kwargs):
+                if not self.backend or not self.key_maker:
+                    raise ValueError("Backend or KeyMaker not initialized")
+
+                _identify_key = []
+                for key, values in identify.items():
+                    _obj = kwargs.get(key, None)
+                    if not _obj:
+                        raise ValueError(f"Caching: Identify key {key} not found in kwargs")
+                    for attr in values:
+                        _identify_key.append(f"{attr}={getattr(_obj, attr)}")
+                _identify_key = ":".join(_identify_key)
+
+                key = await self.key_maker.make(function=function, prefix=tag.value, identify_key=_identify_key)
+
+                cached_response = self.backend.get(key=key)
+                if cached_response:
+                    return orjson.loads(cached_response)
+
+                response = await function(*args, **kwargs)
+                self.backend.set(response=orjson.dumps(response).decode("utf-8"), key=key, ttl=ttl)
+                return response
+
+            return __cached
+
+        return _cached  # type: ignore
+
+    async def remove_by_tag(self, tag: CacheTag) -> None:
+        await self.backend.delete_startswith(value=tag.value)
+
+    async def remove_by_prefix(self, prefix: str) -> None:
+        await self.backend.delete_startswith(value=prefix)
+
+
+Cache = CacheManager()

hypern/caching/cache_tag.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+from enum import Enum
+
+
+class CacheTag(Enum):
+    GET_HEALTH_CHECK = "get_health_check"
+    GET_USER_INFO = "get_user_info"
+    GET_CATEGORIES = "get_categories"
+    GET_HISTORY = "get_chat_history"
+    GET_QUESTION = "get_question"

hypern/caching/custom_key_maker.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+from typing import Callable
+import inspect
+
+from hypern.caching.base import BaseKeyMaker
+
+
+class CustomKeyMaker(BaseKeyMaker):
+    async def make(self, function: Callable, prefix: str, identify_key: str = "") -> str:
+        path = f"{prefix}:{inspect.getmodule(function).__name__}.{function.__name__}:{identify_key}"  # type: ignore
+        return str(path)

hypern/caching/redis_backend.py

@@ -0,0 +1,3 @@
+from hypern.hypern import RedisBackend
+
+__all__ = ["RedisBackend"]