neuroglia-python 0.0.23__py3-none-any.whl

neuroglia/core/__init__.py

@@ -0,0 +1,4 @@
+from .module_loader import *
+from .operation_result import *
+from .type_finder import *
+from .type_extensions import *

neuroglia/core/module_loader.py

@@ -0,0 +1,13 @@
+import importlib
+import sys
+from types import ModuleType
+
+
+class ModuleLoader:
+
+    @staticmethod
+    def load(module_name: str) -> ModuleType:
+        module = sys.modules.get(module_name, None)
+        if module is None:
+            module = importlib.import_module(module_name)
+        return module

neuroglia/core/operation_result.py

@@ -0,0 +1,11 @@
+from typing import Generic, Optional, TypeVar
+from neuroglia.core.problem_details import ProblemDetails
+
+TData = TypeVar('TData')
+
+
+class OperationResult(Generic[TData], ProblemDetails):
+    ''' Represents the result of an operation '''
+
+    data: Optional[TData]
+    ''' Gets the data, if any, returned by the operation in case of success '''

neuroglia/core/problem_details.py

@@ -0,0 +1,25 @@
+import dataclasses
+from typing import Optional
+
+
+@dataclasses.dataclass
+class ProblemDetails:
+    '''Represents the structure of a Problem Details response (RFC 7807).'''
+
+    title: str
+    '''A short, human-readable summary of the problem.'''
+
+    status: int
+    '''The HTTP status code for this occurrence of the problem.'''
+
+    detail: Optional[str] = None
+    '''A human-readable explanation specific to this occurrence of the problem.'''
+
+    type: Optional[str] = None
+    '''A URI reference that identifies the problem type.'''
+
+    instance: Optional[str] = None
+    '''A URI reference that identifies the specific occurrence of the problem.'''
+    
+    def is_success_status_code(self) -> bool: self.status >= 200 and self.status < 300
+    ''' Determines whether the operation is successfull or not '''

neuroglia/core/type_extensions.py

@@ -0,0 +1,75 @@
+from typing import Dict, List, Type, TypeVar
+
+
+class TypeExtensions:
+
+    @staticmethod
+    def get_generic_implementation(type_: Type, generic_type_definition: Type, generic_args: Dict[str, Type] = None):
+        base_types = TypeExtensions._get_base_types(type_)
+        base_types = [base for base in base_types if (issubclass(base.__origin__, generic_type_definition) if hasattr(base, "__origin__") else issubclass(base, generic_type_definition))]
+        base_type = next((base for base in base_types if base == generic_type_definition or (hasattr(base, "__origin__")) and base.__origin__ == generic_type_definition), None)
+        if hasattr(type_, "__orig_class__") and hasattr(type_.__orig_class__.__origin__, "__parameters__"):
+            if generic_args is None:
+                generic_args = dict[str, Type]()
+            for i in range(len(type_.__orig_class__.__origin__.__parameters__)):
+                name = type_.__orig_class__.__origin__.__parameters__[i].__name__
+                arg_type = type_.__orig_class__.__args__[i]
+                generic_args[name] = arg_type
+        if (hasattr(type_, "__origin__") and hasattr(type_.__origin__, "__parameters__")):
+            if generic_args is None:
+                generic_args = dict[str, Type]()
+            for i in range(len(type_.__origin__.__parameters__)):
+                name = type_.__origin__.__parameters__[i].__name__
+                arg_type = type_.__args__[i]
+                generic_args[name] = arg_type
+        if base_type is not None:
+            return TypeExtensions._substitute_generic_arguments(base_type, generic_args)
+        else:
+            return next((implementation_type for implementation_type in [TypeExtensions.get_generic_implementation(base, generic_type_definition, generic_args) for base in base_types]), None)
+
+    @staticmethod
+    def get_generic_arguments(type_: Type, generic_arguments: Dict[str, Type] = None) -> Dict[str, Type]:
+        if hasattr(type_, "__orig_class__") and hasattr(type_.__orig_class__.__origin__, "__parameters__"):
+            if generic_arguments is None:
+                generic_arguments = dict[str, Type]()
+            for i in range(len(type_.__orig_class__.__origin__.__parameters__)):
+                name = type_.__orig_class__.__origin__.__parameters__[i].__name__
+                arg_type = type_.__orig_class__.__args__[i]
+                generic_arguments[name] = TypeExtensions._substitute_generic_arguments(arg_type, generic_arguments)
+        if (hasattr(type_, "__origin__") and hasattr(type_.__origin__, "__parameters__")):
+            if generic_arguments is None:
+                generic_arguments = dict[str, Type]()
+            for i in range(len(type_.__origin__.__parameters__)):
+                name = type_.__origin__.__parameters__[i].__name__
+                arg_type = type_.__args__[i]
+                generic_arguments[name] = TypeExtensions._substitute_generic_arguments(arg_type, generic_arguments)
+        for base_type in TypeExtensions._get_base_types(type_):
+            generic_arguments = TypeExtensions.get_generic_arguments(base_type, generic_arguments)
+        return generic_arguments
+
+    @staticmethod
+    def get_generic_argument(type_: Type, name: str) -> Type | None:
+        generic_arguments = TypeExtensions.get_generic_arguments(type_)
+        return generic_arguments.get(name, None)
+
+    @staticmethod
+    def _get_base_types(type_: Type) -> List[Type]:
+        if hasattr(type_, "__origin__") and hasattr(type_.__origin__, "__orig_bases__"):
+            return type_.__origin__.__orig_bases__
+        elif hasattr(type_, "__orig_bases__"):
+            return type_.__orig_bases__
+        else:
+            return list[Type]()
+
+    @staticmethod
+    def _substitute_generic_arguments(type_: Type, generic_args: Dict[str, Type] | None = None) -> Type:
+        if not hasattr(type_, "__parameters__") and generic_args is not None:
+            if isinstance(type_, TypeVar):
+                return generic_args.get(type_.__name__, None)
+            else:
+                return type_
+        parameters = [param.__name__ for param in type_.__parameters__]
+        type_args = [TypeExtensions._substitute_generic_arguments(generic_arg_value, generic_args) for generic_arg_key, generic_arg_value in generic_args.items() if generic_arg_key in parameters]
+        if len(type_args) < 1:
+            return type_
+        return type_[*type_args]

