tiferet-fast 0.1.0__py3-none-any.whl

tiferet_fast/__init__.py

@@ -0,0 +1,15 @@
+"""Tiferet Fast - A FastAPI Framework"""
+
+# *** exports
+
+# ** app
+# Export the main application context and related modules.
+# Use a try-except block to avoid import errors on build systems.
+try:
+    from .contexts import FastApiContext
+except:
+    pass
+
+# *** version
+
+__version__ = "0.1.0"

tiferet_fast/contexts/__init__.py

@@ -0,0 +1,7 @@
+"""Fast API Context Exports."""
+
+# *** exports
+
+# ** app
+from .request import FastRequestContext
+from .fast import FastApiContext

tiferet_fast/contexts/fast.py

@@ -0,0 +1,207 @@
+"""Fast API Context for Tiferet framework."""
+
+# *** imports
+
+# ** core
+from typing import Any, Callable
+from functools import partial
+
+# ** infra
+from tiferet import TiferetError
+from tiferet.contexts import (
+    AppInterfaceContext,
+    FeatureContext,
+    ErrorContext,
+    LoggingContext
+)
+from fastapi import FastAPI
+from fastapi.routing import APIRouter
+from starlette.middleware import Middleware
+from starlette_context import context, plugins
+from starlette_context.middleware import RawContextMiddleware
+
+# ** app
+from .request import FastRequestContext
+from ..handlers import FastApiHandler
+from ..models import FastRouter
+
+# *** contexts
+
+# ** context: fast_api_context
+class FastApiContext(AppInterfaceContext):
+    '''
+    A context for managing Fast API interactions within the Tiferet framework.
+    '''
+
+    # * attribute: fast_app
+    fast_app: FastAPI
+
+    # * attribute: fast_api_handler
+    fast_api_handler: FastApiHandler
+
+    # * init
+    def __init__(self,
+            interface_id: str,
+            features: FeatureContext,
+            errors: ErrorContext,
+            logging: LoggingContext,
+            fast_api_handler: FastApiHandler
+        ):
+        '''
+        Initialize the Fast API context.
+
+        :param interface_id: The interface ID.
+        :type interface_id: str
+        :param features: The feature context.
+        :type features: FeatureContext
+        :param errors: The error context.
+        :type errors: ErrorContext
+        :param logging: The logging context.
+        :type logging: LoggingContext
+        :param fast_api_handler: The Fast API handler.
+        :type fast_api_handler: FastApiHandler
+        '''
+
+        # Call the parent constructor.
+        super().__init__(interface_id, features, errors, logging)
+
+        # Set the attributes.
+        self.fast_api_handler = fast_api_handler
+
+    # * method: parse_request
+    def parse_request(self, headers: dict = {}, data: dict = {}, feature_id: str = None, **kwargs) -> FastRequestContext:
+        '''
+        Parse the incoming request and return a FastRequestContext instance.
+
+        :param headers: The request headers.
+        :type headers: dict
+        :param data: The request data.
+        :type data: dict
+        :param feature_id: The feature ID.
+        :type feature_id: str
+        :param kwargs: Additional keyword arguments.
+        :type kwargs: dict
+        :return: A FastRequestContext instance.
+        :rtype: FastRequestContext
+        '''
+
+        # Return a FastRequestContext instance.
+        return FastRequestContext(
+            headers=headers,
+            data=data,
+            feature_id=feature_id
+        )
+
+    # * method: handle_error
+    def handle_error(self, error: Exception) -> Any:
+        '''
+        Handle the error and return the response.
+
+        :param error: The error to handle.
+        :type error: Exception
+        :return: The error response.
+        :rtype: Any
+        '''
+
+        # Handle the error and get the response from the parent context.
+        if not isinstance(error, TiferetError):
+            return super().handle_error(error), 500
+
+        # Get the status code by the error code on the exception.
+        status_code = self.fast_api_handler.get_status_code(error.error_code)
+        return super().handle_error(error), status_code
+
+    # * method: handle_response
+    def handle_response(self, request: FastRequestContext) -> Any:
+        '''
+        Handle the response from the request context.
+
+        :param request: The request context.
+        :type request: RequestContext
+        :return: The response.
+        :rtype: Any
+        '''
+
+        # Handle the response from the request context.
+        response = super().handle_response(request)
+
+        # Retrieve the route by the request feature id.
+        route = self.fast_api_handler.get_route(request.feature_id)
+
+        # Return the result with the specified status code.
+        return response, route.status_code if route else 200
+
+    # * method: build_router
+    def build_router(self, fast_router: FastRouter, view_func: Callable, **kwargs) -> FastAPI:
+        '''
+        Assembles a FastAPI router from the given FastRouter model.
+
+        :param fast_router: The FastRouter model.
+        :type fast_router: FastRouter
+        :param view_func: The view function to handle requests.
+        :type view_func: Callable
+        :param kwargs: Additional keyword arguments.
+        :type kwargs: dict
+        :return: The created FastAPI router.
+        :rtype: FastAPI
+        '''
+
+        # Create a FastAPI router instance.
+        router = APIRouter(
+            prefix=fast_router.prefix,
+            tags=[fast_router.name]
+        )
+
+        # Add the routes to the router.
+        for route in fast_router.routes:
+            router.add_api_route(
+                name=route.endpoint,
+                path=route.path,
+                endpoint=partial(view_func),
+                methods=route.methods,
+                status_code=route.status_code
+            )
+
+        # Return the created router.
+        return router
+
+    # * method: build_fast_app
+    def build_fast_app(self, view_func: Callable, **kwargs) -> FastAPI:
+        '''
+        Build and return a FastAPI application instance.
+
+        :param view_func: The view function to handle requests.
+        :type view_func: Callable
+        :param kwargs: Additional keyword arguments.
+        :type kwargs: dict
+        :return: A FastAPI application instance.
+        :rtype: FastAPI
+        '''
+
+        # Create middleware for context management.
+        middleware = [
+            Middleware(
+                RawContextMiddleware, 
+                plugins=(
+                    plugins.RequestIdPlugin(), 
+                    plugins.CorrelationIdPlugin(),
+                )
+            )
+        ]
+
+        # Create the FastAPI application.
+        fast_app = FastAPI(title=f"{self.interface_id} API", middleware=middleware)
+
+        # Load the FastAPI routers.
+        routers = self.fast_api_handler.get_routers()
+
+        # Create and include the routers.
+        for router in routers:
+            fast_router = self.build_router(router, view_func=view_func, **kwargs)
+            fast_app.include_router(fast_router)
+
+        # Set the fast_app attribute.
+        self.fast_app = fast_app
+
+        # Return the FastAPI application.
+        return fast_app

