dory-sdk 2.1.0__py3-none-any.whl

dory/__init__.py

@@ -0,0 +1,70 @@
+"""
+Dory SDK - Python Integration Package for Processor Applications
+
+This SDK handles all operational concerns (graceful shutdown, state migration,
+health checks, observability) so developers focus solely on business logic.
+
+Quick Start (Class-based API):
+    from dory import DoryApp, BaseProcessor, stateful
+
+    class MyProcessor(BaseProcessor):
+        counter = stateful(0)  # Auto-saved/restored
+
+        async def run(self):
+            async for _ in self.run_loop(interval=1):
+                self.counter += 1
+
+    if __name__ == '__main__':
+        DoryApp().run(MyProcessor)
+
+Quick Start (Function-based API):
+    from dory.simple import processor, state
+
+    counter = state(0)
+
+    @processor
+    async def main(ctx):
+        async for _ in ctx.run_loop(interval=1):
+            counter.value += 1
+"""
+
+__version__ = "1.0.0"
+
+# Core API
+from dory.core.processor import BaseProcessor
+from dory.core.context import ExecutionContext
+from dory.core.app import DoryApp
+
+# Configuration
+from dory.config.schema import DoryConfig
+
+# Decorators for simplified integration
+from dory.decorators import stateful, StatefulVar
+
+# Exceptions
+from dory.utils.errors import (
+    DoryError,
+    DoryStartupError,
+    DoryShutdownError,
+    DoryStateError,
+    DoryConfigError,
+)
+
+__all__ = [
+    # Core API
+    "BaseProcessor",
+    "ExecutionContext",
+    "DoryApp",
+    "DoryConfig",
+    # Decorators
+    "stateful",
+    "StatefulVar",
+    # Exceptions
+    "DoryError",
+    "DoryStartupError",
+    "DoryShutdownError",
+    "DoryStateError",
+    "DoryConfigError",
+    # Version
+    "__version__",
+]

dory/auto_instrument.py

@@ -0,0 +1,142 @@
+"""
+Auto-instrumentation decorator for handlers.
+
+Automatically applies:
+- Request ID generation
+- Request tracking
+- OpenTelemetry span creation
+- Error classification
+- Attribute injection
+
+No manual decorators needed!
+"""
+
+import functools
+import logging
+from typing import Callable, Any
+
+logger = logging.getLogger(__name__)
+
+
+def auto_instrument(func: Callable) -> Callable:
+    """
+    Auto-instrument async function with all SDK features.
+
+    Automatically handles:
+    - Request ID generation
+    - Request tracking with timeout
+    - OpenTelemetry span creation
+    - Span attributes injection
+    - Error classification and logging
+
+    Usage:
+        @auto_instrument
+        async def handler(self, request):
+            # All instrumentation is automatic!
+            return {"status": "ok"}
+
+    Or with metaclass (no decorator needed):
+        class MyProcessor(BaseProcessor):
+            # All handle_* methods automatically instrumented!
+            async def handle_request(self, request):
+                return {"status": "ok"}
+
+    Args:
+        func: Async function to instrument
+
+    Returns:
+        Instrumented async function
+    """
+
+    @functools.wraps(func)
+    async def wrapper(self, *args, **kwargs):
+        # Extract request if present (first arg or keyword arg)
+        request = None
+        if args:
+            request = args[0]
+        elif "request" in kwargs:
+            request = kwargs["request"]
+
+        # Get processor components (auto-initialized by BaseProcessor)
+        request_id_middleware = getattr(self, "request_id_middleware", None)
+        request_tracker = getattr(self, "request_tracker", None)
+        otel = getattr(self, "otel", None)
+        error_classifier = getattr(self, "error_classifier", None)
+
+        # 1. Generate request ID
+        request_id = None
+        if request_id_middleware:
+            request_id = request_id_middleware.generate_id()
+            # Store in request for retrieval
+            if request is not None and hasattr(request, "__setitem__"):
+                request["request_id"] = request_id
+            elif request is not None and hasattr(request, "__dict__"):
+                request.request_id = request_id
+            logger.debug(f"Generated request ID: {request_id}")
+
+        # 2. Track request
+        request_tracker_ctx = None
+        if request_tracker:
+            request_tracker_ctx = request_tracker.track_request(request_id)
+            await request_tracker_ctx.__aenter__()
+            logger.debug(f"Started tracking request: {request_id}")
+
+        # 3. Create OpenTelemetry span
+        span_ctx = None
+        if otel:
+            span_name = f"{self.__class__.__name__}.{func.__name__}"
+            attributes = {
+                "function": func.__name__,
+                "class": self.__class__.__name__,
+            }
+            if request_id:
+                attributes["request.id"] = request_id
+            if request is not None and hasattr(request, "path"):
+                attributes["endpoint"] = str(request.path)
+            if request is not None and hasattr(request, "method"):
+                attributes["http.method"] = str(request.method)
+
+            span_ctx = otel.create_span(span_name, attributes=attributes)
+            span_ctx.__enter__()
+            logger.debug(f"Created span: {span_name}")
+
+        try:
+            # Execute handler
+            result = await func(self, *args, **kwargs)
+
+            # Mark request as successful
+            if request_tracker_ctx:
+                await request_tracker_ctx.__aexit__(None, None, None)
+                logger.debug(f"Request completed successfully: {request_id}")
+
+            if span_ctx:
+                span_ctx.__exit__(None, None, None)
+
+            return result
+
+        except Exception as e:
+            # Classify error
+            if error_classifier:
+                error_info = error_classifier.classify(e)
+                logger.warning(
+                    f"Handler error: {error_info.error_type.value} - {e}",
+                    extra={
+                        "request_id": request_id,
+                        "error_type": error_info.error_type.value,
+                        "is_transient": error_info.is_transient,
+                    },
+                )
+            else:
+                logger.warning(f"Handler error: {e}", extra={"request_id": request_id})
+
+            # Mark request as failed
+            if request_tracker_ctx:
+                await request_tracker_ctx.__aexit__(type(e), e, None)
+
+            # Record exception in span
+            if span_ctx:
+                span_ctx.__exit__(type(e), e, None)
+
+            raise
+
+    return wrapper