neuroglia/core/type_finder.py

@@ -0,0 +1,24 @@
+import importlib
+import inspect
+import pkgutil
+from types import ModuleType
+from typing import Callable, List, Type
+
+
+class TypeFinder:
+    ''' Represents an utility class that exposes methods to find and filter types '''
+
+    def get_types(module: ModuleType, predicate: Callable[[Type], bool] = lambda t: True, include_sub_modules=True, include_sub_packages=False) -> List[Type]:
+        ''' Recursively finds all types contained in the specified module that match the specified predicate, if any '''
+        results: List[Type] = list[Type]()
+        results.extend([cls for _, cls in inspect.getmembers(module, inspect.isclass) if predicate(cls)])
+        if include_sub_modules:
+            for submodule in [submodule for _, submodule in inspect.getmembers(module, inspect.ismodule) if submodule.__name__.startswith(module.__name__)]:
+                results.extend(TypeFinder.get_types(submodule, predicate, include_sub_modules, include_sub_packages))
+        # todo: the following creates big problems, as it will actually (re)load, thus (re)run, imported packages <= it sucks
+        if include_sub_packages:
+            if hasattr(module, "__path__"):
+                sub_packages = [importlib.import_module(module_name) for _, module_name, _ in pkgutil.walk_packages(module.__path__, module.__name__ + ".") if module_name.startswith(module.__name__)]
+                for submodule in sub_packages:
+                    results.extend(TypeFinder.get_types(submodule, predicate, include_sub_modules, include_sub_packages))
+        return list(set(results))

neuroglia/data/__init__.py

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

neuroglia/data/abstractions.py

