hypern 0.2.0__cp312-none-win32.whl

hypern/hypern.pyi

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Tuple
+
+@dataclass
+class BaseBackend:
+    get: Callable[[str], Any]
+    set: Callable[[Any, str, int], None]
+    delete_startswith: Callable[[str], None]
+
+@dataclass
+class RedisBackend(BaseBackend):
+    url: str
+
+    get: Callable[[str], Any]
+    set: Callable[[Any, str, int], None]
+    delete_startswith: Callable[[str], None]
+
+@dataclass
+class BaseSchemaGenerator:
+    remove_converter: Callable[[str], str]
+    parse_docstring: Callable[[Callable[..., Any]], str]
+
+@dataclass
+class SwaggerUI:
+    title: str
+    openapi_url: str
+
+    def get_html_content(self) -> str: ...
+
+@dataclass
+class BackgroundTask:
+    """
+    A task to be executed in the background
+    id: str: The task ID
+    function: Callable[..., Any]: The function to be executed
+    args: List | Tuple: The arguments to be passed to the function
+    kwargs: Dict[str, Any]: The keyword arguments to be passed to the function
+    timeout_secs: int: The maximum time in seconds the task is allowed to run
+    cancelled: bool: Whether the task is cancelled
+
+    **Note**: function is currently running with sync mode, so it should be a sync function
+    """
+
+    id: str
+    function: Callable[..., Any]
+    args: List | Tuple
+    kwargs: Dict[str, Any]
+    timeout_secs: int
+    cancelled: bool
+
+    def get_id(self) -> str:
+        """
+        Get the task ID
+        """
+        pass
+
+    def cancel(self) -> None:
+        """
+        Cancel the task
+        """
+        pass
+
+    def is_cancelled(self) -> bool:
+        """
+        Check if the task is cancelled
+        """
+        pass
+
+    def execute(self) -> Any:
+        """
+        Execute the task
+        """
+        pass
+
+@dataclass
+class BackgroundTasks:
+    """
+    A collection of tasks to be executed in the background
+
+    **Note**: Only set tasks. pool, sender, receiver are set by the framework
+    """
+
+    def add_task(self, task: BackgroundTask) -> str:
+        """
+        Add a task to the collection
+        """
+        pass
+
+    def cancel_task(self, task_id: str) -> bool:
+        """
+        Cancel a task in the collection
+        """
+        pass
+
+    def execute_all(self) -> None:
+        """
+        Execute all tasks in the collection
+        """
+        pass
+
+    def execute_task(self, task_id: str) -> None:
+        """
+        Execute a task in the collection
+        """
+        pass
+
+class Scheduler:
+    def add_job(
+        self,
+        job_type: str,
+        schedule_param: str,
+        task: Callable[..., Any],
+        timezone: str,
+        dependencies: List[str],
+        retry_policy: Tuple[int, int, bool] | None = None,
+    ) -> str:
+        """
+        Add a job to the scheduler
+        params:
+        job_type: str: The type of the job (e.g. "cron", "interval")
+
+        schedule_param: str: The schedule parameter of the job. interval in seconds for interval jobs, cron expression for cron jobs
+
+        Exmaple:
+        //           sec  min   hour   day of month   month   day of week   year
+        expression = "0   30   9,12,15     1,15       May-Aug  Mon,Wed,Fri  2018/2";
+
+        task: Callable[..., Any]: The task to be executed
+
+        timezone: str: The timezone of the job
+
+        dependencies: List[str]: The IDs of the jobs this job depends on
+
+        retry_policy: Tuple[int, int, bool] | None: The retry policy of the job. (max_retries, retry_delay_secs, exponential_backoff)
+
+        return:
+        str: The ID of the job
+        """
+        pass
+
+    def remove_job(self, job_id: str) -> None:
+        """
+        Remove a job from the scheduler
+        """
+        pass
+
+    def start(self) -> None:
+        """
+        Start the scheduler
+        """
+        pass
+
+    def stop(self) -> None:
+        """
+        Stop the scheduler
+        """
+        pass
+
+    def get_job_status(self, job_id: str) -> Tuple[float, float, List[str], int]:
+        """
+        Get the status of a job
+        """
+        pass
+
+    def get_next_run(self, job_id: str) -> float:
+        """
+        Get the next run time of a job
+        """
+        pass
+
+@dataclass
+class FunctionInfo:
+    """
+    The function info object passed to the route handler.
+
+    Attributes:
+        handler (Callable): The function to be called
+        is_async (bool): Whether the function is async or not
+    """
+
+    handler: Callable
+    is_async: bool
+
+class SocketHeld:
+    socket: Any
+
+@dataclass
+class Server:
+    router: Router
+    websocket_router: Any
+    startup_handler: Any
+    shutdown_handler: Any
+
+    def add_route(self, route: Route) -> None: ...
+    def set_router(self, router: Router) -> None: ...
+    def start(self, socket: SocketHeld, worker: int, max_blocking_threads: int) -> None: ...
+    def inject(self, key: str, value: Any) -> None: ...
+    def set_injected(self, injected: Dict[str, Any]) -> None: ...
+    def set_before_hooks(self, hooks: List[FunctionInfo]) -> None: ...
+    def set_after_hooks(self, hooks: List[FunctionInfo]) -> None: ...
+    def set_response_headers(self, headers: Dict[str, str]) -> None: ...
+
+class Route:
+    path: str
+    function: FunctionInfo
+    method: str
+
+    def matches(self, path: str, method: str) -> str: ...
+    def clone_route(self) -> Route: ...
+    def update_path(self, new_path: str) -> None: ...
+    def update_method(self, new_method: str) -> None: ...
+    def is_valid(self) -> bool: ...
+    def get_path_parans(self) -> List[str]: ...
+    def has_parameters(self) -> bool: ...
+    def normalized_path(self) -> str: ...
+    def same_handler(self, other: Route) -> bool: ...
+
+class Router:
+    routes: List[Route]
+
+    def add_route(self, route: Route) -> None: ...
+    def remove_route(self, path: str, method: str) -> bool: ...
+    def get_route(self, path: str, method) -> Route | None: ...
+    def get_routes_by_path(self, path: str) -> List[Route]: ...
+    def get_routes_by_method(self, method: str) -> List[Route]: ...
+    def extend_route(self, routes: List[Route]) -> None: ...
+
+@dataclass
+class Header:
+    headers: Dict[str, str]
+
+@dataclass
+class Response:
+    status_code: int
+    response_type: str
+    headers: Any
+    description: str
+    file_path: str
+
+@dataclass
+class QueryParams:
+    queries: Dict[str, List[str]]
+
+@dataclass
+class UploadedFile:
+    name: str
+    content_type: str
+    path: str
+    size: int
+    content: bytes
+    filename: str
+
+@dataclass
+class BodyData:
+    json: bytes
+    files: List[UploadedFile]
+
+@dataclass
+class Request:
+    query_params: QueryParams
+    headers: Dict[str, str]
+    path_params: Dict[str, str]
+    body: BodyData
+    method: str

