HexCore es un módulo base reutilizable para proyectos Python que implementan arquitectura hexagonal y event handling.

Este repositorio cuenta con un conjunto de skills adicionales para extender y personalizar funcionalidades en VS Code y otros entornos compatibles. Puedes encontrarlas en:

• Repositorio de Skills de HexCore

• Clases base y abstracciones para entidades, repositorios, servicios y unidad de trabajo (UoW), siguiendo los principios de DDD y arquitectura hexagonal.
• Interfaces y contratos para caché, eventos y manejo de dependencias, desacoplando la lógica de negocio de la infraestructura.
• Utilidades para event sourcing y event dispatching listas para usar en cualquier proyecto.
• Estructura flexible para que puedas construir microservicios o aplicaciones monolíticas desacopladas y testeables.

pip install hexcore

¡Gracias por tu interés en contribuir a HexCore! Para mantener una colaboración organizada y eficiente, sigue estas pautas:

Mantén siempre una comunicación respetuosa y profesional. Revisa el Código de Conducta antes de interactuar.

• Forkea el repositorio y crea una rama para tu contribución (feature/nombre, fix/nombre, etc.).
• Realiza tus cambios en la rama y asegúrate de que el código funcione correctamente.
• Escribe una descripción clara y detallada en tu pull request (PR).
• Relaciona los issues relevantes en tu PR si aplica.

• Sigue la guía de estilos de Python (PEP8).
• Usa comentarios cuando sea necesario para clarificar el propósito del código.
• Idealmente, incluye pruebas unitarias para nuevas funciones y arreglos.

• Todos los PR serán revisados antes de ser aceptados. Se pueden solicitar cambios o aclaraciones.
• Responde a los comentarios de los revisores para facilitar el proceso.

• Describe claramente los problemas que encuentres.
• Proporciona información relevante (logs, versiones, pasos para reproducir, etc.).

• Usa los issues y las discusiones para preguntas, sugerencias o propuestas.
• Si tienes dudas sobre cómo empezar, puedes abrir un issue para orientación.

Al contribuir, aceptas que tu código será distribuido bajo la licencia del repositorio.

HexCore se organiza con los siguientes submódulos y carpetas:

• src/domain/: Módulos de dominio, entidades, repositorios, servicios, objetos de valor, eventos, enums y excepciones.

  src/domain/{modulo}/
    ├─ __init__.py
    ├─ entities.py
    ├─ repositories.py
    ├─ services.py
    ├─ value_objects.py
    ├─ events.py
    ├─ enums.py
    └─ exceptions.py
  

• src/application/: Casos de uso (UseCase) y DTOs para orquestar la lógica de negocio.
• src/infrastructure/: Implementaciones técnicas (ORM/ODM, CLI, caché, base de datos, repositorios, unit of work).
• src/infrastructure/database/models/: Modelos SQLAlchemy para base de datos relacional.
• src/infrastructure/database/documents/: Documentos Beanie para MongoDB.
• tests/: Pruebas para módulos de dominio e infraestructura.

Clase base para entidades de dominio. Provee atributos comunes y gestión de eventos.

from hexcore.domain.base import BaseEntity

class User(BaseEntity):
    id: UUID
    name: str

Abstracciones para eventos de dominio y para ciclo de vida de entidades.

from hexcore.domain.events import DomainEvent, EntityCreatedEvent

class UserCreatedEvent(EntityCreatedEvent[User]):
    pass

user = User(...)
event = UserCreatedEvent(entity_id=user.id, payload={"name": user.name})

Repositorio genérico para modelos SQLAlchemy con métodos CRUD reutilizables.

class SQLAlchemyCommonImplementationsRepo(BaseSQLAlchemyRepository[T], HasBasicArgs[T, M], t.Generic[T, M]):
    # Métodos principales: get_by_id, list_all, save, delete
    ...

Ejemplo:

class UserRepository(SQLAlchemyCommonImplementationsRepo[UserEntity, UserModel]):
    def __init__(self, uow):
        super().__init__(
            entity_cls=UserEntity,
            model_cls=UserModel,
            not_found_exception=UserNotFoundException,
            fields_resolvers=None,
            fields_serializers=None,
            uow=uow
        )

Repositorio genérico para documentos Beanie ODM (MongoDB) con métodos CRUD reutilizables.

class BeanieODMCommonImplementationsRepo(IBaseRepository[T], HasBasicArgs[T, D], t.Generic[T, D]):
    # Métodos principales: get_by_id, list_all, save, delete
    ...

Ejemplo:

class UserRepository(BeanieODMCommonImplementationsRepo[UserEntity, UserDocument]):
    def __init__(self, uow):
        super().__init__(
            entity_cls=UserEntity,
            document_cls=UserDocument,
            not_found_exception=UserNotFoundException,
            fields_resolvers=None,
            fields_serializers=None,
            uow=uow
        )

Para inicializar y registrar automáticamente todos los documentos Beanie:

from hexcore.infrastructure.repositories.orms.beanie.utils import init_beanie_documents

await init_beanie_documents()

Ambos repositorios utilizan to_entity_from_model_or_document para convertir modelos ORM/ODM en entidades del dominio, aplicando resolvers para atributos complejos.

• CONTRIBUTING.md: Pautas de colaboración.
• CHANGELOG.md: Historial de cambios.
• DOCS.md: Documentación básica de clases, funciones y ejemplos.