neuroglia-python 0.0.23__py3-none-any.whl

neuroglia/data/queryable.py

@@ -0,0 +1,175 @@
+import ast
+import inspect
+import os
+from abc import ABC, abstractclassmethod
+from ast import Attribute, Name, NodeTransformer, expr
+from typing import Any, Callable, Dict, Generic, List, Optional, Type, TypeVar
+
+
+T = TypeVar('T')
+''' Represents the type of data associated to a queryable '''
+
+
+class QueryProvider(ABC):
+    ''' Defines the fundamentals of a service used to create and execute queries associated with the data source '''
+
+    @abstractclassmethod
+    def create_query(self, element_type: Type, expression: expr) -> 'Queryable':
+        ''' Creates a new queryable based on the specified expression '''
+        raise NotImplementedError()
+
+    @abstractclassmethod
+    def execute(self, expression: expr, query_type: Type) -> Any:
+        ''' Executes the specified query expression '''
+        raise NotImplementedError()
+
+
+class Queryable(Generic[T]):
+    ''' Provides functionality to evaluate queries against a specific data source '''
+
+    def __init__(self, provider: QueryProvider, expression: Optional[expr] = None):
+        self.provider = provider
+        self.expression = ast.Name(id='__query') if expression is None else expression
+
+    expression: expr
+    ''' Gets the expression that is associated with the queryable '''
+
+    provider: QueryProvider
+    ''' Gets the service used to create and execute queries associated with the data source '''
+
+    def get_element_type(self) -> Type:
+        ''' Gets the type of elements to query against '''
+        return self.__orig_class__.__args__[0]
+
+    def first_or_default(self, predicate: Callable[[T], bool] = None) -> T:
+        ''' Gets the first element in the sequence that matches the specified predicate, if any '''
+        frame = inspect.currentframe().f_back
+        frame_info = inspect.getframeinfo(frame)
+        variables = {**frame.f_locals}
+        lambda_src = self._get_lambda_source_code(predicate, frame_info.positions.end_col_offset)
+        lambda_tree = ast.parse(lambda_src)
+        lambda_expression = lambda_tree.body[0].value
+        expression = VariableExpressionReplacer(variables).visit(ast.Call(func=ast.Attribute(value=self.expression, attr='first', ctx=ast.Load()), args=[lambda_expression], keywords=[]))
+        query = self.provider.create_query(self.get_element_type(), expression)
+        return self.provider.execute(query.expression, T)
+
+    def first(self, predicate: Callable[[T], bool] = None) -> T:
+        ''' Gets the first element in the sequence that matches the specified predicate, if any '''
+        result = self.first_or_default(predicate)
+        if result is None and T != None:
+            raise Exception("No match")
+        return result
+
+    def last_or_default(self, predicate: Callable[[T], bool] = None) -> T:
+        ''' Gets the last element in the sequence that matches the specified predicate, if any '''
+        frame = inspect.currentframe().f_back
+        frame_info = inspect.getframeinfo(frame)
+        variables = {**frame.f_locals}
+        lambda_src = self._get_lambda_source_code(predicate, frame_info.positions.end_col_offset)
+        lambda_tree = ast.parse(lambda_src)
+        lambda_expression = lambda_tree.body[0].value
+        expression = VariableExpressionReplacer(variables).visit(ast.Call(func=ast.Attribute(value=self.expression, attr='last', ctx=ast.Load()), args=[lambda_expression], keywords=[]))
+        query = self.provider.create_query(self.get_element_type(), expression)
+        return self.provider.execute(query.expression, T)
+
+    def last(self, predicate: Callable[[T], bool] = None) -> T:
+        ''' Gets the last element in the sequence that matches the specified predicate, if any '''
+        result = self.last_or_default(predicate)
+        if result is None and T != None:
+            raise Exception("No match")
+        return result
+
+    def order_by(self, selector: Callable[[T], Any]):
+        ''' Orders the sequence using the specified attribute '''
+        selector_source = self._get_lambda_source_code(selector)
+        selector_tree = ast.parse(selector_source)
+        selector_lambda_expression = selector_tree.body[0].value
+        if not isinstance(selector_lambda_expression.body, Attribute):
+            raise Exception("The specified expression must be of type Attribute")
+        expression = ast.Call(func=ast.Attribute(value=self.expression, attr='order_by', ctx=ast.Load()), args=[selector_lambda_expression], keywords=[])
+        return self.provider.create_query(self.get_element_type(), expression)
+
+    def order_by_descending(self, selector: Callable[[T], Any]):
+        ''' Orders the sequence in a descending fashion using the specified attribute '''
+        selector_source = self._get_lambda_source_code(selector)
+        selector_tree = ast.parse(selector_source)
+        selector_lambda_expression = selector_tree.body[0].value
+        if not isinstance(selector_lambda_expression.body, Attribute):
+            raise Exception("The specified expression must be of type Attribute")
+        expression = ast.Call(func=ast.Attribute(value=self.expression, attr='order_by_descending', ctx=ast.Load()), args=[selector_lambda_expression], keywords=[])
+        return self.provider.create_query(self.get_element_type(), expression)
+
+    def select(self, selector: Callable[[T], Any]):
+        ''' Projects each element of a sequence into a new form '''
+        frame = inspect.currentframe().f_back
+        variables = {**frame.f_locals}
+        selector_source = self._get_lambda_source_code(selector)
+        selector_tree = ast.parse(selector_source)
+        selector_lambda_expression = selector_tree.body[0].value
+        if not isinstance(selector_lambda_expression.body, Attribute) and not isinstance(selector_lambda_expression.body, ast.List):
+            raise Exception("The specified expression must be of type Attribute or List[Attribute]")
+        expression = VariableExpressionReplacer(variables).visit(ast.Call(func=ast.Attribute(value=self.expression, attr='select', ctx=ast.Load()), args=[selector_lambda_expression], keywords=[]))
+        return self.provider.create_query(self.get_element_type(), expression)
+
+    def skip(self, amount: int):
+        ''' Bypasses a specified number of elements in a sequence and then returns the remaining elements. '''
+        expression = ast.Call(func=ast.Attribute(value=self.expression, attr='skip', ctx=ast.Load()), args=[ast.Constant(value=amount)], keywords=[])
+        return self.provider.create_query(self.get_element_type(), expression)
+
+    def take(self, amount: int):
+        ''' Selects a specified amount of contiguous elements from the start of a sequence '''
+        expression = ast.Call(func=ast.Attribute(value=self.expression, attr='take', ctx=ast.Load()), args=[ast.Constant(value=amount)], keywords=[])
+        return self.provider.create_query(self.get_element_type(), expression)
+
+    def where(self, predicate: Callable[[T], bool]) -> 'Queryable[T]':
+        ''' Filters a sequence of values based on a predicate. '''
+        frame = inspect.currentframe().f_back
+        frame_info = inspect.getframeinfo(frame)
+        variables = {**frame.f_locals}
+        lambda_src = self._get_lambda_source_code(predicate, frame_info.positions.end_col_offset)
+        lambda_tree = ast.parse(lambda_src)
+        lambda_expression = lambda_tree.body[0].value
+        expression = VariableExpressionReplacer(variables).visit(ast.Call(func=ast.Attribute(value=self.expression, attr='where', ctx=ast.Load()), args=[lambda_expression], keywords=[]))
+        return self.provider.create_query(self.get_element_type(), expression)
+
+    def to_list(self) -> List[T]:
+        ''' Executes the queryable '''
+        return self.provider.execute(self.expression, List)
+
+    def __str__(self) -> str: return ast.unparse(self.expression)
+
+    def _get_lambda_source_code(self, function: Callable, max_col_offset: int):
+        ''' Gets the source code of the specified lambda 
+
+            Args:
+                function (Callable): The lambda to get the source code of
+                max_col_offset (int): The maximum column offset to walk the AST tree for the target lamba
+
+            Notes:
+                Credits to https://gist.github.com/Xion/617c1496ff45f3673a5692c3b0e3f75a
+        '''
+        source_lines, _ = inspect.getsourcelines(function)
+        if len(source_lines) != 1:
+            return None
+        source_text = os.linesep.join(source_lines).strip()
+        source_ast = ast.parse(source_text)
+        lambda_node = next((node for node in ast.walk(source_ast) if isinstance(node, ast.Lambda) and node.col_offset <= max_col_offset), None)
+        if lambda_node is None:
+            return None
+        lambda_text = source_text[lambda_node.col_offset:lambda_node.end_col_offset]
+        return lambda_text
+
+
+class VariableExpressionReplacer(NodeTransformer):
+
+    def __init__(self, variables: Dict[str, Any]):
+        super().__init__()
+        self.variables = variables
+
+    variables: Dict[str, Any] = dict[str, Any]()
+
+    def visit_Name(self, node: Name) -> Any:
+        if not node.id in self.variables.keys():
+            return node
+        value = self.variables[node.id]
+        return ast.Constant(value)