tiferet_fast/contexts/request.py

@@ -0,0 +1,62 @@
+"""Fast API Request Context"""
+
+# *** imports
+
+# ** core
+from typing import Any
+
+# ** infra
+from tiferet.contexts.request import RequestContext
+from tiferet.models import ModelObject
+
+# *** contexts
+
+# ** context: fast_request_context
+class FastRequestContext(RequestContext):
+    '''
+    A context for handling Fast API request data and responses.
+    '''
+
+    # * method: handle_response
+    def handle_response(self) -> Any:
+        '''
+        Handle the response for the Fast API request context.
+
+        :return: The response.
+        :rtype: Any
+        '''
+
+        # Set the result using the set_result method to ensure proper formatting.
+        self.set_result(self.result)
+
+        # Handle the response using the parent method.
+        return super().handle_response()
+
+    # * method: set_result
+    def set_result(self, result: Any):
+        '''
+        Set the result of the request context.
+
+        :param result: The result to set.
+        :type result: Any
+        '''
+
+        # If the response is None, return an empty response.
+        if result is None:
+            self.result = ''
+
+        # Convert the response to a dictionary if it's a ModelObject.
+        elif isinstance(result, ModelObject):
+            self.result = result.to_primitive()
+
+        # If the response is a list containing model objects, convert each to a dictionary.
+        elif isinstance(result, list) and all(isinstance(item, ModelObject) for item in result):
+            self.result = [item.to_primitive() for item in result]
+
+        # If the response is a dict containing model objects, convert each to a dictionary.
+        elif isinstance(result, dict) and all(isinstance(value, ModelObject) for value in result.values()):
+            self.result = {key: value.to_primitive() for key, value in result.items()}
+
+        # Otherwise, set the result directly.
+        else:
+            self.result = result

tiferet_fast/contracts/__init__.py

@@ -0,0 +1,10 @@
+"""Tiferet Fast Contract Exports."""
+
+# *** exports
+
+# ** app
+from .fast import (
+    FastRouteContract,
+    FastRouterContract,
+    FastApiRepository
+)

tiferet_fast/contracts/fast.py

@@ -0,0 +1,84 @@
+"""Fast API Contracts."""
+
+# *** imports
+
+# ** core
+from typing import List
+
+# ** infra
+from tiferet import (
+    ModelContract,
+    Repository,
+    abstractmethod
+)
+
+# *** contracts
+
+# ** contract: fast_route_contract
+class FastRouteContract(ModelContract):
+    '''
+    A contract for Fast route models.
+    '''
+
+    # * attribute: endpoint
+    endpoint: str
+
+    # * attribute: status_code
+    status_code: int
+
+# ** contract: fast_blueprint_contract
+class FastRouterContract(ModelContract):
+    '''
+    A contract for Fast blueprint models.
+    '''
+
+    # * attribute: name
+    name: str
+
+    # * attribute: routes
+    routes: List[FastRouteContract]
+
+# ** contract: fast_api_repository
+class FastApiRepository(Repository):
+    '''
+    A repository contract for managing Fast API entities.
+    '''
+
+    # * method: get_routers
+    @abstractmethod
+    def get_routers(self) -> List[FastRouterContract]:
+        '''
+        Retrieve all Fast routers.
+
+        :return: A list of FastRouterContract instances.
+        :rtype: List[FastRouterContract]
+        '''
+        raise NotImplementedError('get_routers method not implemented.')
+
+    # * method: get_route
+    @abstractmethod
+    def get_route(self, route_id: str, router_name: str = None) -> FastRouteContract:
+        '''
+        Retrieve a specific Fast route by its router and route IDs.
+
+        :param route_id: The ID of the route within the router.
+        :type route_id: str
+        :param router_name: The name of the router (optional).
+        :type router_name: str
+        :return: The corresponding FastRouteContract instance.
+        :rtype: FastRouteContract
+        '''
+        raise NotImplementedError('get_route method not implemented.')
+
+    # * method: get_status_code
+    @abstractmethod
+    def get_status_code(self, error_code: str) -> int:
+        '''
+        Retrieve the HTTP status code for a given error code.
+
+        :param error_code: The error code.
+        :type error_code: str
+        :return: The corresponding HTTP status code.
+        :rtype: int
+        '''
+        raise NotImplementedError('get_status_code method not implemented.')

