neuroglia-python 0.0.23__py3-none-any.whl

neuroglia/mapping/__init__.py

@@ -0,0 +1 @@
+from .mapper import Mapper as Mapper

neuroglia/mapping/mapper.py

@@ -0,0 +1,238 @@
+import importlib
+import inspect
+from typing import Any, Callable, List, Type
+from neuroglia.core import ModuleLoader, TypeFinder
+from neuroglia.hosting.abstractions import ApplicationBuilderBase
+
+
+def label(name: str, value: str):
+    ''' Represents a decorator used to add a custom label (key, value) to a class'''
+    def decorator(cls):
+        if "__labels__" not in dir(cls):
+            cls.__labels__ = dict()
+        cls.__labels__[name] = value
+        return cls
+    return decorator
+
+
+def labels(**kwargs):
+    ''' Represents a decorator used to add one or more custom labels to a class'''
+    def decorator(cls):
+        if "__labels__" not in dir(cls):
+            cls.__labels__ = dict()
+        for k, v in kwargs.items():
+            cls.__labels__[k] = v
+        return cls
+    return decorator
+
+
+def map_to(target_type: Type):
+    ''' Represents a decorator used to create a mapping of the marked class to a specified type '''
+    def decorator(cls):
+        cls.__map_to__ = target_type
+        return cls
+    return decorator
+
+
+def map_from(source_type: Type):
+    ''' Represents a decorator used to create a mapping from a specified type to the marked class '''
+    def decorator(cls):
+        cls.__map_from__ = source_type
+        return cls
+    return decorator
+
+
+class TypeMappingContext:
+    ''' Represents the context of a type mapping '''
+
+    def __init__(self, source: Any, source_type: Type, destination_type: Type):
+        self.source = source
+        self.source_type = source_type
+        self.destination_type = destination_type
+
+    source: Any
+    ''' Gets the value to map '''
+
+    source_type: Type
+    ''' Gets the type of the value to map '''
+
+    destination_type: Type
+    ''' Gets the type to map the source to '''
+
+
+class MemberMappingContext(TypeMappingContext):
+    ''' Represents the context of a type mapping '''
+
+    def __init__(self, source: Any, source_type: Type, destination_type: Type, member_name: str, source_member_value: Any):
+        super().__init__(source, source_type, destination_type)
+        self.member_name = member_name
+        self.source_member_value = source_member_value
+
+    member_name: str
+
+    source_member_value: Any
+
+
+class MemberMapConfiguration:
+    ''' Represents an object used to configure the mapping of a type member '''
+
+    def __init__(self, name: str, is_ignored: bool = False, value_converter: Callable[[MemberMappingContext], Any] = None):
+        self.name = name
+        self.is_ignored = is_ignored
+        self.value_converter = value_converter
+
+    name: str
+    ''' Gets the name of the configured member '''
+
+    is_ignored: bool
+    ''' Gets a boolean indicating whether or not the member is ignored '''
+
+    value_converter: Callable[[MemberMappingContext], Any]
+    ''' Gets a callable, if any, used to convert the value of the member '''
+
+
+class TypeMapConfiguration:
+    ''' Represents an object used to configure the mapping of a type to another '''
+
+    def __init__(self, source_type: Type, destination_type: Type, type_converter: Callable[[Any], Any] = None):
+        self.source_type = source_type
+        self.destination_type = destination_type
+        self.type_converter = type_converter
+
+    source_type: Type
+    ''' Gets the type to convert to the specified type '''
+
+    destination_type: Type
+    ''' Gets the type to convert source values to '''
+
+    type_converter: Callable[[TypeMappingContext], Any]
+    ''' Gets the callable, if any, used to convert source instances to the configured destination type '''
+
+    member_configurations: List[MemberMapConfiguration] = list[MemberMapConfiguration]()
+    ''' Gets a list containing objects used to configure how to map members of the configured source and destination types '''
+
+    def map(self, source: Any):
+        ''' Maps the specified value to the configured destination type '''
+        mapping_context = TypeMappingContext(source, self.source_type, self.destination_type)
+        if self.type_converter is not None:
+            return self.type_converter(mapping_context)
+        source_attributes = dict([(key, value) for key, value in source.__dict__.items() if not key.startswith('_')]) if hasattr(source, "__dict__") else dict()
+        destination_attributes = dict()
+        declared_attributes = [key for key, _ in self.destination_type.__annotations__.items() if not key.startswith('_')] if hasattr(self.destination_type, "__annotations__") else list[str]()
+        for source_attribute_key, source_attribute_value in source_attributes.items():
+            if not source_attribute_key in declared_attributes:
+                continue
+            member_map = next((member for member in self.member_configurations if member.name == source_attribute_key), None)
+            if member_map is None:
+                destination_attributes[source_attribute_key] = source_attribute_value
+            elif member_map.is_ignored:
+                continue
+            else:
+                destination_attributes[source_attribute_key] = member_map.value_converter(MemberMappingContext(source, self.source_type, self.destination_type, source_attribute_key, source_attribute_value))
+        for configured_attribute in [attr for attr in self.member_configurations if attr not in source_attributes.keys()]:
+            if configured_attribute.is_ignored or configured_attribute.value_converter is None:
+                continue
+            destination_attributes[configured_attribute.name] = configured_attribute.value_converter(MemberMappingContext(source, self.source_type, self.destination_type, configured_attribute.name, None))
+        destination = object.__new__(self.destination_type)
+        destination.__dict__ = destination_attributes
+        return destination
+
+
+class TypeMapExpression:
+    ''' Represents a type mapping expression, used to fluently build and configure a new TypeMapConfiguration '''
+
+    def __init__(self, configuration: TypeMapConfiguration):
+        self._configuration = configuration
+
+    _configuration: TypeMapConfiguration
+
+    def convert_using(self, converter: Callable[[TypeMappingContext], Any]) -> None:
+        ''' Maps values using the specified converter function '''
+        self._configuration.type_converter = converter
+
+    def ignore_member(self, name: str) -> 'TypeMapExpression':
+        ''' Configures the map to ignore the specified member of the source type '''
+        configuration = next((member for member in self._configuration.member_configurations if member.name == name), None)
+        if configuration is None:
+            self._configuration.member_configurations.append(MemberMapConfiguration(name, True))
+        else:
+            configuration.is_ignored = True
+        return self
+
+    def for_member(self, name: str, converter: Callable[[MemberMappingContext], Any]):
+        ''' Configures the mapping of the specified member to use a converter function '''
+        configuration = next((member for member in self._configuration.member_configurations if member.name == name), None)
+        if configuration is None:
+            self._configuration.member_configurations.append(MemberMapConfiguration(name, value_converter=converter))
+        else:
+            configuration.value_converter = converter
+        return self
+
+
+class MapperConfiguration:
+
+    type_maps: List[TypeMapConfiguration] = list[TypeMapConfiguration]()
+
+    def create_map(self, source_type: Type, destination_type: Type) -> TypeMapExpression:
+        ''' Creates a new expression used to convert how to map instances of the source type to instances of the destination type '''
+        configuration: TypeMapConfiguration = next((tmc for tmc in self.type_maps if tmc.source_type == source_type and tmc.destination_type == destination_type), None)
+        if configuration is None:
+            configuration = TypeMapConfiguration(source_type, destination_type)
+            self.type_maps.append(configuration)
+        return TypeMapExpression(configuration)
+
+
+class MappingProfile:
+    ''' Represents a class used to configure a mapper'''
+
+    _configuration_actions: List[Callable[[MapperConfiguration], None]] = list[Callable[[MapperConfiguration], None]]()
+    ''' Gets the mapper configuration to configure '''
+
+    def create_map(self, source_type: Type, destination_type: Type) -> TypeMapExpression:
+        ''' Creates a new expression used to convert how to map instances of the source type to instances of the destination type '''
+        callable: Callable[[MapperConfiguration], None] = lambda config: config.create_map(source_type, destination_type)
+        self._configuration_actions.append(callable)
+
+    def apply_to(self, configuration: MapperConfiguration) -> MapperConfiguration:
+        ''' Applies the mapping profile to the specified mapper configuration '''
+        for configuration_action in self._configuration_actions:
+            configuration_action(configuration)
+        return configuration
+
+
+class Mapper:
+    ''' Represents the service used to map objects '''
+
+    def __init__(self, options: MapperConfiguration):
+        self.options = options
+
+    options: MapperConfiguration
+    ''' Gets the options used to configure the mapper '''
+
+    def map(self, source: Any, destination_type: Type) -> Any:
+        ''' Maps the specified value into a new instance of the destination type '''
+        source_type = type(source)
+        type_map = next((tmc for tmc in self.options.type_maps if tmc.source_type == source_type and tmc.destination_type == destination_type), None)
+        if type_map is None:
+            raise Exception(f"Missing type map configuration or unsupported mapping. Mapping types: {source_type.__name__} -> {destination_type.__name__}")
+        destination = type_map.map(source)
+        return destination
+
+    @staticmethod
+    def configure(builder: ApplicationBuilderBase, modules: List[str] = list[str]()) -> ApplicationBuilderBase:
+        ''' Registers and configures mapping-related services to the specified service collection.
+
+            Args:
+                services (ServiceCollection): the service collection to configure
+                modules (List[str]): a list containing the names of the modules to scan for MappingProfiles, which are classes used to configure the Mapper
+        '''
+        configuration: MapperConfiguration = MapperConfiguration()
+        for module in [ModuleLoader.load(module_name) for module_name in modules]:
+            mapping_profile_types = TypeFinder.get_types(module, lambda cls: inspect.isclass(cls) and issubclass(cls, MappingProfile) and cls != MappingProfile, include_sub_packages=True)
+            for mapping_profile_type in mapping_profile_types:
+                mapping_profile: MappingProfile = object.__new__(mapping_profile_type)
+                mapping_profile.__init__()
+                mapping_profile.apply_to(configuration)
+        builder.services.add_singleton(MapperConfiguration, singleton=configuration)
+        builder.services.add_singleton(Mapper)
+        return builder