neuroglia/dependency_injection/__init__.py

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

neuroglia/dependency_injection/service_provider.py

@@ -0,0 +1,341 @@
+from abc import ABC, abstractclassmethod
+from contextlib import contextmanager
+from enum import Enum
+import inspect
+from typing import Any, Callable, ForwardRef, List, Optional, Type, Dict, TypeVar
+
+from neuroglia.core.type_extensions import TypeExtensions
+
+
+class ServiceLifetime(Enum):
+    '''Enumerates all supported service lifetimes.'''
+
+    TRANSIENT = 'transient'
+    '''Transient services are created each time they are requested.'''
+
+    SCOPED = 'scoped'
+    '''Scoped services are created once per request within a scope (e.g., a web request).'''
+
+    SINGLETON = 'singleton'
+    '''Singleton services are created only once and reused for the entire application lifetime.'''
+
+
+ServiceDescriptor = ForwardRef("ServiceDescriptor")
+
+ServiceProvider = ForwardRef("ServiceProvider")
+
+ServiceScopeBase = ForwardRef("IServiceScope")
+
+
+class ServiceProviderBase(ABC):
+    ''' Defines the fundamentals of a container used to manage and provide instances of dependencies, enabling dependency injection to promote modularity and maintainability. '''
+
+    def get_service(self, type: Type) -> Optional[any]:
+        ''' Gets the service with the specified type, if any has been registered '''
+        raise NotImplementedError()
+
+    def get_required_service(self, type: Type) -> any:
+        ''' Gets the required service with the specified type '''
+        raise NotImplementedError()
+
+    def get_services(self, type: Type) -> List:
+        ''' Gets all services of the specified type '''
+        raise NotImplementedError()
+
+    def create_scope(self) -> ServiceScopeBase:
+        ''' Creates a new service scope '''
+        raise NotImplementedError()
+
+
+class ServiceScopeBase(ABC):
+    ''' Defines the fundamentals of a a limited context within which services are resolved and managed by a service provider, allowing for scoped instances and controlled lifetimes of dependencies. '''
+
+    @abstractclassmethod
+    def get_service_provider(self) -> ServiceProviderBase:
+        ''' Gets the scoped service provider '''
+        raise NotImplementedError()
+
+    @abstractclassmethod
+    def dispose(self):
+        ''' Disposes of the service scope '''
+        raise NotImplementedError()
+
+
+class ServiceScope(ServiceScopeBase, ServiceProviderBase):
+    ''' Represents the default implementation of the IServiceScope class '''
+
+    def __init__(self, root_service_provider: ServiceProviderBase, scoped_service_descriptors: List[ServiceDescriptor]):
+        self._root_service_provider = root_service_provider
+        self._scoped_service_descriptors = scoped_service_descriptors
+
+    _root_service_provider: ServiceProviderBase
+    ''' Gets the IServiceProvider that has created the service scope '''
+
+    _scoped_service_descriptors: List[ServiceDescriptor]
+    ''' Gets a list containing the configurations of all scoped dependencies '''
+
+    _realized_scoped_services: Dict[Type, List] = dict[Type, List]()
+    ''' Gets a type/list mapping containing all scoped services that have already been built/resolved '''
+
+    def get_service_provider(self) -> ServiceProviderBase: return self
+
+    def get_service(self, type: Type) -> Optional[any]:
+        if type == ServiceProviderBase:
+            return self
+        realized_services = self._realized_scoped_services.get(type)
+        realized_service = self._root_service_provider.get_service(type) if realized_services is None else realized_services[0]
+        if realized_service is not None:
+            return realized_service
+        descriptor = next(descriptor for descriptor in self._scoped_service_descriptors if descriptor.service_type == type)
+        if descriptor is None:
+            return None
+        return self._build_service(descriptor)
+
+    def get_required_service(self, type: Type) -> any:
+        service = self.get_service(type)
+        if service is None:
+            raise Exception(f"Failed to resolve service of type '{type.__name__}'")
+        return service
+
+    def get_services(self, type: Type) -> List:
+        if type == ServiceProviderBase:
+            return [self]
+        service_descriptors = [descriptor for descriptor in self._scoped_service_descriptors if descriptor.service_type == type]
+        realized_services = self._realized_scoped_services.get(type)
+        if realized_services is None:
+            realized_services = List()
+        for descriptor in service_descriptors:
+            if any(type(service) == descriptor.service_type for service in realized_services):
+                continue
+            realized_services.append(self._build_service(descriptor))
+        return realized_services + self._root_service_provider.get_services(type)
+
+    def _build_service(self, service_descriptor: ServiceDescriptor) -> any:
+        ''' Builds a new service provider based on the configured dependencies '''
+        if service_descriptor.lifetime == ServiceLifetime.SCOPED:
+            raise Exception(f"Failed to resolve scoped service of type '{service_descriptor.implementation_type}' from root service provider")
+        if service_descriptor.singleton is not None:
+            service = service_descriptor.singleton
+        elif service_descriptor.implementation_factory is not None:
+            service = service_descriptor.implementation_factory(self)
+        else:
+            init_args = [param for param in inspect.signature(service_descriptor.implementation_type.__init__).parameters.values() if param.name not in ['self', 'args', 'kwargs']]
+            args = dict[Type, any]()
+            for init_arg in init_args:
+                dependency = self.get_service(init_arg.annotation)
+                if dependency is None and init_arg.default == init_arg.empty and init_arg.name != 'self':
+                    raise Exception(f"Failed to build service of type '{service_descriptor.service_type.__name__}' because the service provider failed to resolve service '{init_arg.annotation}'")
+                args[init_arg.name] = dependency
+            service = service_descriptor.implementation_type(**args)
+        if service_descriptor.lifetime != ServiceLifetime.TRANSIENT:
+            realized_services = self._realized_scoped_services.get(service_descriptor.service_type)
+            if realized_services is None:
+                self._realized_scoped_services[service_descriptor.service_type] = {service}
+            else:
+                realized_services.append(service)
+        return service
+
+    def create_scope(self) -> ServiceScopeBase: return self
+
+    def dispose(self):
+        for service in self._realized_scoped_services:
+            service.__exit__()
+        self._realized_scoped_services = dict[Type, List]()
+
+
+class ServiceProvider(ServiceProviderBase):
+    ''' Represents the default implementation of the IServiceProvider class '''
+
+    def __init__(self, service_descriptors: List[ServiceDescriptor]):
+        ''' Initializes a new service provider using the specified service dependency configuration '''
+        self._service_descriptors = service_descriptors
+
+    _service_descriptors: List[ServiceDescriptor]
+    ''' Gets a list containing the configuration of all registered dependencies '''
+
+    _realized_services: Dict[Type, List] = dict[Type, List]()
+    ''' Gets a type/list mapping containing all services that have already been built/resolved '''
+
+    def get_service(self, type: Type) -> Optional[any]:
+        if type == ServiceProviderBase:
+            return self
+        realized_services = self._realized_services.get(type)
+        if realized_services is not None:
+            return realized_services[0]
+        if len(self._service_descriptors) < 1:
+            return None
+        descriptor = next((descriptor for descriptor in self._service_descriptors if descriptor.service_type == type), None)
+        if descriptor is None:
+            return None
+        return self._build_service(descriptor)
+
+    def get_required_service(self, type: Type) -> any:
+        service = self.get_service(type)
+        if service is None:
+            raise Exception(f"Failed to resolve service of type '{type.__name__}'")
+        return service
+
+    def get_services(self, type: Type) -> List:
+        if type == ServiceProviderBase:
+            return [self]
+        service_descriptors = [descriptor for descriptor in self._service_descriptors if descriptor.service_type == type]
+        realized_services = self._realized_services.get(type)
+        if realized_services is None:
+            realized_services = list()
+        for descriptor in service_descriptors:
+            implementation_type = descriptor.get_implementation_type()
+            realized_service = next((service for service in realized_services if self._is_service_instance_of(service, implementation_type)), None)
+            if realized_service is None:
+                realized_services.append(self._build_service(descriptor))
+        return realized_services
+
+    def _is_service_instance_of(self, service: Any, type_: Type) -> bool:
+        if hasattr(type_, "__origin__"):
+            service_type = service.__orig_class__ if hasattr(service, "__orig_class__") else type(service)
+            service_generic_arguments = TypeExtensions.get_generic_arguments(service_type)
+            implementation_generic_arguments = TypeExtensions.get_generic_arguments(type_)
+            for i in range(len(implementation_generic_arguments)):
+                generic_argument_name = list(implementation_generic_arguments.keys())[i]
+                service_generic_argument = service_generic_arguments.get(generic_argument_name, None)
+                if service_generic_argument is None or service_generic_argument != implementation_generic_arguments[generic_argument_name]:
+                    return False
+            return isinstance(service, type_.__origin__)
+        else:
+            return isinstance(service, type_)
+
+    def _build_service(self, service_descriptor: ServiceDescriptor) -> any:
+        ''' Builds a new service provider based on the configured dependencies '''
+        if service_descriptor.lifetime == ServiceLifetime.SCOPED:
+            raise Exception(f"Failed to resolve scoped service of type '{service_descriptor.implementation_type}' from root service provider")
+        if service_descriptor.singleton is not None:
+            service = service_descriptor.singleton
+        elif service_descriptor.implementation_factory is not None:
+            service = service_descriptor.implementation_factory(self)
+        else:
+            is_service_generic = not inspect.isclass(service_descriptor.implementation_type)  # if implementation_type is not a class, then it must be a generic type
+            service_generic_type = service_descriptor.implementation_type.__origin__ if is_service_generic else None  # retrieve the generic type, used to determine the __init__ args
+            service_type = service_descriptor.implementation_type if service_generic_type is None else service_generic_type  # get the type used to determine the __init__ args: the implementation type as is or its generic type definition
+            service_init_args = [param for param in inspect.signature(service_type.__init__).parameters.values() if param.name not in ['self', 'args', 'kwargs']]  # gets the __init__ args and leave out self, args and kwargs
+            service_generic_args = TypeExtensions.get_generic_arguments(service_descriptor.implementation_type)  # gets the generic args: we will need them to substitute the type args of potential generic dependencies
+            service_args = dict[Type, any]()
+            for init_arg in service_init_args:
+                is_dependency_generic = not inspect.isclass(init_arg.annotation)
+                dependency_generic_type = init_arg.annotation.__origin__ if is_dependency_generic else None
+                dependency_generic_args = None if dependency_generic_type is None else init_arg.annotation.__args__
+                if dependency_generic_args is not None:
+                    dependency_generic_args = [service_generic_args[arg.__name__] if type(arg) == TypeVar else arg for arg in dependency_generic_args]  # replace TypeVar generic arguments by the service's matching generic argument
+                dependency_type = init_arg.annotation.__origin__[*dependency_generic_args] if is_dependency_generic else init_arg.annotation
+                dependency = self.get_service(dependency_type)
+                if dependency is None and init_arg.default == init_arg.empty and init_arg.name != 'self':
+                    raise Exception(f"Failed to build service of type '{service_descriptor.service_type.__name__}' because the service provider failed to resolve service '{dependency_type.__name__}'")
+                service_args[init_arg.name] = dependency
+            service = service_descriptor.implementation_type(**service_args)
+        if service_descriptor.lifetime != ServiceLifetime.TRANSIENT:
+            realized_services = self._realized_services.get(service_descriptor.service_type)
+            if realized_services is None:
+                self._realized_services[service_descriptor.service_type] = [service]
+            else:
+                realized_services.append(service)
+        return service
+
+    @contextmanager
+    def create_scope(self) -> ServiceScopeBase:
+        service_scope = ServiceScope(self, [descriptor for descriptor in self._service_descriptors if descriptor.lifetime == ServiceLifetime.SCOPED])
+        try:
+            yield service_scope
+        finally:
+            service_scope.dispose()
+
+    def dispose(self):
+        for service in self._realized_services:
+            try:
+                service.__exit__()
+            except:
+                pass
+        self._realized_services = dict[Type, List]()
+
+
+class ServiceDescriptor:
+    ''' Represents an object used to describe and configure a service dependency '''
+
+    def __init__(self, service_type: Type, implementation_type: Optional[Type] = None, singleton: any = None, implementation_factory: Callable[[ServiceProvider], any] = None, lifetime: ServiceLifetime = ServiceLifetime.SINGLETON):
+        ''' Initializes a new service descriptor '''
+        if singleton is not None and lifetime != ServiceLifetime.SINGLETON:
+            raise Exception("A singleton service dependency must have lifetime set to 'SINGLETON'")
+        self.service_type = service_type
+        self.implementation_type = implementation_type
+        self.singleton = singleton
+        self.implementation_factory = implementation_factory
+        self.lifetime = lifetime
+        if self.singleton is None and self.implementation_factory is None and self.implementation_type is None:
+            self.implementation_type = self.service_type
+
+    service_type: Type
+    ''' Gets the type of the service dependency '''
+
+    implementation_type: Optional[Type]
+    ''' Gets the service dependency's implementation/concretion type, if any, to be instanciated on demand by a service provider. If set, 'singleton' and 'implementation-factory' are ignored. '''
+
+    singleton: any
+    ''' Gets the service instance singleton, if any. If set, 'implementation_type' and 'implementation-factory' are ignored. '''
+
+    implementation_factory: Callable[[ServiceProvider], any]
+    ''' Gets a function, if any, use to create a new instance of the service dependency. If set, 'implementation_type' and 'singleton' are ignored. '''
+
+    lifetime: ServiceLifetime = ServiceLifetime.SINGLETON
+    ''' Gets the service's lifetime. Defaults to 'SINGLETON' '''
+
+    def get_implementation_type(self) -> Type:
+        ''' Gets the service's implementation type '''
+        if self.implementation_type is not None:
+            return self.implementation_type
+        return_type = inspect.signature(self.implementation_factory).return_annotation if self.implementation_factory != None else None
+        if return_type is None and self.implementation_factory != None:
+            if self.implementation_type is None:
+                raise Exception(f"Failed to determine the return type of the implementation factory configured for service of type '{self.service_type.__name__}'. Either specify the implementation type, or use a function instead of a lambda as factory callable.")
+            else:
+                return_type = self.implementation_type
+        return type(self.singleton) if self.singleton is not None else inspect.signature(self.implementation_factory).return_annotation
+
+
+ServiceCollection = ForwardRef("ServiceCollection")
+
+
+class ServiceCollection(List[ServiceDescriptor]):
+    ''' Represents a collection of service descriptors used to configure a service provider '''
+
+    def add_singleton(self, service_type: Type, implementation_type: Optional[Type] = None, singleton: any = None, implementation_factory: Callable[[ServiceProvider], any] = None) -> ServiceCollection:
+        ''' Registers a new singleton service dependency '''
+        self.append(ServiceDescriptor(service_type, implementation_type, singleton, implementation_factory, ServiceLifetime.SINGLETON))
+        return self
+
+    def try_add_singleton(self, service_type: Type, implementation_type: Optional[Type] = None, singleton: any = None, implementation_factory: Callable[[ServiceProvider], any] = None) -> ServiceCollection:
+        ''' Attempts to register a new singleton service dependency, if one has not already been registered'''
+        if any(descriptor.service_type == service_type for descriptor in self):
+            return self
+        return self.add_singleton(service_type, implementation_type, singleton, implementation_factory)
+
+    def add_transient(self, service_type: Type, implementation_type: Optional[Type] = None, implementation_factory: Callable[[ServiceProvider], any] = None) -> ServiceCollection:
+        ''' Registers a new transient service dependency '''
+        self.append(ServiceDescriptor(service_type, implementation_type, None, implementation_factory, ServiceLifetime.SINGLETON))
+        return self
+
+    def try_add_transient(self, service_type: Type, implementation_type: Optional[Type] = None, implementation_factory: Callable[[ServiceProvider], any] = None) -> ServiceCollection:
+        ''' Attempts to register a new transient service dependency, if one has not already been registered'''
+        if any(descriptor.service_type == service_type for descriptor in self):
+            return self
+        return self.add_transient(service_type, implementation_type, implementation_factory)
+
+    def add_scoped(self, service_type: Type, implementation_type: Optional[Type] = None, implementation_factory: Callable[[ServiceProvider], any] = None) -> ServiceCollection:
+        ''' Registers a new scoped service dependency '''
+        self.append(ServiceDescriptor(service_type, implementation_type, None, implementation_factory, ServiceLifetime.SINGLETON))
+        return self
+
+    def try_add_scoped(self, service_type: Type, implementation_type: Optional[Type] = None, implementation_factory: Callable[[ServiceProvider], any] = None) -> ServiceCollection:
+        ''' Attempts to register a new scoped service dependency, if one has not already been registered'''
+        if any(descriptor.service_type == service_type for descriptor in self):
+            return self
+        return self.add_scoped(service_type, implementation_type, implementation_factory)
+
+    def build(self) -> ServiceProviderBase:
+        return ServiceProvider(self)

