hypern 0.3.0__cp311-cp311-win_amd64.whl

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__}.")

hypern/datastructures.py

@@ -0,0 +1,40 @@
+from typing import Optional
+from enum import Enum
+from pydantic import BaseModel, AnyUrl, EmailStr
+
+
+class BaseModelWithConfig(BaseModel):
+    model_config = {"extra": "allow"}
+
+
+class Contact(BaseModelWithConfig):
+    name: Optional[str] = None
+    url: Optional[AnyUrl] = None
+    email: Optional[EmailStr] = None
+
+
+class License(BaseModelWithConfig):
+    name: str
+    identifier: Optional[str] = None
+    url: Optional[AnyUrl] = None
+
+
+class Info(BaseModelWithConfig):
+    title: str
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    contact: Optional[Contact] = None
+    license: Optional[License] = None
+    version: str
+
+
+class HTTPMethod(Enum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+    TRACE = "TRACE"
+    CONNECT = "CONNECT"

hypern/db/nosql/__init__.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+from typing import List, TypedDict
+
+from uuid import uuid4
+from mongoengine import connect
+
+
+class TypedDictModel(TypedDict):
+    host: str
+    alias: str
+
+
+class NoSqlConfig:
+    def __init__(self, dbs_config: List[TypedDictModel]):
+        self.dbs_config = dbs_config
+
+    def _connect_db(self, db_config: TypedDictModel):
+        _alias = db_config.get("alias", str(uuid4()))
+        connect(host=db_config["host"], alias=_alias)
+
+    def init_app(self, app):
+        self.app = app  # noqa
+        # connect
+        for db_config in self.dbs_config:
+            self._connect_db(db_config)

hypern/db/nosql/addons/__init__.py

@@ -0,0 +1,4 @@
+from .encrypted import EncryptedField
+from .password import PasswordField
+
+__all__ = ["EncryptedField", "PasswordField"]

hypern/db/nosql/addons/color.py

@@ -0,0 +1,16 @@
+from mongoengine import BaseField
+import re
+
+
+class ColorField(BaseField):
+    def validate(self, value):
+        color_regex = r"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
+        if not re.match(color_regex, value):
+            self.error("Invalid color format. Use hexadecimal color codes (e.g., #FF0000)")
+        return True
+
+    def to_mongo(self, value):
+        return value
+
+    def to_python(self, value):
+        return value

hypern/db/nosql/addons/daterange.py

@@ -0,0 +1,30 @@
+from mongoengine import BaseField
+from datetime import datetime
+
+
+class DateRangeField(BaseField):
+    def __init__(self, **kwargs):
+        super(DateRangeField, self).__init__(**kwargs)
+
+    def validate(self, value):
+        if not isinstance(value, dict) or "start" not in value or "end" not in value:
+            self.error('DateRangeField must be a dictionary with "start" and "end" keys')
+        # Use get to safely access keys
+        start = value.get("start")
+        end = value.get("end")
+        # Check if both "start" and "end" are present
+        if start is None or end is None:
+            self.error('DateRangeField must contain both "start" and "end" keys')
+
+        # Check if "start" and "end" are datetime objects
+        if not isinstance(value["start"], datetime) or not isinstance(value["end"], datetime):
+            self.error('DateRangeField "start" and "end" must be datetime objects')
+        if value["start"] > value["end"]:
+            self.error('DateRangeField "start" must be earlier than "end"')
+        return True
+
+    def to_mongo(self, value):
+        return value
+
+    def to_python(self, value):
+        return value

hypern/db/nosql/addons/encrypted.py

@@ -0,0 +1,53 @@
+import os
+from typing import Any, Optional
+from mongoengine.base import BaseField
+
+from cryptography.hazmat.primitives import padding
+
+from hypern.security import EDEngine, AESEngine
+
+
+class EncryptedField(BaseField):
+    """
+    A custom MongoEngine field that encrypts data using AES-256-CBC.
+
+    The field automatically handles encryption when saving to MongoDB and
+    decryption when retrieving data.
+
+    Attributes:
+        engine: Encryption engine to use. If not provided, will use AES-256-CBC
+    """
+
+    def __init__(self, engine: Optional[EDEngine] = None, **kwargs):
+        if not engine:
+            key = os.urandom(32)
+            iv = os.urandom(16)
+            padding_class = padding.PKCS7
+            self.engine = AESEngine(secret_key=key, iv=iv, padding_class=padding_class)
+        else:
+            self.engine = engine  # type: ignore
+        super(EncryptedField, self).__init__(**kwargs)
+
+    def to_mongo(self, value: Any) -> Optional[str]:
+        """Convert a Python object to a MongoDB-compatible format."""
+        if value is None:
+            return None
+        return self.engine.encrypt(value)
+
+    def to_python(self, value: Optional[str]) -> Optional[str]:
+        """Convert a MongoDB-compatible format to a Python object."""
+        if value is None:
+            return None
+        if isinstance(value, bytes):
+            return self.engine.decrypt(value)
+        return value
+
+    def prepare_query_value(self, op, value: Any) -> Optional[str]:
+        """Prepare a value used in a query."""
+        if value is None:
+            return None
+
+        if op in ("set", "upsert"):
+            return self.to_mongo(value)
+
+        return value

hypern/db/nosql/addons/password.py

@@ -0,0 +1,134 @@
+from mongoengine.base import BaseField
+import weakref
+from passlib.context import CryptContext
+import re
+from typing import Optional, Any
+
+
+class PasswordField(BaseField):
+    """
+    A custom password field using passlib for hashing and weakref for reference management.
+    Supports multiple hashing schemes and automatic upgrade of hash algorithms.
+    """
+
+    # Class-level password context - shared across all instances
+    pwd_context = CryptContext(
+        # List of hashing schemes in order of preference
+        schemes=["argon2", "pbkdf2_sha256", "bcrypt_sha256"],
+        # Mark argon2 as default
+        default="argon2",
+        # Argon2 parameters
+        argon2__rounds=4,
+        argon2__memory_cost=65536,
+        argon2__parallelism=2,
+        # PBKDF2 parameters
+        pbkdf2_sha256__rounds=29000,
+    )
+
+    def __init__(
+        self,
+        min_length: int = 8,
+        require_number: bool = False,
+        require_special: bool = False,
+        require_uppercase: bool = False,
+        require_lowercase: bool = False,
+        **kwargs,
+    ):
+        """
+        Initialize the password field with validation rules.
+
+        Args:
+            min_length: Minimum password length
+            require_number: Require at least one number
+            require_special: Require at least one special character
+            require_uppercase: Require at least one uppercase letter
+            require_lowercase: Require at least one lowercase letter
+        """
+        self.min_length = min_length
+        self.require_number = require_number
+        self.require_special = require_special
+        self.require_uppercase = require_uppercase
+        self.require_lowercase = require_lowercase
+
+        # Use weakref to store references to parent documents
+        self.instances = weakref.WeakKeyDictionary()
+
+        kwargs["required"] = True
+        super(PasswordField, self).__init__(**kwargs)
+
+    def validate_password(self, password: str) -> tuple[bool, str]:
+        """Validate password strength."""
+
+        if len(password) < self.min_length:
+            return False, f"Password must be at least {self.min_length} characters long"
+
+        if self.require_number and not re.search(r"\d", password):
+            return False, "Password must contain at least one number"
+
+        if self.require_special and not re.search(r"[!@#$%^&*(),.?\":{}|<>]", password):
+            return False, "Password must contain at least one special character"
+
+        if self.require_uppercase and not re.search(r"[A-Z]", password):
+            return False, "Password must contain at least one uppercase letter"
+
+        if self.require_lowercase and not re.search(r"[a-z]", password):
+            return False, "Password must contain at least one lowercase letter"
+
+        return True, ""
+
+    def hash_password(self, password: str) -> str:
+        """Hash password using the configured passlib context."""
+        return self.pwd_context.hash(password)
+
+    def verify_password(self, password: str, hash: str) -> tuple[bool, Optional[str]]:
+        """
+        Verify password and return tuple of (is_valid, new_hash).
+        new_hash is provided if the hash needs to be upgraded.
+        """
+        try:
+            is_valid = self.pwd_context.verify(password, hash)
+            # Check if the hash needs to be upgraded
+            if is_valid and self.pwd_context.needs_update(hash):
+                return True, self.hash_password(password)
+            return is_valid, None
+        except Exception:
+            return False, None
+
+    def __get__(self, instance, owner):
+        """Custom getter using weakref."""
+        if instance is None:
+            return self
+        return self.instances.get(instance)
+
+    def __set__(self, instance, value):
+        """Custom setter using weakref."""
+        if value and isinstance(value, str):
+            # Validate and hash new password
+            is_valid, error = self.validate_password(value)
+            if not is_valid:
+                raise ValueError(error)
+            hashed = self.hash_password(value)
+            self.instances[instance] = hashed
+            instance._data[self.name] = hashed
+        else:
+            # If it's already hashed or None
+            self.instances[instance] = value
+            instance._data[self.name] = value
+
+    def to_mongo(self, value: str) -> Optional[str]:
+        """Convert to MongoDB-compatible value."""
+        if value is None:
+            return None
+        return self.hash_password(value)
+
+    def to_python(self, value: str) -> str:
+        """Convert from MongoDB to Python."""
+        return value
+
+    def prepare_query_value(self, op, value: Any) -> Optional[str]:
+        """Prepare value for database operations."""
+        if value is None:
+            return None
+        if op == "exact":
+            return self.hash_password(value)
+        return value

hypern/db/nosql/addons/unicode.py

@@ -0,0 +1,10 @@
+from mongoengine import StringField
+
+
+class UnicodeField(StringField):
+    def validate(self, value):
+        try:
+            value.encode("utf-8")
+        except UnicodeEncodeError:
+            self.error("Value must be valid Unicode")
+        return True

hypern/db/sql/__init__.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+import asyncio
+import threading
+import traceback
+from contextlib import asynccontextmanager
+from contextvars import ContextVar, Token
+from datetime import datetime
+from typing import Dict, Optional, Union
+from uuid import uuid4
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_scoped_session
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.sql.expression import Delete, Insert, Update
+
+from hypern.hypern import Request, Response
+
+from .repository import Model, PostgresRepository
+
+
+class ContextStore:
+    def __init__(self, cleanup_interval: int = 300, max_age: int = 3600):
+        """
+        Initialize ContextStore with automatic session cleanup.
+
+        :param cleanup_interval: Interval between cleanup checks (in seconds)
+        :param max_age: Maximum age of a session before it's considered expired (in seconds)
+        """
+        self._session_times: Dict[str, datetime] = {}
+        self.session_var = ContextVar("session_id", default=None)
+
+        self._max_age = max_age
+        self._cleanup_interval = cleanup_interval
+        self._cleanup_thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+
+        # Start the cleanup thread
+        self._start_cleanup_thread()
+
+    def _start_cleanup_thread(self):
+        """Start a background thread for periodic session cleanup."""
+
+        def cleanup_worker():
+            while not self._stop_event.is_set():
+                self._perform_cleanup()
+                self._stop_event.wait(self._cleanup_interval)
+
+        self._cleanup_thread = threading.Thread(
+            target=cleanup_worker,
+            daemon=True,  # Allows the thread to be automatically terminated when the main program exits
+        )
+        self._cleanup_thread.start()
+
+    def _perform_cleanup(self):
+        """Perform cleanup of expired sessions."""
+        current_time = datetime.now()
+        expired_sessions = [
+            session_id for session_id, timestamp in list(self._session_times.items()) if (current_time - timestamp).total_seconds() > self._max_age
+        ]
+
+        for session_id in expired_sessions:
+            self.remove_session(session_id)
+
+    def remove_session(self, session_id: str):
+        """Remove a specific session."""
+        self._session_times.pop(session_id, None)
+
+    def set_context(self, session_id: str):
+        """
+        Context manager for setting and resetting session context.
+
+        :param session_id: Unique identifier for the session
+        :return: Context manager for session
+        """
+        self.session_var.set(session_id)
+        self._session_times[session_id] = datetime.now()
+
+    def get_context(self) -> str:
+        """
+        Get the current session context.
+
+        :return: Current session ID
+        :raises RuntimeError: If no session context is available
+        """
+        return self.session_var.get()
+
+    def reset_context(self):
+        """Reset the session context."""
+        token = self.get_context()
+        if token is not None:
+            self.session_var.reset(token)
+
+    def stop_cleanup(self):
+        """
+        Stop the cleanup thread.
+        Useful for graceful shutdown of the application.
+        """
+        self._stop_event.set()
+        if self._cleanup_thread:
+            self._cleanup_thread.join()
+
+    def __del__(self):
+        """
+        Ensure cleanup thread is stopped when the object is deleted.
+        """
+        self.stop_cleanup()
+
+
+class SqlConfig:
+    def __init__(self, default_engine: AsyncEngine | None = None, reader_engine: AsyncEngine | None = None, writer_engine: AsyncEngine | None = None):
+        """
+        Initialize the SQL configuration.
+        You can provide a default engine, a reader engine, and a writer engine.
+        If only one engine is provided (default_engine), it will be used for both reading and writing.
+        If both reader and writer engines are provided, they will be used for reading and writing respectively.
+        Note: The reader and writer engines must be different.
+        """
+
+        assert default_engine or reader_engine or writer_engine, "At least one engine must be provided."
+        assert not (reader_engine and writer_engine and id(reader_engine) == id(writer_engine)), "Reader and writer engines must be different."
+
+        engines = {
+            "writer": writer_engine or default_engine,
+            "reader": reader_engine or default_engine,
+        }
+        self.session_store = ContextStore()
+
+        class RoutingSession(Session):
+            def get_bind(this, mapper=None, clause=None, **kwargs):
+                if this._flushing or isinstance(clause, (Update, Delete, Insert)):
+                    return engines["writer"].sync_engine
+                return engines["reader"].sync_engine
+
+        async_session_factory = sessionmaker(
+            class_=AsyncSession,
+            sync_session_class=RoutingSession,
+            expire_on_commit=False,
+        )
+
+        session_scope: Union[AsyncSession, async_scoped_session] = async_scoped_session(
+            session_factory=async_session_factory,
+            scopefunc=asyncio.current_task,
+        )
+
+        @asynccontextmanager
+        async def get_session():
+            """
+            Get the database session.
+            This can be used for dependency injection.
+
+            :return: The database session.
+            """
+            try:
+                yield session_scope
+            except Exception:
+                traceback.print_exc()
+                await session_scope.rollback()
+            finally:
+                await session_scope.remove()
+                await session_scope.close()
+
+        self.get_session = get_session
+        self._context_token: Optional[Token] = None
+
+    def before_request(self, request: Request):
+        token = str(uuid4())
+        self.session_store.set_context(token)
+        return request
+
+    def after_request(self, response: Response):
+        self.session_store.reset_context()
+        return response
+
+    def init_app(self, app):
+        app.inject("get_session", self.get_session)
+        app.before_request()(self.before_request)
+        app.after_request()(self.after_request)
+
+
+__all__ = ["Model", "PostgresRepository", "SqlConfig"]

hypern/db/sql/addons/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+from .ts_vector import TSVector
+from .datetime import DatetimeType
+from .password import PasswordType
+from .encrypted import StringEncryptType, LargeBinaryEncryptType, AESEngine
+
+__all__ = [
+    "TSVector",
+    "DatetimeType",
+    "PasswordType",
+    "StringEncryptType",
+    "LargeBinaryEncryptType",
+    "AESEngine",
+]

hypern/db/sql/addons/color.py

@@ -0,0 +1,16 @@
+import re
+
+from sqlalchemy.types import String, TypeDecorator
+
+
+class ColorField(TypeDecorator):
+    impl = String
+
+    def process_bind_param(self, value, dialect):
+        color_regex = r"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
+        if not re.match(color_regex, value):
+            raise ValueError("Invalid color format. Use hexadecimal color codes (e.g., #FF0000)")
+        return value
+
+    def process_result_value(self, value, dialect):
+        return value