hypern/logging/__init__.py

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

hypern/logging/logger.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+import logging
+import sys
+from copy import copy
+from datetime import datetime, timezone
+from typing import Literal, Optional
+
+import click
+
+TRACE_LOG_LEVEL = 5
+
+
+class ColourizedFormatter(logging.Formatter):
+    level_name_colors = {
+        TRACE_LOG_LEVEL: lambda level_name: click.style(str(level_name), fg="blue"),
+        logging.DEBUG: lambda level_name: click.style(str(level_name), fg="cyan"),
+        logging.INFO: lambda level_name: click.style(str(level_name), fg="green"),
+        logging.WARNING: lambda level_name: click.style(str(level_name), fg="yellow"),
+        logging.ERROR: lambda level_name: click.style(str(level_name), fg="red"),
+        logging.CRITICAL: lambda level_name: click.style(str(level_name), fg="bright_red"),
+    }
+
+    def __init__(
+        self,
+        fmt: Optional[str] = None,
+        datefmt: Optional[str] = None,
+        style: Literal["%", "{", "$"] = "%",
+        use_colors: Optional[bool] = None,
+    ):
+        if use_colors in (True, False):
+            self.use_colors = use_colors
+        else:
+            self.use_colors = sys.stdout.isatty()
+        super().__init__(fmt=fmt, datefmt=datefmt, style=style)
+
+    def color_level_name(self, level_name: str, level_no: int) -> str:
+        def default(level_name: str) -> str:
+            return str(level_name)
+
+        func = self.level_name_colors.get(level_no, default)
+        return func(level_name)
+
+    def should_use_colors(self) -> bool:
+        return True
+
+    def formatMessage(self, record: logging.LogRecord) -> str:
+        recordcopy = copy(record)
+        levelname = recordcopy.levelname
+        process = recordcopy.process
+        created = recordcopy.created
+        filename = recordcopy.filename
+        module = recordcopy.module
+        lineno = recordcopy.lineno
+        separator = " " * (5 - len(recordcopy.levelname))
+        if self.use_colors:
+            levelname = self.color_level_name(levelname, recordcopy.levelno)
+            if "color_message" in recordcopy.__dict__:
+                recordcopy.msg = recordcopy.__dict__["color_message"]
+                recordcopy.__dict__["message"] = recordcopy.getMessage()
+        recordcopy.__dict__["levelprefix"] = levelname + separator
+        recordcopy.__dict__["process"] = click.style(str(process), fg="blue")
+        recordcopy.__dict__["asctime"] = click.style(datetime.fromtimestamp(created, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S.%fZ"), fg=(101, 111, 104))
+        recordcopy.__dict__["filename"] = click.style(f"{module}/{filename}:{lineno}:", fg=(101, 111, 104))
+        return super().formatMessage(recordcopy)
+
+
+class DefaultFormatter(ColourizedFormatter):
+    def should_use_colors(self) -> bool:
+        return sys.stderr.isatty()
+
+
+def create_logger(name) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)
+    formatter = DefaultFormatter(fmt="%(asctime)s %(levelprefix)s %(filename)s %(message)s", use_colors=True, datefmt="%Y-%m-%d %H:%M:%S")
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    return logger
+
+
+logger = create_logger("hypern")

hypern/middleware/__init__.py

@@ -0,0 +1,5 @@
+from .base import Middleware
+from .cors import CORSMiddleware
+from .limit import RateLimitMiddleware, StorageBackend, RedisBackend, InMemoryBackend
+
+__all__ = ["Middleware", "CORSMiddleware", "RateLimitMiddleware", "StorageBackend", "RedisBackend", "InMemoryBackend"]

hypern/middleware/base.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+from hypern.hypern import Response, Request
+
+
+# The `Middleware` class is an abstract base class with abstract methods `before_request` and
+# `after_request` for handling requests and responses in a web application.
+class Middleware(ABC):
+    def __init__(self) -> None:
+        super().__init__()
+        self.app = None
+
+    @abstractmethod
+    def before_request(self, request: Request):
+        pass
+
+    @abstractmethod
+    def after_request(self, response: Response):
+        pass

hypern/middleware/cors.py

@@ -0,0 +1,38 @@
+from typing import List
+from .base import Middleware
+
+
+class CORSMiddleware(Middleware):
+    """
+    The `CORSMiddleware` class is used to add CORS headers to the response based on specified origins,
+    methods, and headers.
+    """
+
+    def __init__(self, allow_origins: List[str] = None, allow_methods: List[str] = None, allow_headers: List[str] = None) -> None:
+        super().__init__()
+        self.allow_origins = allow_origins or []
+        self.allow_methods = allow_methods or []
+        self.allow_headers = allow_headers or []
+
+    def before_request(self, request):
+        return request
+
+    def after_request(self, response):
+        """
+        The `after_request` function adds Access-Control headers to the response based on specified origins,
+        methods, and headers.
+
+        :param response: The `after_request` method is used to add CORS (Cross-Origin Resource Sharing)
+        headers to the response object before sending it back to the client. The parameters used in this
+        method are:
+        :return: The `response` object is being returned from the `after_request` method.
+        """
+        for origin in self.allow_origins:
+            self.app.add_response_header("Access-Control-Allow-Origin", origin)
+            self.app.add_response_header(
+                "Access-Control-Allow-Methods",
+                ", ".join([method.upper() for method in self.allow_methods]),
+            )
+            self.app.add_response_header("Access-Control-Allow-Headers", ", ".join(self.allow_headers))
+            self.app.add_response_header("Access-Control-Allow-Credentials", "true")
+        return response

hypern/middleware/i18n.py

@@ -0,0 +1 @@
+# comming soon

hypern/middleware/limit.py

@@ -0,0 +1,176 @@
+import time
+from abc import ABC, abstractmethod
+from threading import Lock
+
+from hypern.hypern import Request, Response
+
+from .base import Middleware
+
+
+class StorageBackend(ABC):
+    @abstractmethod
+    def increment(self, key, amount=1, expire=None):
+        pass
+
+    @abstractmethod
+    def get(self, key):
+        pass
+
+
+class RedisBackend(StorageBackend):
+    def __init__(self, redis_client):
+        self.redis = redis_client
+
+    def increment(self, key, amount=1, expire=None):
+        """
+        The `increment` function increments a value in Redis by a specified amount and optionally sets an
+        expiration time for the key.
+
+        :param key: The `key` parameter in the `increment` method is used to specify the key in the Redis
+        database that you want to increment
+        :param amount: The `amount` parameter in the `increment` method specifies the value by which the
+        key's current value should be incremented. By default, it is set to 1, meaning that if no specific
+        amount is provided, the key's value will be incremented by 1, defaults to 1 (optional)
+        :param expire: The `expire` parameter in the `increment` method is used to specify the expiration
+        time for the key in Redis. If a value is provided for `expire`, the key will expire after the
+        specified number of seconds. If `expire` is not provided (i.e., it is `None`
+        :return: The `increment` method returns the result of incrementing the value of the key by the
+        specified amount. If an expiration time is provided, it also sets the expiration time for the key in
+        Redis. The method returns the updated value of the key after the increment operation.
+        """
+        with self.redis.pipeline() as pipe:
+            pipe.incr(key, amount)
+            if expire:
+                pipe.expire(key, int(expire))
+            return pipe.execute()[0]
+
+    def get(self, key):
+        return int(self.redis.get(key) or 0)
+
+
+class InMemoryBackend(StorageBackend):
+    def __init__(self):
+        self.storage = {}
+
+    def increment(self, key, amount=1, expire=None):
+        """
+        The `increment` function updates the value associated with a key in a storage dictionary by a
+        specified amount and optionally sets an expiration time.
+
+        :param key: The `key` parameter in the `increment` method is used to identify the value that needs
+        to be incremented in the storage. It serves as a unique identifier for the value being manipulated
+        :param amount: The `amount` parameter in the `increment` method specifies the value by which the
+        existing value associated with the given `key` should be incremented. By default, if no `amount` is
+        provided, it will increment the value by 1, defaults to 1 (optional)
+        :param expire: The `expire` parameter in the `increment` method is used to specify the expiration
+        time for the key-value pair being incremented. If a value is provided for the `expire` parameter, it
+        sets the expiration time for the key in the storage dictionary to the current time plus the
+        specified expiration duration
+        :return: The function `increment` returns the updated value of the key in the storage after
+        incrementing it by the specified amount.
+        """
+        if key not in self.storage:
+            self.storage[key] = {"value": 0, "expire": None}
+        self.storage[key]["value"] += amount
+        if expire:
+            self.storage[key]["expire"] = time.time() + expire
+        return self.storage[key]["value"]
+
+    def get(self, key):
+        """
+        This Python function retrieves the value associated with a given key from a storage dictionary,
+        checking for expiration before returning the value or 0 if the key is not found.
+
+        :param key: The `key` parameter is used to specify the key of the item you want to retrieve from the
+        storage. The function checks if the key exists in the storage dictionary and returns the
+        corresponding value if it does. If the key has an expiration time set and it has expired, the
+        function deletes the key
+        :return: The `get` method returns the value associated with the given key if the key is present in
+        the storage and has not expired. If the key is not found or has expired, it returns 0.
+        """
+        if key in self.storage:
+            if self.storage[key]["expire"] and time.time() > self.storage[key]["expire"]:
+                del self.storage[key]
+                return 0
+            return self.storage[key]["value"]
+        return 0
+
+
+class RateLimitMiddleware(Middleware):
+    """
+    The RateLimitMiddleware class implements rate limiting functionality to restrict the number of
+    Requests per minute for a given IP address.
+    """
+
+    def __init__(self, storage_backend, requests_per_minute=60, window_size=60):
+        super().__init__()
+        self.storage = storage_backend
+        self.requests_per_minute = requests_per_minute
+        self.window_size = window_size
+
+    def get_request_identifier(self, request: Request):
+        return request.ip_addr
+
+    def before_request(self, request: Request):
+        """
+        The `before_request` function checks the request rate limit and returns a 429 status code if the
+        limit is exceeded.
+
+        :param request: The `request` parameter in the `before_request` method is of type `Request`. It
+        is used to represent an incoming HTTP request that the server will process
+        :type request: Request
+        :return: The code snippet is a method called `before_request` that takes in a `Request` object
+        as a parameter.
+        """
+        identifier = self.get_request_identifier(request)
+        current_time = int(time.time())
+        window_key = f"{identifier}:{current_time // self.window_size}"
+
+        request_count = self.storage.increment(window_key, expire=self.window_size)
+
+        if request_count > self.requests_per_minute:
+            return Response(status_code=429, description=b"Too Many Requests", headers={"Retry-After": str(self.window_size)})
+
+        return request
+
+    def after_request(self, response):
+        return response
+
+
+class ConcurrentRequestMiddleware(Middleware):
+    # The `ConcurrentRequestMiddleware` class limits the number of concurrent requests and returns a 429
+    # status code with a Retry-After header if the limit is reached.
+    def __init__(self, max_concurrent_requests=100):
+        super().__init__()
+        self.max_concurrent_requests = max_concurrent_requests
+        self.current_requests = 0
+        self.lock = Lock()
+
+    def get_request_identifier(self, request):
+        return request.ip_addr
+
+    def before_request(self, request):
+        """
+        The `before_request` function limits the number of concurrent requests and returns a 429 status code
+        with a Retry-After header if the limit is reached.
+
+        :param request: The `before_request` method in the code snippet is a method that is called before
+        processing each incoming request. It checks if the number of current requests is within the allowed
+        limit (`max_concurrent_requests`). If the limit is exceeded, it returns a 429 status code with a
+        "Too Many Requests
+        :return: the `request` object after checking if the number of current requests is within the allowed
+        limit. If the limit is exceeded, it returns a 429 status code response with a "Too Many Requests"
+        description and a "Retry-After" header set to 5.
+        """
+
+        with self.lock:
+            if self.current_requests >= self.max_concurrent_requests:
+                return Response(status_code=429, description="Too Many Requests", headers={"Retry-After": "5"})
+            self.current_requests += 1
+
+        return request
+
+    def after_request(self, response):
+        with self.lock:
+            self.current_requests -= 1
+        return response

hypern/openapi/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+from .schemas import SchemaGenerator
+from .swagger import SwaggerUI
+
+__all__ = ["SchemaGenerator", "SwaggerUI"]

hypern/openapi/schemas.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+from hypern.hypern import BaseSchemaGenerator, Route as InternalRoute
+import typing
+import orjson
+
+
+class EndpointInfo(typing.NamedTuple):
+    path: str
+    http_method: str
+    func: typing.Callable[..., typing.Any]
+
+
+class SchemaGenerator(BaseSchemaGenerator):
+    def __init__(self, base_schema: dict[str, typing.Any]) -> None:
+        self.base_schema = base_schema
+
+    def get_endpoints(self, routes: list[InternalRoute]) -> list[EndpointInfo]:
+        """
+        Given the routes, yields the following information:
+
+        - path
+            eg: /users/
+        - http_method
+            one of 'get', 'post', 'put', 'patch', 'delete', 'options'
+        - func
+            method ready to extract the docstring
+        """
+        endpoints_info: list[EndpointInfo] = []
+
+        for route in routes:
+            method = route.method.lower()
+            endpoints_info.append(EndpointInfo(path=route.path, http_method=method, func=route.function.handler))
+        return endpoints_info
+
+    def get_schema(self, app) -> dict[str, typing.Any]:
+        schema = dict(self.base_schema)
+        schema.setdefault("paths", {})
+        endpoints_info = self.get_endpoints(app.router.routes)
+
+        for endpoint in endpoints_info:
+            parsed = self.parse_docstring(endpoint.func)
+
+            if not parsed:
+                continue
+
+            if endpoint.path not in schema["paths"]:
+                schema["paths"][endpoint.path] = {}
+
+            schema["paths"][endpoint.path][endpoint.http_method] = orjson.loads(parsed)
+
+        return schema

hypern/openapi/swagger.py

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