neuroglia/eventing/cloud_events/__init__.py

@@ -0,0 +1 @@
+from .cloud_event import CloudEvent as CloudEvent

neuroglia/eventing/cloud_events/cloud_event.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Optional
+
+
+class CloudEventSpecVersion:
+    ''' Exposes all supported versions of the Cloud Event Specification '''
+
+    v1_0: str = "1.0"
+    ''' Gets the version '1.0' of the Cloud Event Specification '''
+
+
+@dataclass
+class CloudEvent:
+    '''
+    Represents a Cloud Event.
+
+    Attributes:
+        id (str): A string that uniquely identifies the cloud event in the scope of its source.
+        specversion (str): The version of the CloudEvents specification which the event uses. Defaults to '1.0'.
+        time (Optional[datetime]): The date and time at which the event has been produced.
+        source (str): The cloud event's source.
+        type (str): The cloud event's type.
+        subject (Optional[str]): A value that describes the subject of the event in the context of the event producer.
+        datacontenttype (Optional[str]): The cloud event's data content type. Defaults to 'application/json'.
+        dataschema (Optional[str]): An URI that references the versioned schema of the event's data.
+        data (Optional[Any]): The event's data, if any. Only used if the event has been formatted using the structured mode.
+        data_base64 (Optional[str]): The event's binary data, encoded in base 64. Used if the event has been formatted using the binary mode.
+        extensionAttributes (Optional[Dict[str, Any]]): A mapping containing the event's extension attributes.
+    '''
+
+    id: str
+    ''' Gets/sets string that uniquely identifies the cloud event in the scope of its source. '''
+
+    source: str
+    ''' Gets/sets the cloud event's source. Must be an absolute URI. '''
+
+    type: str
+    ''' Gets/sets the cloud event's source. Should be a reverse DNS domain name, which must only contain lowercase alphanumeric, '-' and '.' characters. '''
+
+    specversion: str = '1.0'  # Default value for specversion
+    ''' Gets/sets the version of the CloudEvents specification which the event uses. Defaults to '1.0'. '''
+
+    sequencetype: Optional[str] = None
+    ''' Gets/sets the type of the sequence. '''
+
+    sequence: Optional[int] = None
+    ''' Gets/sets the sequence of the event. '''
+
+    time: Optional[datetime] = None
+    ''' Gets/sets the date and time at which the event has been produced. '''
+
+    subject: Optional[str] = None
+    ''' Gets/sets value that describes the subject of the event in the context of the event producer. '''
+
+    datacontenttype: Optional[str] = 'application/json'  # Default value for datacontenttype
+    ''' Gets/sets the cloud event's data content type. Defaults to 'application/json'. '''
+
+    dataschema: Optional[str] = None
+    ''' Gets/sets an URI, if any, that references the versioned schema of the event's data. '''
+
+    data: Optional[Any] = None
+    ''' Gets/sets the event's data, if any. Only used if the event has been formatted using the structured mode. '''
+
+    data_base64: Optional[str] = None
+    ''' Gets/sets the event's binary data, encoded in base 64. Used if the event has been formatted using the binary mode. '''
+
+    def get_attribute(self, name: str) -> Optional[Any]:
+        ''' Gets the value of the attribute with the specified name, if any '''
+        if not name:
+            raise ValueError("Attribute name cannot be empty or None.")
+        self.__dict__[name] if name in self.__dict__.keys() else None

neuroglia/eventing/cloud_events/decorators.py

@@ -0,0 +1,5 @@
+def cloudevent(cloud_event_type: str):
+    def decorator(cls):
+        cls.__cloudevent__type__ = cloud_event_type
+        return cls
+    return decorator

neuroglia/eventing/cloud_events/infrastructure/__init__.py

@@ -0,0 +1,4 @@
+from .cloud_event_bus import CloudEventBus
+from .cloud_event_ingestor import CloudEventIngestor
+from .cloud_event_middleware import CloudEventMiddleware
+from .cloud_event_publisher import CloudEventPublisher

neuroglia/eventing/cloud_events/infrastructure/cloud_event_bus.py

@@ -0,0 +1,11 @@
+from rx.subject import Subject
+
+
+class CloudEventBus:
+    ''' Defines the fundamentals of a service used to manage incoming and outgoing streams of cloud events '''
+
+    input_stream: Subject = Subject()
+    ''' Gets the stream of events ingested by the application '''
+
+    output_stream: Subject = Subject()
+    ''' Gets the stream of events published by the application '''