vega-framework 0.1.29__py3-none-any.whl → 0.1.30__py3-none-any.whl

vega/cli/commands/generate.py

@@ -15,6 +15,8 @@ from vega.cli.templates import (
     render_sqlalchemy_model,
     render_cli_command,
     render_cli_command_simple,
+    render_event,
+    render_event_handler,
     render_template,
 )
 from vega.cli.scaffolds import create_fastapi_scaffold
@@ -61,6 +63,11 @@ def generate_component(
     class_name = to_pascal_case(name)
     implementation = implementation.strip() if implementation else None
 
+    if component_type == 'repo':
+        component_type = 'repository'
+    if component_type in {'event-handler', 'subscriber'}:
+        component_type = 'event_handler'
+
     suffixes = {
         "repository": "Repository",
         "service": "Service",
@@ -105,6 +112,10 @@ def generate_component(
         _generate_web_models(project_root, project_name, name, is_request, is_response)
     elif component_type == 'command':
         _generate_command(project_root, project_name, name, implementation)
+    elif component_type == 'event':
+        _generate_event(project_root, project_name, class_name, file_name)
+    elif component_type == 'event_handler':
+        _generate_event_handler(project_root, project_name, class_name, file_name)
 
 
 def _generate_entity(project_root: Path, project_name: str, class_name: str, file_name: str):
@@ -875,3 +886,106 @@ def _generate_command(project_root: Path, project_name: str, name: str, is_async
     click.echo(click.style(f"      (Commands are auto-discovered from cli/commands/)", fg='bright_black'))
     if with_interactor:
         click.echo(f"   3. Create interactor: vega generate interactor {interactor_name}")
+
+
+def _generate_event(project_root: Path, project_name: str, class_name: str, file_name: str):
+    """Generate a domain event."""
+
+    events_path = project_root / "domain" / "events"
+    events_path.mkdir(parents=True, exist_ok=True)
+
+    init_file = events_path / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text("")
+
+    file_path = events_path / f"{file_name}.py"
+    if file_path.exists():
+        click.echo(click.style(f"ERROR: Error: {file_path.relative_to(project_root)} already exists", fg='red'))
+        return
+
+    click.echo("\nDefine event payload fields (press Enter to skip):")
+    fields: list[dict[str, str]] = []
+    while True:
+        field_name = click.prompt("Field name", default="", show_default=False)
+        if not field_name:
+            break
+        snake_name = to_snake_case(field_name)
+        type_hint = click.prompt("Type hint", default="str")
+        description = click.prompt(
+            "Description",
+            default=f"{snake_name.replace('_', ' ').capitalize()} value",
+        )
+        fields.append(
+            {
+                "name": snake_name,
+                "type_hint": type_hint,
+                "description": description,
+            }
+        )
+
+    content = render_event(class_name, fields)
+    file_path.write_text(content)
+    click.echo(f"+ Created {click.style(str(file_path.relative_to(project_root)), fg='green')}")
+
+    click.echo("\nNext steps:")
+    click.echo("   1. Publish the event from your domain logic.")
+    click.echo("   2. Generate subscribers: vega generate subscriber <HandlerName>")
+
+
+def _generate_event_handler(project_root: Path, project_name: str, class_name: str, file_name: str):
+    """Generate an application-level event handler/subscriber."""
+
+    handlers_path = project_root / "application" / "events"
+    handlers_path.mkdir(parents=True, exist_ok=True)
+
+    init_file = handlers_path / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text("")
+
+    handler_file = handlers_path / f"{file_name}.py"
+    if handler_file.exists():
+        click.echo(click.style(f"ERROR: Error: {handler_file.relative_to(project_root)} already exists", fg='red'))
+        return
+
+    default_event_class = class_name
+    if default_event_class.lower().endswith("handler"):
+        default_event_class = default_event_class[:-7] or class_name
+
+    event_class = click.prompt("Event class name", default=default_event_class)
+    event_module_default = f"domain.events.{to_snake_case(event_class)}"
+    event_module = click.prompt("Event module path", default=event_module_default)
+
+    priority = click.prompt("Handler priority (higher runs first)", default=0, type=int)
+    retry_on_error = click.confirm("Retry on failure?", default=False)
+    max_retries = None
+    if retry_on_error:
+        max_retries = click.prompt("Max retries", default=3, type=int)
+
+    decorator_args = event_class
+    options: list[str] = []
+    if priority:
+        options.append(f"priority={priority}")
+    if retry_on_error:
+        options.append("retry_on_error=True")
+        if max_retries is not None:
+            options.append(f"max_retries={max_retries}")
+    if options:
+        decorator_args = f"{event_class}, " + ", ".join(options)
+
+    handler_func_name = to_snake_case(class_name)
+
+    content = render_event_handler(
+        class_name=class_name,
+        handler_func_name=handler_func_name,
+        event_name=event_class,
+        event_module=event_module,
+        decorator_args=decorator_args,
+    )
+
+    handler_file.write_text(content)
+    click.echo(f"+ Created {click.style(str(handler_file.relative_to(project_root)), fg='green')}")
+
+    click.echo("\nNext steps:")
+    click.echo(f"   1. Implement your handler in {handler_file.relative_to(project_root)}")
+    click.echo("   2. Ensure the module is imported during application bootstrap (autodiscovery or manual import).")
+    click.echo("   3. Run your workflow and verify the subscriber reacts to the event.")

vega/cli/commands/init.py

@@ -38,6 +38,7 @@ def init_project(project_name: str, template: str, parent_path: str):
         "infrastructure/repositories",
         "infrastructure/services",
         "presentation/cli/commands",
+        "events",
         "tests/domain",
         "tests/application",
         "tests/infrastructure",
@@ -53,6 +54,11 @@ def init_project(project_name: str, template: str, parent_path: str):
             from vega.cli.templates import render_cli_commands_init
             content = render_cli_commands_init()
             (dir_path / "__init__.py").write_text(content)
+        # Use auto-discovery template for events/
+        elif directory == "events":
+            from vega.cli.templates import render_events_init
+            content = render_events_init()
+            (dir_path / "__init__.py").write_text(content)
 
         click.echo(f"  + Created {directory}/")
 

vega/cli/main.py

@@ -57,7 +57,20 @@ def init(project_name, template, path):
 
 @cli.command()
 @click.argument('component_type', type=click.Choice([
-    'entity', 'repository', 'repo', 'service', 'interactor', 'mediator', 'router', 'middleware', 'webmodel', 'model', 'command'
+    'entity',
+    'repository',
+    'repo',
+    'service',
+    'interactor',
+    'mediator',
+    'router',
+    'middleware',
+    'webmodel',
+    'model',
+    'command',
+    'event',
+    'event-handler',
+    'subscriber',
 ]))
 @click.argument('name')
 @click.option('--path', default='.', help='Project root path')
@@ -80,6 +93,8 @@ def generate(component_type, name, path, impl, request, response):
         webmodel    - Pydantic request/response models (requires web module)
         model       - SQLAlchemy model (requires sqlalchemy module)
         command     - CLI command (async by default)
+        event       - Domain event (immutable dataclass + metadata)
+        event-handler/subscriber - Application-level event subscriber
 
     Examples:
         vega generate entity Product
@@ -94,6 +109,8 @@ def generate(component_type, name, path, impl, request, response):
         vega generate model User
         vega generate command CreateUser
         vega generate command ListUsers --impl sync
+        vega generate event UserCreated
+        vega generate subscriber SendWelcomeEmail --name UserCreated
     """
     # Normalize 'repo' to 'repository'
     if component_type == 'repo':

vega/cli/templates/__init__.py

@@ -28,6 +28,9 @@ from .components import (
     render_cli_command_simple,
     render_cli_commands_init,
     render_fastapi_routes_init_autodiscovery,
+    render_event,
+    render_event_handler,
+    render_events_init,
 )
 from .loader import render_template
 
@@ -61,5 +64,8 @@ __all__ = [
     "render_cli_command_simple",
     "render_cli_commands_init",
     "render_fastapi_routes_init_autodiscovery",
+    "render_event",
+    "render_event_handler",
+    "render_events_init",
     "render_template",
 ]

vega/cli/templates/components.py

@@ -247,3 +247,37 @@ def render_cli_commands_init() -> str:
 def render_fastapi_routes_init_autodiscovery() -> str:
     """Return the template for web/routes/__init__.py with auto-discovery"""
     return render_template("routes_init_autodiscovery.py.j2", subfolder="web")
+
+
+def render_event(class_name: str, fields: list[dict]) -> str:
+    """Return the template for a domain event"""
+    return render_template(
+        "event.py.j2",
+        subfolder="domain",
+        class_name=class_name,
+        fields=fields,
+    )
+
+
+def render_event_handler(
+    class_name: str,
+    handler_func_name: str,
+    event_name: str,
+    event_module: str,
+    decorator_args: str,
+) -> str:
+    """Return the template for an event handler"""
+    return render_template(
+        "event_handler.py.j2",
+        subfolder="domain",
+        class_name=class_name,
+        handler_func_name=handler_func_name,
+        event_name=event_name,
+        event_module=event_module,
+        decorator_args=decorator_args,
+    )
+
+
+def render_events_init() -> str:
+    """Return the template for events/__init__.py with auto-discovery"""
+    return render_template("events_init.py.j2", subfolder="project")

vega/cli/templates/domain/event.py.j2

@@ -0,0 +1,23 @@
+"""{{ class_name }} domain event"""
+from dataclasses import dataclass
+from vega.events import Event
+
+
+@dataclass(frozen=True)
+class {{ class_name }}(Event):
+    """
+    {{ class_name }} event.
+
+    This event is published when {{ class_name|lower|replace('created', 'is created')|replace('updated', 'is updated')|replace('deleted', 'is deleted') }}.
+
+    Attributes:
+{% for field in fields %}        {{ field.name }}: {{ field.type_hint }} - {{ field.description }}
+{% endfor %}
+    """
+{% for field in fields %}
+    {{ field.name }}: {{ field.type_hint }}
+{% endfor %}
+
+    def __post_init__(self):
+        """Initialize event metadata"""
+        super().__init__()

vega/cli/templates/domain/event_handler.py.j2

@@ -0,0 +1,22 @@
+"""{{ class_name }} event handler"""
+from vega.events import subscribe
+from {{ event_module }} import {{ event_name }}
+
+
+@subscribe({{ decorator_args }})
+async def {{ handler_func_name }}(event: {{ event_name }}):
+    """
+    Handle {{ event_name }} event.
+
+    This handler is automatically called when a {{ event_name }} event is published.
+
+    Args:
+        event: The {{ event_name }} event instance
+
+    Example:
+        # Event is automatically published from domain logic
+        # This handler will be called automatically
+        pass
+    """
+    # TODO: Implement event handling logic
+    raise NotImplementedError("Implement {{ class_name }} handler")

vega/cli/templates/domain/repository_interface.py.j2

@@ -3,7 +3,7 @@ from abc import abstractmethod
 from typing import List, Optional
 
 from vega.patterns import Repository
-from entities.{{ entity_file }} import {{ entity_name }}
+from domain.entities.{{ entity_file }} import {{ entity_name }}
 
 
 class {{ class_name }}(Repository[{{ entity_name }}]):

vega/cli/templates/project/events_init.py.j2

@@ -0,0 +1,32 @@
+"""Event handlers auto-discovery
+
+This module automatically discovers and registers all event handlers
+decorated with @subscribe() in this directory.
+
+The auto-discovery happens when you call register_all_handlers().
+This should be called during application startup.
+"""
+from vega.discovery import discover_event_handlers
+
+
+def register_all_handlers():
+    """
+    Auto-discover and register all event handlers in this directory.
+
+    This function scans all Python modules in the events/ directory and
+    imports them to trigger @subscribe() decorator registration.
+
+    Call this function during application bootstrap to ensure all event
+    handlers are registered with the global event bus.
+
+    Example:
+        # In your main.py or application startup
+        from events import register_all_handlers
+
+        # Register all event handlers
+        register_all_handlers()
+
+        # Now events will be handled automatically
+        await UserCreated(user_id="123", email="test@test.com", name="John")
+    """
+    discover_event_handlers(__package__)

vega/discovery/__init__.py

@@ -1,5 +1,6 @@
 """Auto-discovery utilities for Vega framework"""
 from .routes import discover_routers
 from .commands import discover_commands
+from .events import discover_event_handlers
 
-__all__ = ["discover_routers", "discover_commands"]
+__all__ = ["discover_routers", "discover_commands", "discover_event_handlers"]

vega/discovery/events.py

@@ -0,0 +1,86 @@
+"""Event handlers auto-discovery utilities"""
+import importlib
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def discover_event_handlers(
+    base_package: str,
+    events_subpackage: str = "events"
+) -> None:
+    """
+    Auto-discover and register event handlers from a package.
+
+    This function scans a package directory for Python modules containing
+    event handlers decorated with @subscribe() and automatically imports them
+    to trigger registration with the global event bus.
+
+    Args:
+        base_package: Base package name (use __package__ from calling module)
+        events_subpackage: Subpackage path containing events (default: "events")
+
+    Example:
+        # In your project's events/__init__.py
+        from vega.discovery import discover_event_handlers
+
+        def register_all_handlers():
+            discover_event_handlers(__package__)
+
+        # Or with custom configuration
+        def register_all_handlers():
+            discover_event_handlers(
+                __package__,
+                events_subpackage="application.events"
+            )
+
+    Note:
+        Event handlers are registered automatically when modules are imported.
+        This function simply imports all modules in the events directory to
+        trigger the @subscribe() decorator registration.
+
+        The function doesn't return anything - handlers register themselves
+        with the global event bus via the @subscribe() decorator.
+    """
+    # Resolve the events package path
+    try:
+        # Determine the package to scan
+        if base_package.endswith(events_subpackage):
+            events_package = base_package
+        else:
+            # Extract base from fully qualified package name
+            parts = base_package.split('.')
+            # Find the root package (usually the project name)
+            root_package = parts[0]
+            events_package = f"{root_package}.{events_subpackage}"
+
+        # Import the events package to get its path
+        events_module = importlib.import_module(events_package)
+        events_dir = Path(events_module.__file__).parent
+
+        logger.debug(f"Discovering event handlers in: {events_dir}")
+
+        # Scan for event handler modules
+        discovered_count = 0
+        for file in events_dir.glob("*.py"):
+            if file.stem == "__init__":
+                continue
+
+            module_name = f"{events_package}.{file.stem}"
+
+            try:
+                # Import the module to trigger @subscribe() decorator registration
+                importlib.import_module(module_name)
+                discovered_count += 1
+                logger.info(f"Loaded event handlers from: {module_name}")
+
+            except Exception as e:
+                logger.warning(f"Failed to import {module_name}: {e}")
+                continue
+
+        logger.info(f"Auto-discovery complete: {discovered_count} event module(s) loaded")
+
+    except ImportError as e:
+        logger.error(f"Failed to import events package '{events_package}': {e}")
+        raise