tiferet_fast/data/__init__.py

@@ -0,0 +1,10 @@
+"""Fast API Data Transfer Object Exports"""
+
+# *** exports
+
+# ** app
+from .fast import (
+    DataObject,
+    FastRouteYamlData,
+    FastRouterYamlData
+)

tiferet_fast/data/fast.py

@@ -0,0 +1,146 @@
+"""Fast API Data Transfer Objects (DTOs)."""
+
+# *** imports
+
+# ** core
+from typing import Dict, Any
+
+# ** infra
+from tiferet.data import (
+    DataObject,
+    StringType,
+    DictType,
+    ModelType
+)
+
+# ** app
+from ..models import (
+    FastRoute,
+    FastRouter
+)
+from ..contracts import (
+    FastRouteContract,
+    FastRouterContract
+)
+
+# *** data
+
+# ** data: fast_route_yaml_data
+class FastRouteYamlData(DataObject, FastRoute):
+    '''
+    A data object for Fast API route model from YAML.
+    '''
+
+    class Options:
+        '''
+        Options for the data object.
+        '''
+        serialize_when_none = False
+        roles = {
+            'to_model': DataObject.allow(),
+            'to_data': DataObject.deny('endpoint')
+        }
+
+    # * attribute: endpoint
+    endpoint = StringType(
+        metadata=dict(
+            description='The unique identifier of the route endpoint.'
+        )
+    )
+
+    # * method: map
+    def map(self, id: str, endpoint: str) -> FastRouteContract:
+        '''
+        Map the data object to a FastRouteContract instance.
+
+        :param id: The unique identifier of the route.
+        :type id: str
+        :param endpoint: The name of the route endpoint.
+        :type endpoint: str
+        :return: A FastRouteContract instance.
+        :rtype: FastRouteContract
+        '''
+
+        # Map the data object to a model instance.
+        return super().map(
+            FastRoute,
+            id=id,
+            endpoint=endpoint
+        )
+
+# ** data: fast_router_yaml_data
+class FastRouterYamlData(DataObject, FastRouter):
+    '''
+    A data object for Fast API router model from YAML.
+    '''
+
+    class Options:
+        '''
+        Options for the data object.
+        '''
+        serialize_when_none = False
+        roles = {
+            'to_model': DataObject.deny('routes'),
+            'to_data': DataObject.deny('name')
+        }
+
+    # * attribute: name
+    name = StringType(
+        metadata=dict(
+            description='The name of the router.'
+        )
+    )
+
+    # * attribute: routes
+    routes = DictType(
+        ModelType(FastRouteYamlData),
+        default={},
+        metadata=dict(
+            description='A dictionary of route endpoint to FastRouteYamlData instances.'
+        )
+    )
+
+    # * method: from_data
+    @staticmethod
+    def from_data(routes: Dict[str, Any] = {}, **kwargs) -> 'FastRouterYamlData':
+        '''
+        Create a FastRouterYamlData instance from raw data.
+
+        :param routes: A dictionary of route endpoint to route data.
+        :type routes: Dict[str, Any]
+        :return: A FastRouterYamlData instance.
+        :rtype: FastRouterYamlData
+        '''
+
+        # Convert each route in the routes dictionary to a FastRouteYamlData instance.
+        route_objs = {endpoint: DataObject.from_data(
+            FastRouteYamlData,
+            endpoint=endpoint,
+            **data
+        ) for endpoint, data in routes.items()}
+
+        # Create and return a FastRouterYamlData instance.
+        return DataObject.from_data(
+            FastRouterYamlData,
+            routes=route_objs,
+            **kwargs
+        )
+
+    # * method: map
+    def map(self) -> FastRouterContract:
+        '''
+        Map the data object to a FastRouterContract instance.
+
+        :return: A FastRouterContract instance.
+        :rtype: FastRouterContract
+        '''
+
+        # Map each route in the routes dictionary.
+        return super().map(
+            FastRouter,
+            routes=[
+                route.map(id=id, endpoint=f'{self.name}.{id}') 
+                for id, route 
+                in self.routes.items()
+            ]
+        )

