hypern 0.2.0__cp312-none-win32.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,412 @@
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+import asyncio
+import socket
+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.exceptions import InvalidPortNumber
+from hypern.hypern import FunctionInfo, Router
+from hypern.hypern import Route as InternalRoute
+from hypern.logging import logger
+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
+
+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,
+        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.scheduler = scheduler
+        self.injectables = default_injectables or {}
+        self.middleware_before_request = []
+        self.middleware_after_request = []
+        self.response_headers = {}
+
+        for route in routes:
+            self.router.extend_route(route(app=self).routes)
+
+        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 is_port_in_use(self, port: int) -> bool:
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                return s.connect_ex(("localhost", port)) == 0
+        except Exception:
+            raise InvalidPortNumber(f"Invalid port number: {port}")
+
+    def start(
+        self,
+        host: Annotated[str, Doc("The host to run the server on. Defaults to `127.0.0.1`")] = "127.0.0.1",
+        port: Annotated[int, Doc("The port to run the server on. Defaults to `8080`")] = 8080,
+        workers: Annotated[int, Doc("The number of workers to run. Defaults to `1`")] = 1,
+        processes: Annotated[int, Doc("The number of processes to run. Defaults to `1`")] = 1,
+        max_blocking_threads: Annotated[int, Doc("The maximum number of blocking threads. Defaults to `100`")] = 1,
+        check_port: Annotated[bool, Doc("Check if the port is already in use. Defaults to `True`")] = False,
+    ):
+        """
+        Starts the server with the specified configuration.
+
+        Args:
+            host (str): The host to run the server on. Defaults to `127.0.0.1`.
+            port (int): The port to run the server on. Defaults to `8080`.
+            workers (int): The number of workers to run. Defaults to `1`.
+            processes (int): The number of processes to run. Defaults to `1`.
+            max_blocking_threads (int): The maximum number of blocking threads. Defaults to `100`.
+            check_port (bool): Check if the port is already in use. Defaults to `True`.
+
+        Raises:
+            ValueError: If an invalid port number is entered when prompted.
+
+        """
+        if check_port:
+            while self.is_port_in_use(port):
+                logger.error("Port %s is already in use. Please use a different port.", port)
+                try:
+                    port = int(input("Enter a different port: "))
+                except Exception:
+                    logger.error("Invalid port number. Please enter a valid port number.")
+                    continue
+
+        if self.scheduler:
+            self.scheduler.start()
+
+        run_processes(
+            host=host,
+            port=port,
+            workers=workers,
+            processes=processes,
+            max_blocking_threads=max_blocking_threads,
+            router=self.router,
+            injectables=self.injectables,
+            before_request=self.middleware_before_request,
+            after_request=self.middleware_after_request,
+            response_headers=self.response_headers,
+        )
+
+    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)

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"]

hypern/config.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+import typing
+import warnings
+from pathlib import Path
+
+"""
+
+refer: https://github.com/encode/starlette/blob/master/starlette/config.py
+# Config will be read from environment variables and/or ".env" files.
+config = Config(".env")
+
+DEBUG = config('DEBUG', cast=bool, default=False)
+DATABASE_URL = config('DATABASE_URL')
+ALLOWED_HOSTS = config('ALLOWED_HOSTS', cast=CommaSeparatedStrings)
+"""
+
+
+class undefined:
+    pass
+
+
+class EnvironError(Exception):
+    pass
+
+
+class Environ(typing.MutableMapping[str, str]):
+    def __init__(self, environ: typing.MutableMapping[str, str] = os.environ):
+        self._environ = environ
+        self._has_been_read: set[str] = set()
+
+    def __getitem__(self, key: str) -> str:
+        self._has_been_read.add(key)
+        return self._environ.__getitem__(key)
+
+    def __setitem__(self, key: str, value: str) -> None:
+        if key in self._has_been_read:
+            raise EnvironError(f"Attempting to set environ['{key}'], but the value has already been read.")
+        self._environ.__setitem__(key, value)
+
+    def __delitem__(self, key: str) -> None:
+        if key in self._has_been_read:
+            raise EnvironError(f"Attempting to delete environ['{key}'], but the value has already been read.")
+        self._environ.__delitem__(key)
+
+    def __iter__(self) -> typing.Iterator[str]:
+        return iter(self._environ)
+
+    def __len__(self) -> int:
+        return len(self._environ)
+
+
+environ = Environ()
+
+T = typing.TypeVar("T")
+
+
+class Config:
+    def __init__(
+        self,
+        env_file: str | Path | None = None,
+        environ: typing.Mapping[str, str] = environ,
+        env_prefix: str = "",
+    ) -> None:
+        self.environ = environ
+        self.env_prefix = env_prefix
+        self.file_values: dict[str, str] = {}
+        if env_file is not None:
+            if not os.path.isfile(env_file):
+                warnings.warn(f"Config file '{env_file}' not found.")
+            else:
+                self.file_values = self._read_file(env_file)
+
+    @typing.overload
+    def __call__(self, key: str, *, default: None) -> str | None: ...
+
+    @typing.overload
+    def __call__(self, key: str, cast: type[T], default: T = ...) -> T: ...
+
+    @typing.overload
+    def __call__(self, key: str, cast: type[str] = ..., default: str = ...) -> str: ...
+
+    @typing.overload
+    def __call__(
+        self,
+        key: str,
+        cast: typing.Callable[[typing.Any], T] = ...,
+        default: typing.Any = ...,
+    ) -> T: ...
+
+    @typing.overload
+    def __call__(self, key: str, cast: type[str] = ..., default: T = ...) -> T | str: ...
+
+    def __call__(
+        self,
+        key: str,
+        cast: typing.Callable[[typing.Any], typing.Any] | None = None,
+        default: typing.Any = undefined,
+    ) -> typing.Any:
+        return self.get(key, cast, default)
+
+    def get(
+        self,
+        key: str,
+        cast: typing.Callable[[typing.Any], typing.Any] | None = None,
+        default: typing.Any = undefined,
+    ) -> typing.Any:
+        key = self.env_prefix + key
+        if key in self.environ:
+            value = self.environ[key]
+            return self._perform_cast(key, value, cast)
+        if key in self.file_values:
+            value = self.file_values[key]
+            return self._perform_cast(key, value, cast)
+        if default is not undefined:
+            return self._perform_cast(key, default, cast)
+        raise KeyError(f"Config '{key}' is missing, and has no default.")
+
+    def _read_file(self, file_name: str | Path) -> dict[str, str]:
+        file_values: dict[str, str] = {}
+        with open(file_name) as input_file:
+            for line in input_file.readlines():
+                line = line.strip()
+                if "=" in line and not line.startswith("#"):
+                    key, value = line.split("=", 1)
+                    key = key.strip()
+                    value = value.strip().strip("\"'")
+                    file_values[key] = value
+        return file_values
+
+    def _perform_cast(
+        self,
+        key: str,
+        value: typing.Any,
+        cast: typing.Callable[[typing.Any], typing.Any] | None = None,
+    ) -> typing.Any:
+        if cast is None or value is None:
+            return value
+        elif cast is bool and isinstance(value, str):
+            mapping = {"true": True, "1": True, "false": False, "0": False}
+            value = value.lower()
+            if value not in mapping:
+                raise ValueError(f"Config '{key}' has value '{value}'. Not a valid bool.")
+            return mapping[value]
+        try:
+            return cast(value)
+        except (TypeError, ValueError):
+            raise ValueError(f"Config '{key}' has value '{value}'. Not a valid {cast.__name__}.")