dory/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Dory SDK CLI tools."""
+
+from dory.cli.main import main
+
+__all__ = ["main"]

dory/cli/main.py

@@ -0,0 +1,290 @@
+"""
+Dory SDK CLI - Command line tools for Dory SDK.
+
+Provides commands for:
+- Generating Kubernetes manifests (RBAC, Deployment, etc.)
+- Initializing new Dory projects
+- Validating configuration
+
+Usage:
+    dory init my-app --image my-app:latest
+    dory generate k8s --name my-app --image my-app:latest
+    dory validate
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from dory.cli.templates import (
+    generate_rbac,
+    generate_deployment,
+    generate_pod,
+    generate_all,
+    generate_dockerfile,
+    generate_processor_template,
+)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Initialize a new Dory project."""
+    name = args.name
+    output_dir = Path(args.output or ".")
+
+    print(f"Initializing Dory project: {name}")
+
+    # Create directories
+    k8s_dir = output_dir / "k8s"
+    k8s_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate files
+    files = {
+        "main.py": generate_processor_template(name),
+        "Dockerfile": generate_dockerfile(name),
+        "k8s/rbac.yaml": generate_rbac(name, args.namespace),
+        "k8s/deployment.yaml": generate_deployment(
+            name=name,
+            image=args.image or f"{name}:latest",
+            namespace=args.namespace,
+            replicas=args.replicas,
+            health_port=args.health_port,
+            app_port=args.app_port,
+        ),
+    }
+
+    for filename, content in files.items():
+        filepath = output_dir / filename
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+
+        if filepath.exists() and not args.force:
+            print(f"  Skipping {filename} (already exists, use --force to overwrite)")
+            continue
+
+        filepath.write_text(content)
+        print(f"  Created {filename}")
+
+    print()
+    print("Next steps:")
+    print(f"  1. Edit main.py with your processor logic")
+    print(f"  2. Build: docker build -t {name}:latest .")
+    print(f"  3. Deploy: kubectl apply -f k8s/")
+    print()
+
+    return 0
+
+
+def cmd_generate(args: argparse.Namespace) -> int:
+    """Generate Kubernetes manifests."""
+    output_dir = Path(args.output or "k8s")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    name = args.name
+    image = args.image or f"{name}:latest"
+    namespace = args.namespace
+
+    if args.type == "rbac":
+        content = generate_rbac(name, namespace)
+        filename = "rbac.yaml"
+    elif args.type == "deployment":
+        content = generate_deployment(
+            name=name,
+            image=image,
+            namespace=namespace,
+            replicas=args.replicas,
+            health_port=args.health_port,
+            app_port=args.app_port,
+        )
+        filename = "deployment.yaml"
+    elif args.type == "pod":
+        content = generate_pod(
+            name=name,
+            image=image,
+            namespace=namespace,
+            health_port=args.health_port,
+            app_port=args.app_port,
+        )
+        filename = "pod.yaml"
+    elif args.type == "all":
+        content = generate_all(
+            name=name,
+            image=image,
+            namespace=namespace,
+            replicas=args.replicas,
+            health_port=args.health_port,
+            app_port=args.app_port,
+        )
+        filename = "all.yaml"
+    else:
+        print(f"Unknown type: {args.type}")
+        return 1
+
+    filepath = output_dir / filename
+
+    if filepath.exists() and not args.force:
+        print(f"File {filepath} already exists. Use --force to overwrite.")
+        return 1
+
+    filepath.write_text(content)
+    print(f"Generated: {filepath}")
+
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Validate Dory configuration."""
+    from dory.config.loader import ConfigLoader
+
+    config_file = args.config
+
+    try:
+        loader = ConfigLoader(config_file=config_file)
+        config = loader.load()
+        print("Configuration is valid!")
+        print()
+        print("Current settings:")
+        for key, value in config.model_dump().items():
+            print(f"  {key}: {value}")
+        return 0
+    except Exception as e:
+        print(f"Configuration error: {e}")
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="dory",
+        description="Dory SDK CLI - Tools for building stateful Kubernetes processors",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 1.0.0",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # init command
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize a new Dory project",
+    )
+    init_parser.add_argument(
+        "name",
+        help="Project/app name",
+    )
+    init_parser.add_argument(
+        "-o", "--output",
+        help="Output directory (default: current directory)",
+    )
+    init_parser.add_argument(
+        "-i", "--image",
+        help="Docker image name (default: <name>:latest)",
+    )
+    init_parser.add_argument(
+        "-n", "--namespace",
+        default="default",
+        help="Kubernetes namespace (default: default)",
+    )
+    init_parser.add_argument(
+        "--replicas",
+        type=int,
+        default=1,
+        help="Number of replicas (default: 1)",
+    )
+    init_parser.add_argument(
+        "--health-port",
+        type=int,
+        default=8080,
+        help="Health server port (default: 8080)",
+    )
+    init_parser.add_argument(
+        "--app-port",
+        type=int,
+        default=8081,
+        help="Application port (default: 8081)",
+    )
+    init_parser.add_argument(
+        "-f", "--force",
+        action="store_true",
+        help="Overwrite existing files",
+    )
+    init_parser.set_defaults(func=cmd_init)
+
+    # generate command
+    gen_parser = subparsers.add_parser(
+        "generate",
+        help="Generate Kubernetes manifests",
+    )
+    gen_parser.add_argument(
+        "type",
+        choices=["rbac", "deployment", "pod", "all"],
+        help="Type of manifest to generate",
+    )
+    gen_parser.add_argument(
+        "-n", "--name",
+        required=True,
+        help="Application name",
+    )
+    gen_parser.add_argument(
+        "-i", "--image",
+        help="Docker image (default: <name>:latest)",
+    )
+    gen_parser.add_argument(
+        "--namespace",
+        default="default",
+        help="Kubernetes namespace (default: default)",
+    )
+    gen_parser.add_argument(
+        "--replicas",
+        type=int,
+        default=1,
+        help="Number of replicas (default: 1)",
+    )
+    gen_parser.add_argument(
+        "--health-port",
+        type=int,
+        default=8080,
+        help="Health server port (default: 8080)",
+    )
+    gen_parser.add_argument(
+        "--app-port",
+        type=int,
+        default=8081,
+        help="Application port (default: 8081)",
+    )
+    gen_parser.add_argument(
+        "-o", "--output",
+        default="k8s",
+        help="Output directory (default: k8s)",
+    )
+    gen_parser.add_argument(
+        "-f", "--force",
+        action="store_true",
+        help="Overwrite existing files",
+    )
+    gen_parser.set_defaults(func=cmd_generate)
+
+    # validate command
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate Dory configuration",
+    )
+    validate_parser.add_argument(
+        "-c", "--config",
+        help="Path to config file (default: dory.yaml)",
+    )
+    validate_parser.set_defaults(func=cmd_validate)
+
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())