@@ -0,0 +1,124 @@
+from abc import ABC
+from datetime import datetime
+from typing import Generic, List, Type, TypeVar
+
+TKey = TypeVar("TKey")
+''' Represents the generic argument used to specify the type of key to use '''
+
+
+class Identifiable(Generic[TKey], ABC):
+    ''' Defines the fundamentals of an object that can be identified based on a unique identifier '''
+
+    id: TKey
+    ''' Gets the object's unique identifier '''
+
+
+TEntity = TypeVar("TEntity", bound=Identifiable)
+''' Represents the generic argument used to specify the type of entity to use '''
+
+
+class Entity(Generic[TKey], Identifiable[TKey], ABC):
+    ''' Represents the abstract class inherited by all entities in the application '''
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.created_at = datetime.now()
+
+    created_at: datetime
+    ''' Gets the date and time the entity has been created at '''
+
+    last_modified: datetime
+    ''' Gets the date and time the entity was last modified at, if any '''
+
+
+class VersionedState(ABC):
+    ''' Represents the abstract class inherited by all versioned states '''
+
+    def __init__(self):
+        self.state_version = 0
+
+    state_version: int = 0
+    ''' Gets the state's version '''
+
+
+class AggregateState(Generic[TKey], Identifiable[TKey], VersionedState, ABC):
+    ''' Represents the abstract class inherited by all aggregate root states '''
+
+    def __init__(self):
+        super().__init__()
+
+    id: TKey
+    ''' Gets the id of the aggregate the state belongs to '''
+
+    created_at: datetime
+    ''' Gets the date and time the aggregate has been created at '''
+
+    last_modified: datetime
+    ''' Gets the date and time, if any, the aggregate was last modified at '''
+
+
+TState = TypeVar("TState", bound=AggregateState)
+''' Represents the generic argument used to specify the state of an aggregate root '''
+
+
+class DomainEvent(Generic[TKey], ABC):
+    ''' Represents the base class inherited by all domain events '''
+
+    def __init__(self, aggregate_id: TKey):
+        ''' Initializes a new domain event '''
+        self.created_at = datetime.now()
+        self.aggregate_id = aggregate_id
+
+    created_at: datetime
+    ''' Gets the date and time the domain event has been created at '''
+
+    aggregate_id: TKey
+    ''' Gets the id of the aggregate that has produced the domain event '''
+
+    aggregate_version: int
+    ''' Gets the version of the aggregate's state, after reducing the domain event '''
+
+
+TEvent = TypeVar("TEvent", bound=DomainEvent)
+''' Represents the generic argument used to specify the state of an aggregate root '''
+
+
+class AggregateRoot(Generic[TState, TKey], Entity[TKey], ABC):
+    ''' Represents the base class for all aggregate roots '''
+
+    _pending_events: List[DomainEvent]
+    ''' Gets a list containing all domain events pending persistence '''
+
+    def __init__(self):
+        ''' Initializes a new aggregate root '''
+        self.state = object.__new__(self.__orig_bases__[0].__args__[0])
+        self.state.__init__()
+        self._pending_events = list[DomainEvent]()
+
+    def id(self):
+        ''' Gets the aggregate root's id '''
+        return self.state.id
+
+    state: TState
+    ''' Gets the aggregate root's state '''
+
+    def register_event(self, e: TEvent) -> TEvent:
+        ''' Registers the specified domain event '''
+        if not hasattr(self, "_pending_events"):
+            self._pending_events = list[DomainEvent]()
+        self._pending_events.append(e)
+        e.aggregate_version = self.state.state_version + len(self._pending_events)
+        return e
+
+    def clear_pending_events(self):
+        ''' Clears all pending domain events '''
+        self._pending_events.clear()
+
+
+TAggregate = TypeVar("TAggregate", bound=AggregateRoot)
+''' Represents the generic argument used to specify an aggregate root type '''
+
+
+def queryable(cls):
+    cls.__queryable__ = True
+    return cls

neuroglia/data/infrastructure/abstractions.py

@@ -0,0 +1,78 @@
+from abc import ABC, abstractmethod
+from typing import Generic, List, Optional
+from neuroglia.data.abstractions import TEntity, TKey
+from neuroglia.data.queryable import Queryable
+
+
+class Repository(Generic[TEntity, TKey], ABC):
+    ''' Defines the fundamentals of a repository '''
+
+    @abstractmethod
+    async def contains_async(self, id: TKey) -> bool:
+        ''' Determines whether or not the repository contains an entity with the specified id '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def get_async(self, id: TKey) -> Optional[TEntity]:
+        ''' Gets the entity with the specified id, if any '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def add_async(self, entity: TEntity) -> TEntity:
+        ''' Adds the specified entity '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def update_async(self, entity: TEntity) -> TEntity:
+        ''' Persists the changes that were made to the specified entity '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def remove_async(self, id: TKey) -> None:
+        ''' Removes the entity with the specified key '''
+        raise NotImplementedError()
+
+
+class QueryableRepository(Generic[TEntity, TKey], Repository[TEntity, TKey], ABC):
+    ''' Defines the fundamentals of a queryable repository '''
+
+    @abstractmethod
+    async def query_async(self) -> Queryable[TEntity]:
+        raise NotImplementedError()
+
+
+class FlexibleRepository(Generic[TEntity, TKey], Repository[TEntity, TKey], ABC):
+    ''' Defines the fundamentals of a flexible repository '''
+
+    @abstractmethod
+    async def set_database(self, database: str) -> None:
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def get_database(self) -> str:
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def contains_by_collection_name_async(self, collection_nam: str, id: TKey) -> bool:
+        ''' Determines whether or not the repository contains an entity with the specified id '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def get_by_collection_name_async(self, collection_name: str, id: TKey) -> Optional[TEntity]:
+        ''' Gets the entity with the specified id, if any '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def add_by_collection_name_async(self, collection_name: str, entity: TEntity) -> TEntity:
+        ''' Adds the specified entity '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def update_by_collection_name_async(self, collection_name: str, entity: TEntity) -> TEntity:
+        ''' Persists the changes that were made to the specified entity '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def remove_by_collection_name_async(self, collection_name: str, id: TKey) -> None:
+        ''' Removes the entity with the specified key '''
+        raise NotImplementedError()