tiferet_fast/handlers/__init__.py

@@ -0,0 +1,8 @@
+"""Fast API Handler Exports"""
+
+# *** exports
+
+# ** app
+from .fast import (
+    FastApiHandler,
+)

tiferet_fast/handlers/fast.py

@@ -0,0 +1,99 @@
+"""Fast API Handlers."""
+
+# *** imports
+
+# ** core
+from typing import List
+
+# ** infra
+from tiferet.commands import raise_error
+
+# ** app
+from ..contracts import (
+    FastRouterContract,
+    FastRouteContract,
+    FastApiRepository
+)
+
+# *** handlers
+
+# ** handler: fast_api_handler
+class FastApiHandler(object):
+    '''
+    A handler for managing Fast API entities.
+    '''
+
+    # * init
+    def __init__(self, fast_repo: FastApiRepository):
+        '''
+        Initialize the FastApiHandler with the given repository.
+
+        :param fast_repo: An instance of FastApiRepository.
+        :type fast_repo: FastApiRepository
+        '''
+
+        # Store the repository instance.
+        self.fast_repo = fast_repo
+
+    # * method: get_routers
+    def get_routers(self) -> List[FastRouterContract]:
+        '''
+        Retrieve all Fast API routers using the repository.
+
+        :return: A list of FastRouterContract instances.
+        :rtype: List[FastRouterContract]
+        '''
+
+        # Delegate the call to the repository.
+        return self.fast_repo.get_routers()
+
+    # * method: get_route
+    def get_route(self, endpoint: str) -> FastRouteContract:
+        '''
+        Retrieve a specific Fast API route by its router and route IDs.
+
+        :param endpoint: The endpoint in the format 'router_name.route_id'.
+        :type endpoint: str
+        :return: The corresponding FastRouteContract instance.
+        :rtype: FastRouteContract
+        '''
+
+        # Split the endpoint into router and route IDs.
+        router_name = None
+        try:
+            router_name, route_id = endpoint.split('.')
+        except ValueError:
+            route_id = endpoint
+
+        # Delegate the call to the repository.
+        route = self.fast_repo.get_route(
+            route_id=route_id,
+            router_name=router_name
+        )
+
+        # Raise an error if the route is not found.
+        if route is None:
+            raise_error.execute(
+                'FAST_ROUTE_NOT_FOUND',
+                f'Fast API route not found for endpoint: {endpoint}',
+                endpoint
+            )
+
+        # Return the found route.
+        return route
+
+    # * method: get_status_code
+    def get_status_code(self, error_code: str) -> int:
+        '''
+        Retrieve the HTTP status code for a given error code using the repository.
+
+        :param error_code: The error code identifier.
+        :type error_code: str
+        :return: The corresponding HTTP status code.
+        :rtype: int
+        '''
+
+        # Delegate the call to the repository.
+        return self.fast_repo.get_status_code(
+            error_code=error_code
+        )

tiferet_fast/models/__init__.py

@@ -0,0 +1,9 @@
+"""Fast API Model Exports"""
+
+# *** exports
+
+# ** app
+from .fast import (
+    FastRoute,
+    FastRouter
+)

tiferet_fast/models/fast.py

@@ -0,0 +1,119 @@
+"""Fast API domain models."""
+
+# *** imports
+
+# ** infra
+from tiferet.models import (
+    ModelObject,
+    StringType,
+    IntegerType,
+    ListType,
+    ModelType
+)
+
+# *** models
+
+# ** model: fast_route
+class FastRoute(ModelObject):
+    '''
+    A Fast route model.
+    '''
+
+    # * attribute: id
+    id = StringType(
+        required=True,
+        metadata=dict(
+            description='The unique identifier of the route.'
+        )
+    )
+
+    # * attribute: endpoint
+    endpoint = StringType(
+        required=True,
+        metadata=dict(
+            description='The unique identifier of the route endpoint.'
+        )
+    )
+
+    # * attribute: path
+    path = StringType(
+        required=True,
+        metadata=dict(
+            description='The URL path as string.'
+        )
+    )
+
+    # * attribute: methods
+    methods = ListType(
+        StringType,
+        required=True,
+        metadata=dict(
+            description='A list of HTTP methods this rule should be limited to.'
+        )
+    )
+
+    # * attribute: status_code
+    status_code = IntegerType(
+        default=200,
+        metadata=dict(
+            description='The default HTTP status code for the route response.'
+        )
+    )
+
+# ** model: fast_router
+class FastRouter(ModelObject):
+    '''
+    A Flask blueprint model.
+    '''
+
+    # * attribute: name
+    name = StringType(
+        required=True,
+        metadata=dict(
+            description='The name of the blueprint.'
+        )
+    )
+
+    # * attribute: url_prefix
+    prefix = StringType(
+        metadata=dict(
+            description='The URL prefix for all routes in this blueprint.'
+        )
+    )
+
+    # * attribute: routes
+    routes = ListType(
+        ModelType(FastRoute),
+        default=[],
+        metadata=dict(
+            description='A list of routes associated with this blueprint.'
+        )
+    )
+
+    # * method: add_route
+    def add_route(self, endpoint: str, path: str, methods: list[str], status_code: int = 200, **kwargs):
+        '''
+        Add a new route to the router.
+
+        :param endpoint: The unique identifier of the route endpoint.
+        :type endpoint: str
+        :param path: The URL path as string.
+        :type path: str
+        :param methods: A list of HTTP methods this rule should be limited to.
+        :type methods: list[str]
+        :param status_code: The default HTTP status code for the route response, defaults to 200.
+        :type status_code: int, optional
+        :param kwargs: Additional keyword arguments for route configuration.
+        :type kwargs: dict
+        '''
+
+        route = ModelObject.new(
+            FastRoute,
+            id=endpoint,
+            endpoint=f'{self.name}.{endpoint}',
+            path=path,
+            methods=methods,
+            status_code=status_code
+        )
+
+        self.routes.append(route)