neuroglia/mediation/__init__.py

@@ -0,0 +1 @@
+from .mediator import *

neuroglia/mediation/mediator.py

@@ -0,0 +1,182 @@
+import asyncio
+import inspect
+import logging
+
+from abc import ABC, abstractmethod
+from types import UnionType
+from typing import Any, Generic, List, Optional, TypeVar
+from neuroglia.core import ModuleLoader, OperationResult, TypeFinder, TypeExtensions
+from neuroglia.data.abstractions import DomainEvent
+from neuroglia.dependency_injection.service_provider import ServiceProviderBase
+from neuroglia.hosting.abstractions import ApplicationBuilderBase
+from neuroglia.integration.models import IntegrationEvent
+
+log = logging.getLogger(__name__)
+
+
+TResult = TypeVar('TResult', bound=OperationResult)
+''' Represents the expected type of result returned by the operation, in case of success '''
+
+
+class Request(Generic[TResult], ABC):
+    ''' Represents a CQRS request '''
+    pass
+
+
+class Command(Generic[TResult], Request[TResult], ABC):
+    ''' Represents a CQRS command '''
+    pass
+
+
+class Query(Generic[TResult], Request[TResult], ABC):
+    ''' Represents a CQRS query '''
+    pass
+
+
+TRequest = TypeVar('TRequest', bound=Request)
+''' Represents the type of CQRS request to handle '''
+
+
+class RequestHandler(Generic[TRequest, TResult], ABC):
+    ''' Represents a service used to handle a specific type of CQRS request '''
+
+    @abstractmethod
+    async def handle_async(self, request: TRequest) -> TResult:
+        ''' Handles the specified request '''
+        raise NotImplementedError()
+
+    def ok(self, data: Optional[Any] = None) -> TResult:
+        result: OperationResult = OperationResult("OK", 200)
+        result.data = data
+        return result
+
+    def created(self, data: Optional[Any] = None) -> TResult:
+        result: OperationResult = OperationResult("Created", 201)
+        result.data = data
+        return result
+
+    def bad_request(self, detail: str) -> TResult:
+        ''' Creates a new OperationResult to describe the fact that the request is invalid '''
+        return OperationResult("Bad Request", 400, detail, "https://www.w3.org/Protocols/HTTP/HTRESP.html#:~:text=Bad%20Request")
+
+    def not_found(self, entity_type, entity_key, key_name: str = "id") -> TResult:
+        ''' Creates a new OperationResult to describe the fact that an entity of the specified type and key could not be found or does not exist '''
+        return OperationResult("Not Found", 404, f"Failed to find an entity of type '{entity_type.__name__}' with the specified {key_name} '{entity_key}'", "https://www.w3.org/Protocols/HTTP/HTRESP.html#:~:text=Not%20found%20404")
+
+
+TCommand = TypeVar('TCommand', bound=Command)
+''' Represents the type of CQRS command to handle '''
+
+
+class CommandHandler(Generic[TCommand, TResult], RequestHandler[TCommand, TResult], ABC):
+    ''' Represents a service used to handle a specific type of CQRS command '''
+
+    pass
+
+
+TQuery = TypeVar('TQuery', bound=Query)
+''' Represents the type of CQRS query to handle '''
+
+
+class QueryHandler(Generic[TQuery, TResult], RequestHandler[TQuery, TResult], ABC):
+    ''' Represents a service used to handle a specific type of CQRS query '''
+
+    pass
+
+
+TNotification = TypeVar('TNotification', bound=object)
+''' Represents the type of CQRS notification to handle '''
+
+
+class NotificationHandler(Generic[TNotification], ABC):
+    ''' Represents a service used to handle a specific type of CQRS notification'''
+
+    @abstractmethod
+    async def handle_async(self, notification: TNotification) -> None:
+        ''' Handles the specified notification '''
+        raise NotImplementedError()
+
+
+TDomainEvent = TypeVar('TDomainEvent', bound=DomainEvent)
+''' Represents the type of domain event to handle '''
+
+
+class DomainEventHandler(Generic[TDomainEvent], NotificationHandler[TDomainEvent], ABC):
+    ''' Represents a service used to handle a specific domain event '''
+
+    pass
+
+
+TIntegrationEvent = TypeVar('TIntegrationEvent', bound=IntegrationEvent)
+''' Represents the type of integration event to handle '''
+
+
+class IntegrationEventHandler(Generic[TIntegrationEvent], NotificationHandler[TIntegrationEvent], ABC):
+    ''' Represents a service used to handle a specific integration event '''
+
+    pass
+
+
+class Mediator:
+    ''' Represents the default implementation of the IMediator class '''
+
+    _service_provider: ServiceProviderBase
+
+    def __init__(self, service_provider: ServiceProviderBase):
+        self._service_provider = service_provider
+
+    async def execute_async(self, request: Request) -> OperationResult:
+        ''' Executes the specified request '''
+        handlers: List[RequestHandler] = [candidate for candidate in self._service_provider.get_services(RequestHandler) if self._request_handler_matches(candidate, request)]
+        if handlers is None or len(handlers) < 1:
+            raise Exception(f"Failed to find a handler for request of type '{type(request).__name__}'")
+        elif len(handlers) > 1:
+            raise Exception(f"There must be exactly one handler defined for the command of type '{type(request).__name__}'")
+        log.info(f"Executing request type {type(request).__name__}")
+        handler = handlers[0]
+        return await handler.handle_async(request)
+
+    async def publish_async(self, notification: object):
+        ''' Publishes the specified notification '''
+        handlers: List[NotificationHandler] = [candidate for candidate in self._service_provider.get_services(NotificationHandler) if self._notification_handler_matches(candidate, type(notification))]
+        if handlers is None or len(handlers) < 1:
+            return
+        await asyncio.gather(*(handler.handle_async(notification) for handler in handlers))
+
+    def _request_handler_matches(self, candidate, request_type) -> bool:
+        expected_request_type = request_type.__orig_class__ if hasattr(request_type, "__orig_class__") else request_type
+        handler_type = TypeExtensions.get_generic_implementation(candidate, RequestHandler)
+        handled_request_type = handler_type.__args__[0]
+        if type(handled_request_type) == type(expected_request_type):
+            matches = handled_request_type == expected_request_type
+            return matches
+        else:
+            return handled_request_type == type(expected_request_type)
+
+    def _notification_handler_matches(self, candidate, request_type) -> bool:
+        candidate_type = type(candidate)
+        handler_type = next(base for base in candidate_type.__orig_bases__ if (issubclass(base.__origin__, NotificationHandler) if hasattr(base, '__origin__') else issubclass(base, NotificationHandler)))
+        handled_notification_type = handler_type.__args__[0]
+        if isinstance(handled_notification_type, UnionType):
+            return any(issubclass(t, request_type) for t in handled_notification_type.__args__)
+        else:
+            return issubclass(handled_notification_type.__origin__, request_type) if hasattr(handled_notification_type, '__origin__') else issubclass(handled_notification_type, request_type)
+
+    def configure(app: ApplicationBuilderBase, modules: List[str] = list[str]()) -> ApplicationBuilderBase:
+        ''' Registers and configures mediation-related services (command/query/notification handlers) to the specified service collection.
+
+            Args:
+                services (ServiceCollection): the service collection to configure
+                modules (List[str]): a list containing the names of the modules to scan for mediation services to register
+        '''
+        for module in [ModuleLoader.load(module_name) for module_name in modules]:
+            for command_handler_type in TypeFinder.get_types(module, lambda cls: inspect.isclass(cls) and (not hasattr(cls, "__parameters__") or len(cls.__parameters__) < 1) and issubclass(cls, CommandHandler) and cls != CommandHandler, include_sub_modules=True):
+                app.services.add_transient(RequestHandler, command_handler_type)
+            for queryhandler_type in TypeFinder.get_types(module, lambda cls: inspect.isclass(cls) and not hasattr(cls, "__parameters__") and issubclass(cls, QueryHandler) and cls != QueryHandler, include_sub_modules=True):
+                app.services.add_transient(RequestHandler, queryhandler_type)
+            for domain_event_handler_type in TypeFinder.get_types(module, lambda cls: inspect.isclass(cls) and issubclass(cls, DomainEventHandler) and cls != DomainEventHandler, include_sub_modules=True):
+                app.services.add_transient(NotificationHandler, domain_event_handler_type)
+            for integration_event_handler_type in TypeFinder.get_types(module, lambda cls: inspect.isclass(cls) and issubclass(cls, IntegrationEventHandler) and cls != IntegrationEventHandler, include_sub_packages=True):
+                app.services.add_transient(NotificationHandler, integration_event_handler_type)
+        app.services.add_singleton(Mediator)
+        return app