neuroglia/data/infrastructure/event_sourcing/abstractions.py

@@ -0,0 +1,126 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, List, Optional, Type
+from neuroglia.data.abstractions import AggregateRoot
+
+
+@dataclass
+class StreamDescriptor:
+    ''' Represents a class used to describe a stream of recorded events '''
+
+    id: str
+    ''' Gets the stream's id '''
+
+    length: int
+    ''' Gets the stream's length '''
+
+    first_event_at: Optional[datetime] = None
+    ''' Gets the date and time at which the first event, if any, has been recorded to the stream '''
+
+    last_event_at: Optional[datetime] = None
+    ''' Gets the date and time at which the last event, if any, has been recorded to the stream '''
+
+
+@dataclass
+class EventDescriptor:
+    ''' Represents a class used to describe an event to record '''
+
+    type: str
+    ''' Gets the type of the event to record '''
+
+    data: Optional[Any] = None
+    ''' Gets the data of the event to record '''
+
+    metadata: Optional[Any] = None
+    ''' Gets the metadata of the event to record, if any '''
+
+
+@dataclass
+class EventRecord:
+    ''' Represents a recorded event '''
+
+    stream_id: str
+    ''' Gets the id of the stream the recorded event belongs to '''
+
+    id: str
+    ''' Gets the id of the recorded event '''
+
+    offset: int
+    ''' Gets the offset of the recorded event in the stream it belongs to '''
+
+    position: int
+    ''' Gets the position of the recorded event in the global stream '''
+
+    timestamp: datetime
+    ''' Gets the date and time at which the event has been recorded '''
+
+    type: str
+    ''' Gets the type of the recorded event. Should be a non-versioned reverse uri made out alphanumeric, '-' and '.' characters '''
+
+    data: Optional[any] = None
+    ''' Gets the recorded event's data, if any '''
+
+    metadata: Optional[any] = None
+    ''' Gets the recorded event's metadadata, if any '''
+
+    replayed: bool = False
+    ''' Gets a boolean indicating whether or not the recorded event is being replayed to its consumer/consumer group '''
+
+
+class StreamReadDirection(Enum):
+    ''' Enumerates all directions in which a event sourcing stream can be read '''
+    FORWARDS = 0,
+    ''' Indicates a forwards direction '''
+    BACKWARDS = 1
+    ''' Indicates a backwards direction '''
+
+
+@dataclass
+class EventStoreOptions:
+
+    database_name: str
+    ''' Gets/sets the name of the database to use, if any '''
+
+
+class EventStore(ABC):
+    ''' Defines the fundamentals of a service used to append and subscribe to sourced events '''
+
+    @abstractmethod
+    async def contains_async(self, stream_id: str) -> bool:
+        ''' Determines whether or not the event store contains a stream with the specified id '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def append_async(self, streamId: str, events: List[EventDescriptor], expectedVersion: Optional[int] = None):
+        ''' Appends a list of events to the specified stream '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def get_async(self, stream_id: str):
+        ''' Gets information about the specified stream '''
+        raise NotImplementedError()
+
+    @abstractmethod
+    async def read_async(self, stream_id: str, read_direction: StreamReadDirection, offset: int, length: Optional[int] = None) -> List[EventRecord]:
+        ''' Reads recorded events from the specified stream '''
+        raise NotImplementedError()
+
+    async def observe_async(self, stream_id: Optional[str], consumer_group: Optional[str] = None, offset: Optional[int] = None):
+        ''' 
+        Creates a new observable used to stream events published by the event store.
+        Typically, this is used by some kind of reconciliation mechanism to consume domain events then publish them to their related handlers, if any.
+        '''
+        raise NotImplementedError()
+
+
+class Aggregator:
+
+    def aggregate(self, events: List, aggregate_type: Type):
+        aggregate: AggregateRoot = object.__new__(aggregate_type)
+        aggregate.state = aggregate.__orig_bases__[0].__args__[0]()
+        for e in events:
+            aggregate.state.on(e.data)
+            aggregate.state.state_version = e.data.aggregate_version
+        return aggregate