tiferet_fast/proxies/__init__.py

@@ -0,0 +1,3 @@
+"""Fast API Proxy Exports"""
+
+# *** exports

tiferet_fast/proxies/yaml/__init__.py

@@ -0,0 +1,8 @@
+"""Fast API YAML Proxy Exports"""
+
+# *** exports
+
+# ** app
+from .fast import (
+    FastYamlProxy,
+)

tiferet_fast/proxies/yaml/fast.py

@@ -0,0 +1,143 @@
+"""Fast API YAML Configuration Proxy."""
+
+# *** imports
+
+# ** core
+from typing import List, Any
+
+# ** infra
+from tiferet import (
+    TiferetError,
+    raise_error
+)
+from tiferet.proxies.yaml import (
+    YamlConfigurationProxy
+)
+
+# ** app
+from ...contracts import (
+    FastApiRepository,
+    FastRouterContract,
+    FastRouteContract
+)
+from ...data import (
+    FastRouterYamlData
+)
+
+# *** proxies
+
+# ** proxy: fast_yaml_proxy
+class FastYamlProxy(FastApiRepository, YamlConfigurationProxy):
+    '''
+    A YAML configuration proxy for Fast API settings.
+    '''
+
+    # * init
+    def __init__(self, fast_config_file: str):
+        '''
+        Initialize the FastYamlProxy with the given YAML file path.
+
+        :param fast_config_file: The path to the Fast API configuration YAML file.
+        :type fast_config_file: str
+        '''
+
+        # Set the configuration file within the base class.
+        super().__init__(fast_config_file)
+
+    # * method: load_yaml
+    def load_yaml(self, start_node: callable = lambda data: data, create_data: callable = lambda data: data) -> Any:
+        '''
+        Load data from the YAML configuration file.
+
+        :param start_node: The starting node in the YAML file.
+        :type start_node: callable
+        :param create_data: A callable to create data objects from the loaded data.
+        :type create_data: callable
+        :return: The loaded data.
+        :rtype: Any
+        '''
+
+        # Load the YAML file contents using the yaml config proxy.
+        try:
+            return super().load_yaml(
+                start_node=start_node,
+                create_data=create_data
+            )
+
+        # Raise an error if the loading fails.
+        except (Exception, TiferetError) as e:
+            raise_error.execute(
+                'FAST_CONFIG_LOADING_FAILED',
+                f'Unable to load Fast API configuration file {self.config_file}: {e}.',
+                self.config_file,
+                str(e)
+            )
+
+    # * method: get_routers
+    def get_routers(self) -> List[FastRouterContract]:
+        '''
+        Retrieve all Fast API routers from the YAML configuration.
+
+        :return: A list of FastRouterContract instances.
+        :rtype: List[FastRouterContract]
+        '''
+
+        # Load the routers section from the YAML file.
+        data = self.load_yaml(
+            create_data=lambda data: [FastRouterYamlData.from_data(
+                name=name,
+                **router
+            ) for name, router in data.items()],
+            start_node=lambda d: d.get('fast', {}).get('routers', {})
+        )
+
+        # Map the loaded data to FastRouterContract instances.
+        return [router.map() for router in data]
+
+    # * method: get_route
+    def get_route(self, route_id: str, router_name: str = None) -> FastRouteContract:
+        '''
+        Retrieve a specific Fast API route by its router and route IDs from the YAML configuration.
+
+        :param route_id: The route identifier.
+        :type route_id: str
+        :param router_name: The name of the router (optional).
+        :type router_name: str
+        :return: The corresponding FastRouteContract instance.
+        :rtype: FastRouteContract
+        '''
+
+        # Load the routers section from the YAML file.
+        routers = self.get_routers()
+
+        # Search for the specified router.
+        for router in routers:
+            if router_name and router.name != router_name:
+                continue
+
+            # Search for the route within the router.
+            for route in router.routes:
+                if route.id == route_id:
+                    return route
+
+        # If not found, return None.
+        return None
+
+    # * method: get_status_code
+    def get_status_code(self, error_code: str) -> int:
+        '''
+        Retrieve the HTTP status code for a given error code from the YAML configuration.
+
+        :param error_code: The error code identifier.
+        :type error_code: str
+        :return: The corresponding HTTP status code.
+        :rtype: int
+        '''
+
+        # Load the error code from the errors section of the YAML file.
+        data = self.load_yaml(
+            start_node=lambda d: d.get('fast').get('errors', {})
+        )
+
+        # Return the status code if found, otherwise default to 500.
+        return data.get(error_code, 500)

