toms-fast 0.2.1__py3-none-any.whl

tomskit/server/server.py

@@ -0,0 +1,276 @@
+
+import os
+import warnings
+from contextvars import ContextVar
+from typing import Any, Optional
+
+from fastapi import FastAPI
+from starlette.types import ASGIApp
+
+from tomskit.server.config import Config
+
+
+class CurrentApp:
+    __app_ctx: ContextVar[Optional["FastApp"]] = ContextVar('tomskit.current_app.context', default=None)
+
+    def set_app(self, app_instance: "FastApp"):
+        self.__app_ctx.set(app_instance)
+
+    def _get_app(self) -> "FastApp":
+        """Get the current application instance, raising error if not set."""
+        if (app := self.__app_ctx.get()) is None:
+            raise RuntimeError("No application instance is currently set")
+        return app
+
+    @property
+    def app(self) -> "FastApp":
+        """Get the current application instance."""
+        return self._get_app()
+
+    def __call__(self) -> "FastApp":
+        """Get the current application instance when called."""
+        return self._get_app()
+
+    @property
+    def config(self):
+        """Get the configuration from the current application instance."""
+        return self._get_app().config
+
+    @property
+    def root_path(self):
+        """Get the root path from the current application instance."""
+        return self._get_app().root_path
+
+    def reset_app(self):
+        """Reset the current application instance."""
+        self.__app_ctx.set(None)
+        # Also reset FastApp singleton instance for testing
+        FastApp.reset_instance()
+
+current_app = CurrentApp()
+
+class FastApp(FastAPI):
+    """
+    A custom FastAPI instance that disables default documentation paths.
+
+    This class creates a custom FastAPI instance that disables the default
+    documentation paths (/docs, /redoc, /openapi) to enhance security and
+    reduce unnecessary exposure in production environments.
+
+    This class also adds configuration support and can initialize the
+    current_app context variable for global access to the application instance.
+    """
+
+    _instance: Optional["FastApp"] = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._is_initialized = False
+        return cls._instance
+    
+    @classmethod
+    def reset_instance(cls):
+        """Reset the singleton instance. Useful for testing."""
+        cls._instance = None
+    
+    def __init__(self, *args, **kwargs):
+        if not self._is_initialized:
+            # Only disable docs if not explicitly provided by user
+            if 'docs_url' not in kwargs:
+                kwargs['docs_url'] = None
+            if 'redoc_url' not in kwargs:
+                kwargs['redoc_url'] = None
+            if 'openapi_url' not in kwargs:
+                kwargs['openapi_url'] = None
+            super().__init__(*args, **kwargs)
+            self.config = Config()
+            current_app.set_app(self)
+            self._is_initialized = True
+        else:
+            # Even if already initialized, ensure current_app is set
+            # This handles cases where reset_app() was called but instance still exists
+            current_app.set_app(self)
+
+    def mount(self, path: str, app: ASGIApp, name: Optional[str] = None):
+        """Mount an ASGI application at the specified path."""
+        if hasattr(app, "config"):
+            app.config = self.config
+        super().mount(path, app, name)
+        
+    def set_environ(self):
+        """Set environment variables from configuration."""
+        for key, value in self.config.items():
+            if isinstance(value, str):
+                os.environ[key] = value
+            elif isinstance(value, (int, float, bool)):
+                os.environ[key] = str(value)
+            elif value is None:
+                os.environ[key] = ""
+    
+    def set_app_root_path(self, app_file: str):
+        """Set the application root path based on the app file location."""
+        self.app_root_path = os.path.dirname(os.path.abspath(app_file))
+
+    def add_exception_handler(self, exc_class_or_status_code, handler):
+        """Add an exception handler to the application."""
+        super().add_exception_handler(exc_class_or_status_code, handler)
+
+class FastModule(FastAPI):
+    """
+    FastAPI sub-application module class.
+
+    Used to create independent sub-application modules, where each module
+    can have its own routes, middleware, and configuration. Supports
+    automatic Resource registration to simplify module management.
+    """
+
+    def __init__(self, name: str, *args, **kwargs):
+        """
+        Initialize FastModule.
+
+        Args:
+            name: Module name used to identify the module. Must match the
+                module name in @register_resource(module=...).
+            *args, **kwargs: Additional arguments passed to FastAPI.
+        """
+        # Only disable docs if not explicitly provided by user
+        if 'docs_url' not in kwargs:
+            kwargs['docs_url'] = None
+        if 'redoc_url' not in kwargs:
+            kwargs['redoc_url'] = None
+        if 'openapi_url' not in kwargs:
+            kwargs['openapi_url'] = None
+        
+        super().__init__(*args, **kwargs)
+
+        self.module_name = name
+        self._router: Optional[Any] = None  # Store the unique ResourceRouter instance
+
+        # Get configuration from current_app
+        try:
+            self.config = current_app.config
+        except RuntimeError:
+            raise RuntimeError(
+                "FastApp instance must be created and set as current_app before creating FastModule"
+            )
+    
+    def create_router(self, prefix: str = "", **kwargs):
+        """
+        Create a ResourceRouter and associate it with this module.
+
+        A FastModule can only have one ResourceRouter. If a router has
+        already been created, calling this method again will raise a ValueError.
+
+        Args:
+            prefix: Route prefix.
+            **kwargs: Additional arguments passed to ResourceRouter.
+
+        Returns:
+            ResourceRouter: The created ResourceRouter instance.
+
+        Example:
+            router = module.create_router(prefix="/api/v1")
+        """
+        from tomskit.server.resource import ResourceRouter
+        
+        if self._router is not None:
+            raise ValueError(
+                f"FastModule '{self.module_name}' already has a router. "
+                "A FastModule can only have one ResourceRouter. "
+                "If you need multiple routers, create multiple FastModule instances."
+            )
+        
+        router = ResourceRouter(app=self, prefix=prefix, **kwargs)
+        self._router = router
+        return router
+    
+    def auto_register_resources(self):
+        """
+        Automatically register all Resources marked for this module.
+
+        This method searches ResourceRegistry for all Resources marked with
+        the current module name and automatically registers them to this
+        module's ResourceRouter.
+
+        If the router does not exist, it will be automatically created
+        (using default prefix="").
+
+        Example:
+            module = FastModule(name="files")
+            module.auto_register_resources()  # Auto-register all Resources marked for "files" module
+
+            # Or create router first, then auto-register
+            module = FastModule(name="files")
+            router = module.create_router(prefix="/api/v1")
+            module.auto_register_resources()  # Register to the created router
+        """
+        from tomskit.server.resource import ResourceRegistry
+
+        # Get or create router
+        if self._router is None:
+            self._router = self.create_router()
+
+        # Get all Resources for this module from registry
+        resources = ResourceRegistry.get_module_resources(self.module_name)
+
+        if not resources:
+            # If no Resources are registered, issue a warning but don't error (allows manual registration)
+            warnings.warn(
+                f"Module '{self.module_name}' has no Resources registered via @register_resource. "
+                f"Ensure Resource classes use @register_resource(module='{self.module_name}', ...) decorator.",
+                UserWarning,
+            )
+            return
+
+        # Register all Resources
+        for resource_info in resources:
+            self._router.add_resource(
+                resource_cls=resource_info.resource_cls,
+                path=resource_info.path,
+                tags=resource_info.tags if resource_info.tags else None,
+            )
+
+        # Include router after all resources are registered
+        # This ensures router has routes before being included
+        self.include_router(self._router)
+    
+    def setup_cors(
+        self,
+        allow_origins: Optional[list[str]] = None,
+        allow_credentials: bool = True,
+        allow_methods: Optional[list[str]] = None,
+        allow_headers: Optional[list[str]] = None,
+        expose_headers: Optional[list[str]] = None,
+    ):
+        """
+        Configure CORS middleware.
+
+        Args:
+            allow_origins: List of allowed origins for cross-origin requests.
+            allow_credentials: Whether to allow credentials in cross-origin requests.
+            allow_methods: List of allowed HTTP methods.
+            allow_headers: List of allowed request headers.
+            expose_headers: List of response headers exposed to clients.
+
+        Example:
+            module.setup_cors(
+                allow_origins=["http://localhost:3000"],
+                allow_credentials=True,
+                allow_methods=["GET", "POST", "PUT", "DELETE"],
+            )
+        """
+        from fastapi.middleware.cors import CORSMiddleware
+        
+        self.add_middleware(
+            CORSMiddleware,
+            allow_origins=allow_origins or [],
+            allow_credentials=allow_credentials,
+            allow_methods=allow_methods or ["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH"],
+            allow_headers=allow_headers or ["Content-Type", "Authorization"],
+            expose_headers=expose_headers or [],
+        )
+        
+    def add_exception_handler(self, exc_class_or_status_code, handler):
+        """Add an exception handler to the module."""
+        super().add_exception_handler(exc_class_or_status_code, handler)