neuroglia/data/infrastructure/event_sourcing/event_sourcing_repository.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+from typing import Generic, Optional, Type
+from neuroglia.data.infrastructure.abstractions import Repository
+from neuroglia.data.abstractions import DomainEvent, TAggregate, TKey
+from neuroglia.data.infrastructure.event_sourcing.abstractions import Aggregator, EventDescriptor, EventStore, StreamReadDirection
+from neuroglia.hosting.abstractions import ApplicationBuilderBase
+
+
+@dataclass
+class EventSourcingRepositoryOptions(Generic[TAggregate, TKey]):
+    ''' Represents the options used to configure an event sourcing repository '''
+    pass
+
+
+class EventSourcingRepository(Generic[TAggregate, TKey], Repository[TAggregate, TKey]):
+    ''' Represents an event sourcing repository implementation '''
+
+    def __init__(self, eventstore: EventStore, aggregator: Aggregator):
+        ''' Initialize a new event sourcing repository '''
+        self._eventstore = eventstore
+        self._aggregator = aggregator
+    
+    _eventstore : EventStore
+    ''' Gets the underlying event store '''
+    
+    _aggregator : Aggregator
+    ''' Gets the underlying event store '''
+
+    async def contains_async(self, id: TKey) -> bool: return self._eventstore.contains_stream(self._build_stream_id_for(id))
+
+    async def get_async(self, id: TKey) -> Optional[TAggregate]:
+        ''' Gets the aggregate with the specified id, if any '''
+        stream_id = self._build_stream_id_for(id)
+        events = await self._eventstore.read_async(stream_id, StreamReadDirection.FORWARDS, 0)
+        return self._aggregator.aggregate(events, self.__orig_class__.__args__[0])
+        
+    async def add_async(self, aggregate: TAggregate) -> TAggregate:
+        ''' Adds and persists the specified aggregate '''
+        stream_id = self._build_stream_id_for(aggregate.id())
+        events = aggregate._pending_events
+        if len(events) < 1 : raise Exception()
+        encoded_events = [self._encode_event(e) for e in events] 
+        await self._eventstore.append_async(stream_id, encoded_events)
+        aggregate.state.state_version = events[-1].aggregate_version
+        aggregate.clear_pending_events()
+        return aggregate
+        
+    async def update_async(self, aggregate: TAggregate) -> TAggregate:
+        ''' Perists the changes made to the specified aggregate '''
+        stream_id = self._build_stream_id_for(aggregate.id())
+        events = aggregate._pending_events
+        if len(events) < 1 : raise Exception()
+        encoded_events = [self._encode_event(e) for e in events] 
+        await self._eventstore.append_async(stream_id, encoded_events, aggregate.state.state_version)
+        aggregate.state.state_version = events[-1].aggregate_version
+        aggregate.clear_pending_events()
+        return aggregate
+
+    async def remove_async(self, id: TKey) -> None:
+        ''' Removes the aggregate root with the specified key, if any '''
+        raise NotImplementedError()
+
+    def _build_stream_id_for(self, aggregate_id : TKey):
+        ''' Builds a new stream id for the specified aggregate '''
+        aggregate_name = self.__orig_class__.__args__[0].__name__
+        return f"{aggregate_name.lower()}-{aggregate_id}"
+    
+    def _encode_event(self, e: DomainEvent):
+        ''' Encodes a domain event into a new event descriptor '''
+        event_type = type(e).__name__.lower()
+        return EventDescriptor(event_type, e)
+    
+    def configure(builder: ApplicationBuilderBase, entity_type : Type, key_type : Type) -> ApplicationBuilderBase:
+        ''' Configures the specified application to use an event sourcing based repository implementation to manage the specified type of entity '''
+        builder.services.try_add_singleton(EventSourcingRepositoryOptions[entity_type, key_type], singleton= EventSourcingRepositoryOptions[entity_type, key_type]())
+        builder.services.try_add_singleton(Repository[entity_type, key_type], EventSourcingRepository[entity_type, key_type])
+        return builder