tiferet_fast-0.1.0.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: tiferet-fast
+Version: 0.1.0
+Summary: An extension of the Tiferet Framework for the Fast API.
+Author-email: "Andrew Shatz, Great Strength Systems" <andrew@greatstrength.me>
+License: MIT
+Project-URL: Homepage, https://github.com/greatstrength/tiferet-fast
+Project-URL: Repository, https://github.com/greatstrength/tiferet-fast
+Project-URL: Download, https://github.com/greatstrength/tiferet-fast
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tiferet>=1.1.2
+Requires-Dist: fastapi>=0.118.0
+Requires-Dist: starlette-context>=0.4.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.3; extra == "test"
+Requires-Dist: pytest_env>=1.1.5; extra == "test"
+Dynamic: license-file
+
+# Tiferet Fast - A FastAPI Extension for the Tiferet Framework
+
+## Introduction
+
+Tiferet Fast elevates the Tiferet Python framework by enabling developers to build high-performance, asynchronous APIs using FastAPI, grounded in Domain-Driven Design (DDD) principles. Inspired by the concept of beauty in harmony, this extension integrates Tiferet’s command-driven architecture with FastAPI’s modern, declarative routing and automatic OpenAPI documentation. The result is a robust, modular platform for crafting scalable web services that transform complex business logic into elegant, extensible API designs.
+
+This tutorial guides you through creating a streamlined calculator API, leveraging Tiferet’s commands and configurations while introducing FastAPI-specific interfaces and endpoints. For a deeper understanding of Tiferet’s core concepts, refer to the [Tiferet documentation](https://github.com/greatstrength/tiferet).
+
+## Getting Started with Tiferet Fast
+
+Begin your Tiferet Fast journey by setting up your development environment. This guide assumes familiarity with Tiferet’s core setup.
+
+### Installing Python
+
+Tiferet Fast requires Python 3.10 or later. Follow the detailed [Python installation instructions](https://github.com/greatstrength/tiferet?tab=readme-ov-file#installing-python) in the Tiferet README for your platform (Windows, macOS, or Linux). Verify your installation with:
+
+```bash
+python3.10 --version
+```
+
+### Setting Up a Virtual Environment
+
+Create a dedicated virtual environment named `tiferet_fast_app` to manage dependencies:
+
+```bash
+# Create the Environment
+# Windows
+python -m venv tiferet_fast_app
+
+# macOS/Linux
+python3.10 -m venv tiferet_fast_app
+
+# Activate the Environment
+# Windows (Command Prompt)
+tiferet_fast_app\Scripts\activate
+
+# Windows (PowerShell)
+.\tiferet_fast_app\Scripts\Activate.ps1
+
+# macOS/Linux
+source tiferet_fast_app/bin/activate
+```
+
+Exit the environment with `deactivate` when finished.
+
+## Your First Calculator API
+
+With your environment ready, install dependencies and configure the project structure to build a dynamic calculator API using Tiferet Fast.
+
+### Installing Tiferet Fast
+
+In your activated virtual environment, install the Tiferet Fast extension using pip:
+
+```bash
+# Windows
+pip install tiferet_fast
+
+# macOS/Linux
+pip3 install tiferet_fast
+```
+
+Note: If developing locally, replace with the appropriate local installation command.
+
+### Project Structure
+
+Adapt Tiferet’s project structure to incorporate FastAPI, adding a dedicated API script:
+
+```plaintext
+project_root/
+├── basic_calc.py
+├── calc_cli.py
+├── calc_fast_api.py
+├── app/
+    ├── commands/
+    │   ├── __init__.py
+    │   ├── calc.py
+    │   └── settings.py
+    └── configs/
+        ├── __init__.py
+        ├── app.yml
+        ├── container.yml
+        ├── error.yml
+        ├── feature.yml
+        ├── fast.yml
+        └── logging.yml
+```
+
+The `app/commands/` and `app/configs/` directories align with Tiferet’s structure (see [Tiferet README](https://github.com/greatstrength/tiferet?tab=readme-ov-file#project-structure)). The `calc_fast_api.py` script initializes and runs the FastAPI application, while `fast.yml` defines router and routing configurations.
+
+## Crafting the Calculator API
+
+Extend Tiferet’s calculator application into a powerful API by reusing its commands and configurations, enhanced with FastAPI-specific functionality.
+
+### Defining Base and Arithmetic Command Classes
+
+Leverage Tiferet’s `BasicCalcCommand` (`app/commands/settings.py`) for input validation and arithmetic commands (`AddNumber`, `SubtractNumber`, `MultiplyNumber`, `DivideNumber`, `ExponentiateNumber` in `app/commands/calc.py`) for core operations. These remain unchanged from the original calculator app; refer to the [Tiferet README](https://github.com/greatstrength/tiferet?tab=readme-ov-file#defining-base-and-arithmetic-command-classes) for details.
+
+### Configuring the Calculator API
+
+Reuse Tiferet’s `container.yml` ([here](https://github.com/greatstrength/tiferet?tab=readme-ov-file#configuring-the-container-in-configscontaineryml)), `error.yml` ([here](https://github.com/greatstrength/tiferet?tab=readme-ov-file#configuring-the-errors-in-configserroryml)), and `feature.yml` ([here](https://github.com/greatstrength/tiferet?tab=readme-ov-file#configuring-the-features-in-configsfeatureyml)) for command mappings, error handling, and feature workflows. Introduce a FastAPI-specific interface in `app.yml` and routing configurations in `fast.yml`.
+
+#### Configuring the App Interface in `configs/app.yml`
+
+Enhance `app/configs/app.yml` with the `calc_fast_api` interface:
+
+```yaml
+interfaces:
+  calc_fast_api:
+    name: Basic Calculator API
+    description: Perform basic calculator operations via FastAPI
+    module_path: tiferet_fast.contexts.fast
+    class_name: FastApiContext
+    attrs:
+      fast_api_handler:
+        module_path: tiferet_fast.handlers.fast
+        class_name: FastApiHandler
+      fast_repo:
+        module_path: tiferet_fast.proxies.yaml.fast
+        class_name: FastYamlProxy
+        params:
+          fast_config_file: app/configs/fast.yml
+```
+
+#### Configuring Routers, Routes, and Error Status Codes in `configs/fast.yml`
+
+Define FastAPI routers, routes, and error mappings in `app/configs/fast.yml`:
+
+```yaml
+fast:
+  routers:
+    calc:
+      name: calc
+      prefix: /calc
+      routes:
+        add:
+          path: /add
+          methods: [POST, GET]
+          status_code: 200
+        subtract:
+          path: /subtract
+          methods: [POST, GET]
+          status_code: 200
+        multiply:
+          path: /multiply
+          methods: [POST, GET]
+          status_code: 200
+        divide:
+          path: /divide
+          methods: [POST, GET]
+          status_code: 200
+        sqrt:
+          path: /sqrt
+          methods: [POST, GET]
+          status_code: 200
+  errors:
+    DIVIDE_BY_ZERO: 400
+```
+
+The `prefix` ensures all routes are prefixed with `/calc`. Each route’s endpoint (e.g., `calc.add`) aligns with the corresponding feature ID in `feature.yml`. Routes specify a `path`, supported HTTP `methods`, and a default `status_code` of 200. The `errors` section maps error codes from `error.yml` to HTTP status codes, ensuring proper error handling.
+
+This configuration enables `FastApiContext` to orchestrate FastAPI operations seamlessly.
+
+### Initializing and Demonstrating the API in `calc_fast_api.py`
+
+Create `calc_fast_api.py` to initialize the API and define endpoints:
+
+```python
+"""Tiferet Fast Calculator Initialization Script"""
+
+# *** imports
+
+# ** infra
+from tiferet import App
+from tiferet_fast.contexts.fast import FastApiContext
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+import uvicorn
+
+# *** functions
+
+# * function: view_func
+async def view_func(request: Request):
+    '''
+    Call the view function whenever a route endpoint is invoked.
+
+    :param context: The Fast API context.
+    :type context: FastApiContext
+    :param kwargs: Additional keyword arguments.
+    :type kwargs: dict
+    :return: The result of the view function.
+    :rtype: Any
+    '''
+
+    data = await request.json() if request.headers.get('content-type') == 'application/json' else {}
+    data.update(dict(request.query_params))
+    data.update(dict(request.path_params))
+
+    # Format header data from the request headers.
+    headers = dict(request.headers)
+
+    # Execute the feature from the request endpoint.
+    response, status_code = context.run(
+        feature_id=request.scope['route'].name,
+        headers=headers,
+        data=data,
+    )
+
+    # Return the response.
+    return JSONResponse(response, status_code=status_code)
+
+# *** exec
+
+# Create the Fast API context.
+context: FastApiContext = App().load_interface('calc_fast_api')
+
+# Build the FastAPI app.
+context.build_fast_app(view_func=view_func)
+
+# Define the fast_app for external use (e.g., for FastAPI CLI or ASGI servers).
+def fast_app():
+    '''
+    Create and return the FastAPI app for testing.
+
+    :return: The FastAPI app.
+    :rtype: FastAPI
+    '''
+
+    return context.fast_app
+
+# Run the FastAPI app if this script is executed directly.
+if __name__ == '__main__':
+    uvicorn.run(context.fast_app, host='127.0.0.1', port=8000)
+```
+
+This script initializes the Tiferet application, loads the `calc_fast_api` interface, and dynamically handles RESTful endpoints for arithmetic operations using FastAPI’s asynchronous routing.
+
+### Demonstrating the Calculator API
+
+Launch the API:
+
+```bash
+python3 calc_fast_api.py
+```
+
+Test endpoints using curl or tools like Postman:
+
+```bash
+# Add two numbers
+curl -X POST http://127.0.0.1:8000/calc/add -H "Content-Type: application/json" -d '{"a": 1, "b": 2}'
+# Output: 3
+
+# Calculate square root
+curl -X POST http://127.0.0.1:8000/calc/sqrt -H "Content-Type: application/json" -d '{"a": 16}'
+# Output: 4.0
+
+# Division by zero
+curl -X POST http://127.0.0.1:8000/calc/divide -H "Content-Type: application/json" -d '{"a": 5, "b": 0}'
+# Output: {"error_code": "DIVIDE_BY_ZERO", "text": "Cannot divide by zero"}
+```
+
+## Conclusion
+
+Tiferet Fast empowers developers to craft high-performance, asynchronous FastAPI applications within Tiferet’s DDD framework, as demonstrated in this calculator tutorial. By reusing Tiferet’s commands and configurations and introducing a FastAPI interface, you’ve built a scalable, intuitive API with minimal effort. Expand its capabilities by integrating authentication, advanced features like trigonometric operations, or combining with Tiferet’s CLI or TUI contexts. Explore the [Tiferet documentation](https://github.com/greatstrength/tiferet) for advanced DDD techniques, and experiment with `app/configs/` to customize your API, transforming complex web applications into clear, purposeful solutions.

tiferet_fast-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+tiferet_fast/__init__.py,sha256=Xiq4CgSuRQxcLXwiuIXiogK7J5_IaaviMAkfdehd_R0,291
+tiferet_fast/contexts/__init__.py,sha256=F8zAxiH0zHtx4RkyISgfao6NKawMOhJEfO8jxa4m34U,129
+tiferet_fast/contexts/fast.py,sha256=SvUFIRnN5--tTOPbCW_tf7mmeenz7inFFeYRU-7WYNY,6403
+tiferet_fast/contexts/request.py,sha256=e7wH8tjtwBaP8Lvn01B_mEYdslcBDIjfqVXxXwXOW3I,1911
+tiferet_fast/contracts/__init__.py,sha256=JHEX7ZauPjYr85bZ2hPwXSESL58OWS-19Vle5miAYds,153
+tiferet_fast/contracts/fast.py,sha256=wj7PTnpqaX2V3XLjEUZ1fqrctUSKXxaso2Zbnft-UDQ,2133
+tiferet_fast/data/__init__.py,sha256=bPQ_D1Q4XWCsus05kapNCLM3VY0gnqmkPAel325W46Q,153
+tiferet_fast/data/fast.py,sha256=wuJYKAYUKHO6M3MTs8PVnR2L6dGJFQ3loqvcKR4wcjg,3633
+tiferet_fast/handlers/__init__.py,sha256=pJWGC5uvM8tcSYbibQfIbWEZYytibmjbCOXT-e8tIb0,97
+tiferet_fast/handlers/fast.py,sha256=E7Fu19AwfxcCwiAjBW6r2wTuZo3C6OcpJ_8F0XW3eOw,2645
+tiferet_fast/models/__init__.py,sha256=ZCW9wqQ2q6AtTye2rsjjkefMw7rAICG74oI2CFQgpZQ,106
+tiferet_fast/models/fast.py,sha256=3PAxhfyNIpZKiXybY-3YROU0dIGQ--l0eNWOjAIiizk,2836
+tiferet_fast/proxies/__init__.py,sha256=cEj1-XgVWIFdDZW3fj9HJI82dVmzc9E0-DAXolOGdGY,44
+tiferet_fast/proxies/yaml/__init__.py,sha256=WkdGmW8qmFJx65kv67h7r5i3zbioOpTul6uwcn9GRqo,100
+tiferet_fast/proxies/yaml/fast.py,sha256=WMf6hZtRKBbSsbtjAia_LtuuMHADy4MT_mUBCFazvnc,4333
+tiferet_fast-0.1.0.dist-info/licenses/LICENSE,sha256=1wptiB9OGy7aH1XHHktyLpobVyxc_Ek2yE5gYpP1VOE,1079
+tiferet_fast-0.1.0.dist-info/METADATA,sha256=4h0Zc9z9upcvZ5I9qw2c9zAKX4I_lHhPXckBSJ3jMrU,10675
+tiferet_fast-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tiferet_fast-0.1.0.dist-info/top_level.txt,sha256=hSa7q81duh97rZo4WR-Ke9W22oK1doNn38WNBPObRWg,13
+tiferet_fast-0.1.0.dist-info/RECORD,,

tiferet_fast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tiferet_fast-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Great Strength Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiferet_fast-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tiferet_fast