neuroglia/mvc/controller_base.py

@@ -0,0 +1,72 @@
+import uuid
+
+from typing import Dict, Any
+from classy_fastapi import Routable
+from fastapi import Response
+from fastapi.routing import APIRoute
+from neuroglia.core.operation_result import OperationResult
+from neuroglia.core.problem_details import ProblemDetails
+from neuroglia.dependency_injection.service_provider import ServiceProviderBase
+from neuroglia.mapping.mapper import Mapper
+from neuroglia.mediation.mediator import Mediator
+from neuroglia.serialization.json import JsonSerializer
+
+
+def generate_unique_id_function(route: APIRoute) -> str | APIRoute:
+    if route.tags and route.name:
+        tag = str(route.tags[0])
+        return f"{tag.lower()}_{route.name}"
+    elif route.methods and route.name:
+        method = str(route.methods.pop()).lower()
+        name = route.name.lower()
+        return f"{name}_{method}"
+    else:
+        method = str(route.methods.pop()).lower()
+        name = route.name.lower()
+        return f"{name}"
+
+
+class ControllerBase(Routable):
+    """Represents the base class of all API controllers"""
+
+    def __init__(self, service_provider: ServiceProviderBase, mapper: Mapper, mediator: Mediator):
+        """Initializes a new ControllerBase"""
+        self.service_provider = service_provider
+        self.mapper = mapper
+        self.mediator = mediator
+        self.json_serializer = self.service_provider.get_required_service(JsonSerializer)
+        self.name = self.__class__.__name__.replace("Controller", "").strip()
+        super().__init__(
+            prefix=f"/{self.name.lower()}",
+            tags=[self.name],
+            generate_unique_id_function=generate_unique_id_function,
+        )
+
+    service_provider: ServiceProviderBase
+    """ Gets the current ServiceProviderBase """
+
+    mapper: Mapper
+    """ Gets the service used to map objects """
+
+    mediator: Mediator
+    """ Gets the service used to mediate calls """
+
+    json_serializer: JsonSerializer
+
+    name: str
+    """ Gets/sets the name of the controller, which is used to configure the controller's router. Defaults to the lowercased name of the implementing controller class, excluding the term 'Controller' """
+
+    def process(self, result: OperationResult):
+        """Processes the specified operation result"""
+        content = result.data if result.status >= 200 and result.status < 300 else result
+        media_type = "application/json"
+        if content is not None:
+            content = self.json_serializer.serialize_to_text(content)
+            media_type = "application/json"
+        return Response(status_code=result.status, content=content, media_type=media_type)
+
+    error_responses: Dict[int | str, Dict[str, Any]] | None = {
+        400: {"model": ProblemDetails, "description": "Bad Request"},
+        404: {"model": ProblemDetails, "description": "Not Found"},
+        500: {"model": ProblemDetails, "description": "Internal Server Error"},
+    }

