hexcore 1.7.0__tar.gz → 1.8.0__tar.gz

hexcore-1.8.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include hexcore *.pyi py.typed

{hexcore-1.7.0 → hexcore-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 1.7.0
+Version: 1.8.0
 Summary: Núcleo reutilizable para proyectos Python con arquitectura hexagonal y event handling. Provee abstracciones, utilidades y contratos para DDD, eventos y desacoplamiento de infraestructura.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT
@@ -49,6 +49,57 @@ Este repositorio cuenta con un conjunto de skills adicionales para extender y pe
 pip install hexcore
 ```
 
+## Templates de Proyecto (CLI)
+
+HexCore incluye templates base para bootstrap de proyectos:
+
+```sh
+hexcore init mi_proyecto --template hexagonal
+hexcore init mi_proyecto --template vertical-slice
+```
+
+- `hexagonal`: crea `src/domain`, `src/application`, `src/infrastructure`.
+- `vertical-slice`: crea `src/features`, `src/shared/domain`, `src/shared/application`, `src/shared/infrastructure`.
+
+En ambos templates se generan:
+- `config.py` en raíz con `repository_discovery_paths` de ejemplo.
+- estructura de migraciones con Alembic.
+
+---
+
+## Configuración v2 (Folder-Agnostic)
+
+Desde v2, HexCore usa configuración explícita y no aplica fallback implícito para descubrir repositorios.
+
+### 1. Configuración visible en raíz
+
+Define un archivo `config.py` en la raíz del proyecto:
+
+```python
+from hexcore.config import ServerConfig
+
+config = ServerConfig(
+    repository_discovery_paths={
+        "myapp.features.users.infrastructure.repositories",
+        "myapp.features.billing.infrastructure.repositories",
+    }
+)
+```
+
+### 2. Prioridad para cargar configuración
+
+`LazyConfig` resuelve módulos en este orden:
+
+1. `HEXCORE_CONFIG_MODULE`
+2. `HEXCORE_CONFIG_MODULES` (lista separada por comas)
+3. módulos configurados por `LazyConfig.set_config_modules(...)`
+4. `config` por defecto (raíz del proyecto)
+
+### 3. Regla de discovery en v2
+
+- Si `repository_discovery_paths` está vacío, no se cargan módulos de repositorios.
+- UoW falla con error explícito para evitar comportamiento ambiguo.
+
 ---
 
 ## Pautas de Colaboración

{hexcore-1.7.0 → hexcore-1.8.0}/README.md

@@ -26,6 +26,57 @@ Este repositorio cuenta con un conjunto de skills adicionales para extender y pe
 pip install hexcore
 ```
 
+## Templates de Proyecto (CLI)
+
+HexCore incluye templates base para bootstrap de proyectos:
+
+```sh
+hexcore init mi_proyecto --template hexagonal
+hexcore init mi_proyecto --template vertical-slice
+```
+
+- `hexagonal`: crea `src/domain`, `src/application`, `src/infrastructure`.
+- `vertical-slice`: crea `src/features`, `src/shared/domain`, `src/shared/application`, `src/shared/infrastructure`.
+
+En ambos templates se generan:
+- `config.py` en raíz con `repository_discovery_paths` de ejemplo.
+- estructura de migraciones con Alembic.
+
+---
+
+## Configuración v2 (Folder-Agnostic)
+
+Desde v2, HexCore usa configuración explícita y no aplica fallback implícito para descubrir repositorios.
+
+### 1. Configuración visible en raíz
+
+Define un archivo `config.py` en la raíz del proyecto:
+
+```python
+from hexcore.config import ServerConfig
+
+config = ServerConfig(
+    repository_discovery_paths={
+        "myapp.features.users.infrastructure.repositories",
+        "myapp.features.billing.infrastructure.repositories",
+    }
+)
+```
+
+### 2. Prioridad para cargar configuración
+
+`LazyConfig` resuelve módulos en este orden:
+
+1. `HEXCORE_CONFIG_MODULE`
+2. `HEXCORE_CONFIG_MODULES` (lista separada por comas)
+3. módulos configurados por `LazyConfig.set_config_modules(...)`
+4. `config` por defecto (raíz del proyecto)
+
+### 3. Regla de discovery en v2
+
+- Si `repository_discovery_paths` está vacío, no se cargan módulos de repositorios.
+- UoW falla con error explícito para evitar comportamiento ambiguo.
+
 ---
 
 ## Pautas de Colaboración

hexcore-1.8.0/hexcore/application/dtos/__init__.py

@@ -0,0 +1,23 @@
+"""
+Submódulo de DTOs base para la aplicación.
+"""
+
+from .base import DTO
+from .query import (
+	FilterConditionDTO,
+	FilterOperator,
+	QueryRequestDTO,
+	QueryResponseDTO,
+	SortConditionDTO,
+	SortDirection,
+)
+
+__all__ = [
+	"DTO",
+	"FilterOperator",
+	"SortDirection",
+	"FilterConditionDTO",
+	"SortConditionDTO",
+	"QueryRequestDTO",
+	"QueryResponseDTO",
+]

hexcore-1.8.0/hexcore/application/dtos/query.py

@@ -0,0 +1,66 @@
+import enum
+import typing as t
+
+from pydantic import Field
+
+from .base import DTO
+
+
+class FilterOperator(str, enum.Enum):
+    EQ = "eq"
+    NE = "ne"
+    GT = "gt"
+    GTE = "gte"
+    LT = "lt"
+    LTE = "lte"
+    IN = "in"
+    NOT_IN = "not_in"
+    CONTAINS = "contains"
+    STARTSWITH = "startswith"
+    ENDSWITH = "endswith"
+    IS_NULL = "is_null"
+
+
+class SortDirection(str, enum.Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+
+class FilterConditionDTO(DTO):
+    field: str = Field(min_length=1)
+    operator: FilterOperator = FilterOperator.EQ
+    value: t.Any = None
+
+
+class SortConditionDTO(DTO):
+    field: str = Field(min_length=1)
+    direction: SortDirection = SortDirection.ASC
+
+
+def _empty_search_fields() -> list[str]:
+    return []
+
+
+def _empty_filters() -> list[FilterConditionDTO]:
+    return []
+
+
+def _empty_sort() -> list[SortConditionDTO]:
+    return []
+
+
+class QueryRequestDTO(DTO):
+    limit: int = Field(default=50, ge=1)
+    offset: int = Field(default=0, ge=0)
+    search: str | None = None
+    search_fields: list[str] = Field(default_factory=_empty_search_fields)
+    filters: list[FilterConditionDTO] = Field(default_factory=_empty_filters)
+    sort: list[SortConditionDTO] = Field(default_factory=_empty_sort)
+
+
+class QueryResponseDTO(DTO):
+    items: list[t.Any] = Field(default_factory=list)
+    total: int = 0
+    limit: int = 0
+    offset: int = 0
+    has_next: bool = False

hexcore-1.8.0/hexcore/application/use_cases/__init__.py

@@ -0,0 +1,13 @@
+"""
+Submódulo de casos de uso base para la aplicación.
+"""
+
+from .base import UseCase
+from .query import ListEntitiesUseCase, QueryEntitiesUseCase, SearchEntitiesUseCase
+
+__all__ = [
+	"UseCase",
+	"QueryEntitiesUseCase",
+	"ListEntitiesUseCase",
+	"SearchEntitiesUseCase",
+]

hexcore-1.8.0/hexcore/application/use_cases/query.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import typing as t
+
+from hexcore.application.dtos.query import QueryRequestDTO, QueryResponseDTO
+from hexcore.domain.base import BaseEntity
+from hexcore.domain.repositories import IBaseRepository
+from hexcore.domain.services import BaseDomainService
+
+from .base import UseCase
+
+T = t.TypeVar("T", bound=BaseEntity)
+
+
+class QueryEntitiesUseCase(UseCase[QueryRequestDTO, QueryResponseDTO], t.Generic[T]):
+    def __init__(
+        self,
+        repository: IBaseRepository[T],
+        service: BaseDomainService | None = None,
+    ) -> None:
+        self.repository = repository
+        self.service = service or BaseDomainService()
+
+    async def execute(self, command: QueryRequestDTO) -> QueryResponseDTO:
+        return await self.service.list_entities(self.repository, command)
+
+
+class ListEntitiesUseCase(QueryEntitiesUseCase[T]):
+    async def execute(self, command: QueryRequestDTO) -> QueryResponseDTO:
+        command.search = None
+        command.search_fields = []
+        return await super().execute(command)
+
+
+class SearchEntitiesUseCase(QueryEntitiesUseCase[T]):
+    async def execute(self, command: QueryRequestDTO) -> QueryResponseDTO:
+        return await super().execute(command)

{hexcore-1.7.0 → hexcore-1.8.0}/hexcore/config.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 import importlib
+import os
 import typing as t
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 from pathlib import Path
 from hexcore.infrastructure.cache import ICache
 from hexcore.domain.events import IEventDispatcher
@@ -53,25 +54,74 @@ class ServerConfig(BaseModel):
     # Event Dispatcher
     event_dispatcher: IEventDispatcher = InMemoryEventDispatcher()
 
+    # Repository Discovery
+    # v2 (breaking): discovery explicito y folder-agnostic.
+    # Si se deja vacio, no se autoloadearan modulos de repositorios.
+    repository_discovery_paths: set[str] = Field(default_factory=set)
+
 
 class LazyConfig:
     """
-    Loader de configuración flexible.
-    Busca una variable 'config' (instancia de ServerConfig) o una clase 'ServerConfig' en los módulos personalizados.
-    Si no la encuentra, usa la configuración base del kernel.
+    Loader de configuración flexible y agnóstico de estructura de carpetas.
+
+    Prioridad de resolución:
+    1) Variable de entorno HEXCORE_CONFIG_MODULE (módulo único)
+    2) Variable de entorno HEXCORE_CONFIG_MODULES (lista separada por comas)
+    3) Lista configurada por set_config_modules(...)
+    4) Valor por defecto: "config" (archivo config.py en la raíz del proyecto)
+
+    En cada módulo candidato se busca:
+    - atributo `config` (instancia o clase derivada de ServerConfig)
+    - o clase `ServerConfig` derivada de la base.
 
-    IMPORTANTE: La configuración personalizada debe estar en un módulo llamado 'config' en src.domain
+    Si no se encuentra nada válido, usa ServerConfig() por defecto.
 
     """
 
     _imported_config: t.Optional[ServerConfig] = None
+    _config_modules: tuple[str, ...] = ("config",)
+
+    @classmethod
+    def set_config_modules(cls, modules: t.Iterable[str]) -> None:
+        """Define módulos candidatos para resolver configuración personalizada."""
+        normalized_modules = tuple(
+            module_name.strip() for module_name in modules if str(module_name).strip()
+        )
+        cls._config_modules = normalized_modules
+        cls._imported_config = None
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Limpia la configuración cacheada para forzar nueva resolución."""
+        cls._imported_config = None
+
+    @classmethod
+    def _iter_config_module_candidates(cls) -> tuple[str, ...]:
+        env_single_module = os.getenv("HEXCORE_CONFIG_MODULE", "").strip()
+        if env_single_module:
+            return (env_single_module,)
+
+        env_modules_raw = os.getenv("HEXCORE_CONFIG_MODULES", "").strip()
+        if env_modules_raw:
+            env_modules = tuple(
+                module_name.strip()
+                for module_name in env_modules_raw.split(",")
+                if module_name.strip()
+            )
+            if env_modules:
+                return env_modules
+
+        if cls._config_modules:
+            return cls._config_modules
+
+        return ("config",)
 
     @classmethod
     def get_config(cls) -> ServerConfig:
         if cls._imported_config is not None:
             return cls._imported_config
         # Intenta importar la config personalizada
-        for modpath in ("config", "src.domain.config"):
+        for modpath in cls._iter_config_module_candidates():
             try:
                 mod = importlib.import_module(modpath)
                 config_instance = getattr(mod, "config", None)
@@ -99,4 +149,4 @@ class LazyConfig:
         return cls._imported_config
 
 
-# Esto es solo para disparar el Workflow pra subir la ultima version a PyPI, por favor ignora este comentario
+# Esto es solo para disparar el Workflow pra subir la ultima version a PyPI, por favor ignora este comentario

hexcore-1.8.0/hexcore/domain/services.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import datetime as dt
+import typing as t
+
+from hexcore.application.dtos.query import (
+    FilterConditionDTO,
+    FilterOperator,
+    QueryRequestDTO,
+    QueryResponseDTO,
+    SortConditionDTO,
+    SortDirection,
+)
+from hexcore.domain.base import BaseEntity
+from hexcore.domain.events import IEventDispatcher
+from hexcore.domain.repositories import IBaseRepository
+from hexcore.config import LazyConfig
+
+
+T = t.TypeVar("T", bound=BaseEntity)
+
+
+class BaseDomainService:
+    def __init__(
+        self,
+        event_dispatcher: IEventDispatcher = LazyConfig().get_config().event_dispatcher,
+    ) -> None:
+        self.config = LazyConfig.get_config()
+        self.event_dispatcher = event_dispatcher
+
+    async def list_entities(
+        self,
+        repository: IBaseRepository[T],
+        query: QueryRequestDTO,
+    ) -> QueryResponseDTO:
+        query_all = getattr(repository, "query_all", None)
+        if callable(query_all):
+            entities, total = await t.cast(
+                t.Callable[[QueryRequestDTO], t.Awaitable[tuple[list[T], int]]],
+                query_all,
+            )(query)
+            has_next = query.offset + len(entities) < total
+            return QueryResponseDTO(
+                items=entities,
+                total=total,
+                limit=query.limit,
+                offset=query.offset,
+                has_next=has_next,
+            )
+
+        entities = await repository.list_all(limit=None, offset=0)
+        return self.query_entities(entities, query)
+
+    def query_entities(
+        self,
+        entities: t.Sequence[T],
+        query: QueryRequestDTO,
+    ) -> QueryResponseDTO:
+        results: list[T] = list(entities)
+        results = self._apply_search(results, query.search, query.search_fields)
+        results = self._apply_filters(results, query.filters)
+        results = self._apply_sort(results, query.sort)
+
+        total = len(results)
+        paginated = results[query.offset : query.offset + query.limit]
+        has_next = query.offset + len(paginated) < total
+
+        return QueryResponseDTO(
+            items=paginated,
+            total=total,
+            limit=query.limit,
+            offset=query.offset,
+            has_next=has_next,
+        )
+
+    def _apply_search(
+        self,
+        entities: list[T],
+        search_text: str | None,
+        search_fields: list[str],
+    ) -> list[T]:
+        if not search_text:
+            return entities
+
+        normalized_query = search_text.lower().strip()
+        if not normalized_query:
+            return entities
+
+        fields = search_fields or self._infer_search_fields(entities)
+        if not fields:
+            return entities
+
+        matched: list[T] = []
+        for entity in entities:
+            for field_name in fields:
+                value = getattr(entity, field_name, None)
+                if value is None:
+                    continue
+                if normalized_query in str(value).lower():
+                    matched.append(entity)
+                    break
+        return matched
+
+    def _infer_search_fields(self, entities: list[T]) -> list[str]:
+        if not entities:
+            return []
+
+        sample = entities[0]
+        sample_dict = sample.model_dump()
+        return [
+            field_name
+            for field_name, value in sample_dict.items()
+            if isinstance(value, (str, int, float, bool, dt.date, dt.datetime))
+        ]
+
+    def _apply_filters(
+        self,
+        entities: list[T],
+        filters: list[FilterConditionDTO],
+    ) -> list[T]:
+        if not filters:
+            return entities
+
+        return [
+            entity
+            for entity in entities
+            if all(self._matches_filter(entity, condition) for condition in filters)
+        ]
+
+    def _matches_filter(
+        self,
+        entity: BaseEntity,
+        condition: FilterConditionDTO,
+    ) -> bool:
+        value = getattr(entity, condition.field, None)
+        operator = condition.operator
+        expected = condition.value
+
+        if operator == FilterOperator.IS_NULL:
+            return value is None
+
+        if operator == FilterOperator.EQ:
+            return value == expected
+        if operator == FilterOperator.NE:
+            return value != expected
+        if operator == FilterOperator.GT:
+            return self._safe_compare(value, expected, lambda a, b: a > b)
+        if operator == FilterOperator.GTE:
+            return self._safe_compare(value, expected, lambda a, b: a >= b)
+        if operator == FilterOperator.LT:
+            return self._safe_compare(value, expected, lambda a, b: a < b)
+        if operator == FilterOperator.LTE:
+            return self._safe_compare(value, expected, lambda a, b: a <= b)
+        if operator == FilterOperator.IN:
+            return self._in_operator(value, expected)
+        if operator == FilterOperator.NOT_IN:
+            return not self._in_operator(value, expected)
+        if operator == FilterOperator.CONTAINS:
+            return self._text_operator(value, expected, mode="contains")
+        if operator == FilterOperator.STARTSWITH:
+            return self._text_operator(value, expected, mode="startswith")
+        if operator == FilterOperator.ENDSWITH:
+            return self._text_operator(value, expected, mode="endswith")
+
+        return False
+
+    def _safe_compare(
+        self,
+        left: t.Any,
+        right: t.Any,
+        comparator: t.Callable[[t.Any, t.Any], bool],
+    ) -> bool:
+        if left is None or right is None:
+            return False
+        try:
+            return comparator(left, right)
+        except TypeError:
+            return False
+
+    def _in_operator(self, value: t.Any, expected: t.Any) -> bool:
+        if expected is None:
+            return False
+        if isinstance(expected, (str, bytes)):
+            return value == expected
+        if not isinstance(expected, (list, tuple, set, frozenset)):
+            return False
+        return value in expected
+
+    def _text_operator(self, value: t.Any, expected: t.Any, mode: str) -> bool:
+        if value is None or expected is None:
+            return False
+        left = str(value).lower()
+        right = str(expected).lower()
+        if mode == "contains":
+            return right in left
+        if mode == "startswith":
+            return left.startswith(right)
+        if mode == "endswith":
+            return left.endswith(right)
+        return False
+
+    def _apply_sort(
+        self,
+        entities: list[T],
+        sort_conditions: list[SortConditionDTO],
+    ) -> list[T]:
+        if not sort_conditions:
+            return entities
+
+        ordered = list(entities)
+        for condition in reversed(sort_conditions):
+            reverse = condition.direction == SortDirection.DESC
+            ordered.sort(
+                key=lambda item: self._safe_sort_value(getattr(item, condition.field, None)),
+                reverse=reverse,
+            )
+        return ordered
+
+    def _safe_sort_value(self, value: t.Any) -> tuple[int, int, t.Any]:
+        if value is None:
+            return (1, 0, None)
+        if isinstance(value, bool):
+            return (0, 0, int(value))
+        if isinstance(value, (int, float)):
+            return (0, 1, float(value))
+        if isinstance(value, dt.datetime):
+            return (0, 2, value.timestamp())
+        if isinstance(value, dt.date):
+            return (0, 3, value.toordinal())
+        if isinstance(value, str):
+            return (0, 4, value.casefold())
+        return (0, 5, str(value))

hexcore-1.8.0/hexcore/infrastructure/api/__init__.py

@@ -0,0 +1,3 @@
+from .utils import build_query_endpoint, register_query_endpoint
+
+__all__ = ["build_query_endpoint", "register_query_endpoint"]