tomskit/server/type.py

@@ -0,0 +1,263 @@
+import uuid
+from typing import Any, Dict, Type
+from pydantic_core import core_schema
+from datetime import datetime
+
+def IntRange(minimum: int, maximum: int) -> Type[int]:
+    """
+    Factory for a constrained int subtype: value must be in [minimum, maximum].
+
+    Usage:
+        class User(BaseModel):
+            age: IntRange(18, 35)
+    """
+    if minimum > maximum:
+        raise ValueError(f"IntRange: minimum ({minimum}) cannot exceed maximum ({maximum})")
+
+    class IntRangeType(int):
+        @classmethod
+        def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+            # Use the built-in int_schema with ge/le
+            return core_schema.int_schema(strict=True, ge=minimum, le=maximum)
+
+        @classmethod
+        def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+            schema.update(
+                type="integer",
+                minimum=minimum,
+                maximum=maximum,
+                description=f"Integer in range [{minimum}, {maximum}]"
+            )
+
+    IntRangeType.__name__ = f"IntRange_{minimum}_{maximum}"
+    return IntRangeType
+
+class Boolean:
+    """
+    Type that parses "true"/"false"/"1"/"0" into bool.
+    """
+
+    @staticmethod
+    def _parse_bool(v: Any) -> bool:
+        if isinstance(v, bool):
+            return v
+        if v is None or (isinstance(v, str) and not v):
+            raise ValueError("Boolean type must be non-null")
+        s = str(v).lower()
+        if s in ("true", "1"):
+            return True
+        if s in ("false", "0"):
+            return False
+        raise ValueError(f"Invalid literal for Boolean(): {v!r}")
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+        return core_schema.union_schema([
+            core_schema.bool_schema(strict=True),
+            core_schema.chain_schema([
+                core_schema.str_schema(strict=False, coerce_numbers_to_str=True),
+                core_schema.no_info_plain_validator_function(cls._parse_bool),
+            ]),
+        ], mode='smart')
+
+    @classmethod
+    def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+        schema.update(
+            type="boolean",
+            description="Accepts true/false/1/0 (case-insensitive)"
+        )
+
+
+class PhoneNumber(str):
+    """
+    Phone number type for Chinese mobile numbers (11 digits, starts with 1[3-9]).
+    """
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+        return core_schema.str_schema(
+            strict=True,
+            pattern=r"^1[3-9]\d{9}$",
+            regex_engine="python-re"
+        )
+
+    @classmethod
+    def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+        schema.update(
+            type="string",
+            pattern=r"^1[3-9]\d{9}$",
+            description="Chinese mobile phone number"
+        )
+
+class EmailStr(str):
+    """
+    Email address type.
+    """
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+        return core_schema.str_schema(
+            strict=True,
+            pattern=r"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$",
+            regex_engine="python-re"
+        )
+
+    @classmethod
+    def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+        schema.update(
+            type="string",
+            format="email",
+            description="Email address"
+        )
+
+def StrLen(max_length: int, min_length: int = 0) -> Type[str]:
+    """
+    Factory for a constrained string subtype: string length must be in [min_length, max_length].
+
+    Usage:
+        class User(BaseModel):
+            username: StrLen(3, 20)  # between 3-20 characters
+            name: StrLen(1, 50)      # between 1-50 characters
+    """
+    if min_length < 0:
+        raise ValueError(f"StrLen: min_length ({min_length}) cannot be negative")
+    if min_length > max_length:
+        raise ValueError(f"StrLen: min_length ({min_length}) cannot exceed max_length ({max_length})")
+    
+    min_length = max_length if min_length == 0 else min_length
+
+    class StrLenType(str):
+        @classmethod
+        def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+            return core_schema.str_schema(
+                strict=True,
+                min_length=min_length,
+                max_length=max_length
+            )
+
+        @classmethod
+        def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+            schema.update(
+                type="string",
+                minLength=min_length,
+                maxLength=max_length,
+                description=f"String with length between {min_length} and {max_length} characters"
+            )
+
+    StrLenType.__name__ = f"StrLen_{min_length}_{max_length}"
+    return StrLenType
+
+def DatetimeString(format: str, argument: str = "datetime") -> Type[str]:
+    """
+    Factory for datetime string type with custom format validation.
+    
+    Usage:
+        class Event(BaseModel):
+            created_at: DatetimeString("%Y-%m-%d %H:%M:%S")
+            date_only: DatetimeString("%Y-%m-%d", "date")
+    """
+    
+    class DatetimeStrType(str):
+        @classmethod
+        def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+            def validate_datetime(value: str) -> str:
+                try:
+                    datetime.strptime(value, format)
+                    return value
+                except ValueError:
+                    raise ValueError(f"Invalid {argument}: '{value}', expected format: {format}")
+            
+            return core_schema.chain_schema([
+                core_schema.str_schema(),
+                core_schema.no_info_plain_validator_function(validate_datetime)
+            ])
+        
+        @classmethod
+        def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+            # 根据格式判断是日期还是日期时间
+            is_datetime = any(x in format for x in ["%H", "%M", "%S"])
+            
+            schema.update(
+                type="string",
+                format="date-time" if is_datetime else "date",
+                description=f"{argument.title()} string in format: {format}",
+                example=datetime.now().strftime(format)
+            )
+    
+    DatetimeStrType.__name__ = f"DatetimeString_{argument}"
+    return DatetimeStrType
+
+
+class UUIDType(str):
+    """
+    UUID 类型验证器
+    用于验证字符串是否为有效的 UUID 格式
+    """
+    
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source, handler) -> core_schema.CoreSchema:
+        def validate_uuid(value: Any) -> str:
+            """验证 UUID 格式"""
+            if value == "":
+                return value
+                
+            try:
+                # 验证是否为有效的 UUID
+                uuid_obj = uuid.UUID(str(value))
+                # 返回标准化的 UUID 字符串
+                return str(uuid_obj)
+            except (ValueError, TypeError):
+                raise ValueError(f"{value} is not a valid UUID")
+        
+        return core_schema.no_info_plain_validator_function(
+            validate_uuid
+        )
+    
+    @classmethod
+    def __modify_json_schema__(cls, schema: Dict[str, Any]) -> None:
+        schema.update(
+            type="string",
+            format="uuid",
+            pattern="^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+            description="A valid UUID string"
+        )
+    
+    @classmethod
+    def is_valid_uuid(cls, value: str) -> bool:
+        """
+        检查字符串是否为有效的 UUID
+        
+        Args:
+            value: 待验证的字符串
+            
+        Returns:
+            bool: 如果是有效的 UUID 返回 True，否则返回 False
+        """
+        if not value or value == "":
+            return False
+            
+        try:
+            uuid.UUID(value)
+            return True
+        except (ValueError, TypeError):
+            return False
+        
+# 预定义的常用日期时间格式
+class CommonDateFormats:
+    """常用的日期时间格式"""
+    ISO_DATE = "%Y-%m-%d"                    # 2023-12-25
+    ISO_DATETIME = "%Y-%m-%d %H:%M:%S"       # 2023-12-25 14:30:00
+    ISO_DATETIME_MS = "%Y-%m-%d %H:%M:%S.%f" # 2023-12-25 14:30:00.123456
+    US_DATE = "%m/%d/%Y"                     # 12/25/2023
+    EU_DATE = "%d/%m/%Y"                     # 25/12/2023
+    TIME_24H = "%H:%M:%S"                    # 14:30:00
+    TIME_12H = "%I:%M:%S %p"                 # 02:30:00 PM
+
+
+# 便捷的预定义类型
+ISODate = DatetimeString(CommonDateFormats.ISO_DATE, "date")
+ISODateTime = DatetimeString(CommonDateFormats.ISO_DATETIME, "datetime")
+USDate = DatetimeString(CommonDateFormats.US_DATE, "date")
+EUDate = DatetimeString(CommonDateFormats.EU_DATE, "date")
+Time24H = DatetimeString(CommonDateFormats.TIME_24H, "time")
+Time12H = DatetimeString(CommonDateFormats.TIME_12H, "time")
+
+