neuroglia/reactive/__init__.py

@@ -0,0 +1 @@
+from .rx_async import AsyncRx

neuroglia/reactive/rx_async.py

@@ -0,0 +1,16 @@
+# import asyncio
+from rx import operators as ops
+from rx.core.observable.observable import Observable
+from typing import Any, Callable
+
+import rx
+
+
+class AsyncRx:
+
+    @staticmethod
+    def subscribe(source: Observable, on_next: Callable[[Any], None]):
+        return source.pipe(
+            ops.map(lambda value: rx.from_future(on_next(value))),
+            ops.concat()
+        ).subscribe(lambda e: None)

neuroglia/serialization/abstractions.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional, Type
+
+
+class Serializer(ABC):
+    ''' Represents the base class for all serializers '''
+
+    @abstractmethod
+    def serialize(self, value: Any) -> bytearray:
+        ''' Serializes the specified value '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    def deserialize(self, input: bytearray, expected_type: Optional[Type]) -> Any:
+        ''' Deserializes the specified input into a new value of the specified type, if any '''
+        raise NotImplementedError()
+
+
+class TextSerializer(Serializer, ABC):
+    ''' Represents the base class for all text serializers '''
+
+    @abstractmethod
+    def serialize_to_text(self, value: Any) -> str:
+        ''' Serializes the specified value to text '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    def deserialize_from_text(self, input: str, expected_type: Optional[Type] = None) -> Any:
+        ''' Deserializes the specified input into a new value of the specified type, if any '''
+        raise NotImplementedError()