julee 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

julee/contrib/polling/domain/__init__.py

@@ -0,0 +1,17 @@
+"""
+Domain layer for the polling contrib module.
+
+This module contains the core domain models, services, and business rules
+for the polling contrib module. It defines the fundamental concepts and
+protocols that govern polling operations.
+"""
+
+from .models import PollingConfig, PollingProtocol, PollingResult
+from .services import PollerService
+
+__all__ = [
+    "PollingConfig",
+    "PollingProtocol",
+    "PollingResult",
+    "PollerService",
+]

julee/contrib/polling/domain/models/__init__.py

@@ -0,0 +1,13 @@
+"""
+Polling domain models.
+
+This module contains the core domain models for the polling contrib module.
+"""
+
+from .polling_config import PollingConfig, PollingProtocol, PollingResult
+
+__all__ = [
+    "PollingConfig",
+    "PollingProtocol",
+    "PollingResult",
+]

julee/contrib/polling/domain/models/polling_config.py

@@ -0,0 +1,39 @@
+"""
+Polling domain models.
+
+This module contains the core domain models for polling operations,
+including configuration and result models.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PollingProtocol(str, Enum):
+    """Supported polling protocols."""
+
+    HTTP = "http"
+
+
+class PollingConfig(BaseModel):
+    """Configuration for a polling operation."""
+
+    endpoint_identifier: str = Field(description="Unique identifier for this endpoint")
+    polling_protocol: PollingProtocol
+    connection_params: dict[str, Any] = Field(default_factory=dict)
+    polling_params: dict[str, Any] = Field(default_factory=dict)
+    timeout_seconds: int | None = Field(default=30)
+
+
+class PollingResult(BaseModel):
+    """Result of a polling operation."""
+
+    success: bool
+    content: bytes
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    polled_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    content_hash: str | None = None
+    error_message: str | None = None

julee/contrib/polling/domain/services/__init__.py

@@ -0,0 +1,11 @@
+"""
+Polling domain services.
+
+This module contains the service protocols for the polling contrib module.
+"""
+
+from .poller import PollerService
+
+__all__ = [
+    "PollerService",
+]

julee/contrib/polling/domain/services/poller.py

@@ -0,0 +1,39 @@
+"""
+PollerService protocol for external endpoint polling operations.
+
+This module defines the PollerService protocol that handles interactions
+with various types of external endpoints for data polling and change detection.
+
+Concrete implementations of this protocol are provided for different polling
+mechanisms and are created via factory functions.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models import PollingConfig, PollingResult
+
+
+@runtime_checkable
+class PollerService(Protocol):
+    """
+    Protocol for polling external endpoints for data.
+
+    This protocol defines the interface for a poller service that can perform
+    individual poll operations on different endpoint types. Implementations
+    handle the specifics of different polling mechanisms.
+    """
+
+    async def poll_endpoint(self, config: PollingConfig) -> PollingResult:
+        """
+        Poll an endpoint according to the provided configuration.
+
+        Args:
+            config: PollingConfig containing endpoint details and parameters
+
+        Returns:
+            PollingResult with success status, content, and metadata
+
+        Raises:
+            PollingError: When polling operation fails
+        """
+        ...

julee/contrib/polling/infrastructure/__init__.py

@@ -0,0 +1,15 @@
+"""
+Infrastructure layer for the polling contrib module.
+
+This module contains the concrete implementations of domain protocols
+and external system integrations for the polling contrib module.
+"""
+
+from .services import HttpPollerService
+from .temporal import TemporalPollerService, WorkflowPollerServiceProxy
+
+__all__ = [
+    "HttpPollerService",
+    "TemporalPollerService",
+    "WorkflowPollerServiceProxy",
+]

julee/contrib/polling/infrastructure/services/__init__.py

@@ -0,0 +1,12 @@
+"""
+Infrastructure services for the polling contrib module.
+
+This module contains the concrete implementations of domain services
+for the polling contrib module.
+"""
+
+from .polling import HttpPollerService
+
+__all__ = [
+    "HttpPollerService",
+]

julee/contrib/polling/infrastructure/services/polling/__init__.py

@@ -0,0 +1,12 @@
+"""
+Polling infrastructure services.
+
+This module contains the concrete implementations of polling services
+for different protocols and mechanisms.
+"""
+
+from .http import HttpPollerService
+
+__all__ = [
+    "HttpPollerService",
+]

julee/contrib/polling/infrastructure/services/polling/http/__init__.py

@@ -0,0 +1,12 @@
+"""
+HTTP polling implementation.
+
+This module provides HTTP-specific polling functionality for the polling
+contrib module.
+"""
+
+from .http_poller_service import HttpPollerService
+
+__all__ = [
+    "HttpPollerService",
+]

julee/contrib/polling/infrastructure/services/polling/http/http_poller_service.py

@@ -0,0 +1,80 @@
+"""
+HTTP implementation of the PollerService protocol.
+
+This module provides HTTP-specific polling functionality including
+REST API endpoints, webhooks, and other HTTP-based data sources.
+"""
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from julee.contrib.polling.domain.models import PollingConfig, PollingResult
+from julee.contrib.polling.domain.services import PollerService
+
+
+class HttpPollerService(PollerService):
+    """HTTP implementation of PollerService protocol."""
+
+    def __init__(self) -> None:
+        self.client = httpx.AsyncClient()
+
+    async def poll_endpoint(self, config: PollingConfig) -> PollingResult:
+        """Poll an HTTP endpoint."""
+        try:
+            # Extract HTTP-specific params
+            url = config.connection_params["url"]
+            headers = config.connection_params.get("headers", {})
+            method = config.polling_params.get("method", "GET")
+            auth_params = config.connection_params.get("auth", {})
+
+            # Make HTTP request
+            response = await self.client.request(
+                method=method,
+                url=url,
+                headers=headers,
+                timeout=config.timeout_seconds,
+                **auth_params,
+            )
+
+            content = response.content
+            content_hash = hashlib.sha256(content).hexdigest()
+
+            # Only consider 2xx status codes as successful
+            success = 200 <= response.status_code < 300
+
+            return PollingResult(
+                success=success,
+                content=content if success else b"",
+                content_hash=content_hash if success else None,
+                polled_at=datetime.now(timezone.utc),
+                metadata={
+                    "status_code": response.status_code,
+                    "response_headers": dict(response.headers),
+                    "url": url,
+                    "method": method,
+                },
+            )
+
+        except Exception as e:
+            return PollingResult(
+                success=False,
+                content=b"",
+                error_message=str(e),
+                polled_at=datetime.now(timezone.utc),
+                metadata={"error_type": type(e).__name__},
+            )
+
+    async def close(self) -> None:
+        """Close the HTTP client connection."""
+        await self.client.aclose()
+
+    async def __aenter__(self) -> "HttpPollerService":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()

julee/contrib/polling/infrastructure/temporal/__init__.py

@@ -0,0 +1,20 @@
+"""
+Temporal infrastructure for the polling contrib module.
+
+This module contains the temporal-specific implementations for the polling
+contrib module, including activity registrations, workflow proxies, and
+activity name constants.
+
+This keeps all polling-temporal integration within the contrib module,
+maintaining proper dependency direction (contrib imports from core, not vice versa).
+"""
+
+from .activities import TemporalPollerService
+from .activity_names import POLLING_SERVICE_ACTIVITY_BASE
+from .proxies import WorkflowPollerServiceProxy
+
+__all__ = [
+    "TemporalPollerService",
+    "POLLING_SERVICE_ACTIVITY_BASE",
+    "WorkflowPollerServiceProxy",
+]

julee/contrib/polling/infrastructure/temporal/activities.py

@@ -0,0 +1,42 @@
+"""
+Temporal activities for the polling contrib module.
+
+This module contains the temporal activity implementations for polling operations.
+These activities are registered with Temporal and can be called from workflows
+to perform durable polling operations.
+
+By keeping these activities within the contrib module, we maintain proper
+dependency direction - contrib modules define their own temporal integration
+without requiring the core framework to know about specific contrib modules.
+"""
+
+import logging
+
+from julee.util.temporal.decorators import temporal_activity_registration
+
+from ..services.polling.http import HttpPollerService
+from .activity_names import POLLING_SERVICE_ACTIVITY_BASE
+
+
+@temporal_activity_registration(POLLING_SERVICE_ACTIVITY_BASE)
+class TemporalPollerService(HttpPollerService):
+    """
+    Temporal activity wrapper for PollerService operations.
+
+    This class wraps the HttpPollerService to make it compatible with Temporal
+    activities. It inherits all the polling functionality while being registered
+    as a Temporal activity that can be called from workflows.
+
+    The temporal activity registration provides durability, retries, and
+    observability for polling operations within workflow contexts.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.logger: logging.Logger = logging.getLogger(__name__)
+
+
+# Export the temporal activity class
+__all__ = [
+    "TemporalPollerService",
+]

julee/contrib/polling/infrastructure/temporal/activity_names.py

@@ -0,0 +1,20 @@
+"""
+Activity name constants for the polling contrib module.
+
+This module contains activity name base constants specific to the polling
+contrib module. These constants are used for registering polling activities
+and calling them from workflow proxies.
+
+By keeping these constants within the contrib module, we maintain proper
+dependency direction - contrib modules define their own temporal integration
+without requiring the core framework to know about specific contrib modules.
+"""
+
+# Activity name base for polling service activities
+POLLING_SERVICE_ACTIVITY_BASE = "julee.contrib.polling"
+
+
+# Export all constants
+__all__ = [
+    "POLLING_SERVICE_ACTIVITY_BASE",
+]

julee/contrib/polling/infrastructure/temporal/proxies.py

@@ -0,0 +1,45 @@
+"""
+Workflow-safe proxy classes for the polling contrib module.
+
+This module contains @temporal_workflow_proxy decorated classes that
+delegate to Temporal activities from within workflows. These classes are
+isolated from backend imports to avoid Temporal's workflow sandbox
+restrictions.
+
+The proxy classes automatically generate methods that call
+workflow.execute_activity() with the appropriate activity names, timeouts,
+and retry policies.
+
+This keeps all polling-temporal integration within the contrib module,
+maintaining proper dependency direction (contrib imports from core, not vice versa).
+"""
+
+from julee.util.temporal.decorators import temporal_workflow_proxy
+
+from ...domain.services import PollerService
+from .activity_names import POLLING_SERVICE_ACTIVITY_BASE
+
+
+@temporal_workflow_proxy(
+    activity_base=POLLING_SERVICE_ACTIVITY_BASE,
+    default_timeout_seconds=60,  # Shorter timeout for HTTP calls
+    retry_methods=["poll_endpoint"],  # Only poll_endpoint needs retries
+)
+class WorkflowPollerServiceProxy(PollerService):
+    """
+    Workflow implementation of PollerService that calls activities.
+    All methods are automatically generated by the @temporal_workflow_proxy
+    decorator.
+
+    This proxy allows workflows to call polling operations through Temporal
+    activities, providing durability and retry capabilities for polling
+    operations within workflow contexts.
+    """
+
+    pass
+
+
+# Export the workflow proxy class
+__all__ = [
+    "WorkflowPollerServiceProxy",
+]

julee/contrib/polling/tests/__init__.py

@@ -0,0 +1,6 @@
+"""
+Tests for the polling contrib module.
+
+This module contains the test suite for the polling contrib module,
+including unit tests, integration tests, and test fixtures.
+"""

julee/contrib/polling/tests/unit/__init__.py

@@ -0,0 +1,6 @@
+"""
+Unit tests for the polling contrib module.
+
+This module contains unit tests for the polling contrib module,
+testing individual components in isolation.
+"""

julee/contrib/polling/tests/unit/infrastructure/__init__.py

@@ -0,0 +1,7 @@
+"""
+Infrastructure layer tests for the polling contrib module.
+
+This module contains unit tests for the infrastructure implementations
+of the polling contrib module, including service implementations and
+external system integrations.
+"""

julee/contrib/polling/tests/unit/infrastructure/services/__init__.py

@@ -0,0 +1,6 @@
+"""
+Services tests for the polling contrib module infrastructure.
+
+This module contains unit tests for service implementations in the
+infrastructure layer of the polling contrib module.
+"""

julee/contrib/polling/tests/unit/infrastructure/services/polling/__init__.py

@@ -0,0 +1,6 @@
+"""
+Polling services tests for the polling contrib module infrastructure.
+
+This module contains unit tests for polling service implementations in the
+infrastructure layer, including HTTP and other protocol-specific pollers.
+"""

julee/contrib/polling/tests/unit/infrastructure/services/polling/http/__init__.py

@@ -0,0 +1,7 @@
+"""
+HTTP polling service tests for the polling contrib module infrastructure.
+
+This module contains unit tests for the HTTP-specific polling service
+implementation in the infrastructure layer, testing HTTP endpoint polling
+functionality, error handling, and response processing.
+"""

julee/contrib/polling/tests/unit/infrastructure/services/polling/http/test_http_poller_service.py

@@ -0,0 +1,163 @@
+"""
+Unit tests for HttpPollerService.
+
+This module tests the HTTP poller service implementation using httpx's
+built-in MockTransport for mocking HTTP responses. Tests use table-based
+parametrization for comprehensive coverage of different scenarios.
+"""
+
+import hashlib
+
+import httpx
+import pytest
+
+from julee.contrib.polling.domain.models import PollingConfig, PollingProtocol
+from julee.contrib.polling.infrastructure.services.polling.http import (
+    HttpPollerService,
+)
+
+
+class TestHttpPollerServicePollEndpoint:
+    """Test the poll_endpoint method of HttpPollerService."""
+
+    @pytest.mark.parametrize(
+        "status_code,content,expected_success,description",
+        [
+            (200, b"test content", True, "HTTP 200 with content"),
+            (201, b"created", True, "HTTP 201 created"),
+            (204, b"", True, "HTTP 204 no content"),
+            (299, b"success boundary", True, "HTTP 299 (2xx boundary)"),
+            (300, b"redirect", False, "HTTP 300 redirect (not 2xx)"),
+            (404, b"not found", False, "HTTP 404 client error"),
+            (418, b"teapot", False, "HTTP 418 client error"),
+            (500, b"server error", False, "HTTP 500 server error"),
+            (502, b"bad gateway", False, "HTTP 502 bad gateway"),
+            (503, b"unavailable", False, "HTTP 503 service unavailable"),
+        ],
+    )
+    @pytest.mark.asyncio
+    async def test_poll_endpoint_status_codes(
+        self, status_code: int, content: bytes, expected_success: bool, description: str
+    ):
+        """Test poll_endpoint with various HTTP status codes."""
+
+        def handler(request):
+            return httpx.Response(status_code=status_code, content=content)
+
+        mock_transport = httpx.MockTransport(handler)
+
+        async with HttpPollerService() as service:
+            service.client = httpx.AsyncClient(transport=mock_transport)
+
+            config = PollingConfig(
+                endpoint_identifier="test-api",
+                polling_protocol=PollingProtocol.HTTP,
+                connection_params={"url": "https://example.com/api"},
+            )
+
+            result = await service.poll_endpoint(config)
+
+            assert result.success == expected_success, f"Failed for {description}"
+            if expected_success:
+                assert result.content == content
+                assert result.content_hash is not None
+            else:
+                assert result.content == b""
+                assert result.content_hash is None
+            assert result.metadata["status_code"] == status_code
+
+    @pytest.mark.parametrize(
+        "exception_type,description",
+        [
+            (httpx.ConnectTimeout, "Connection timeout"),
+            (httpx.ReadTimeout, "Read timeout"),
+            (httpx.ConnectError, "Connection error"),
+            (httpx.RequestError, "Generic request error"),
+        ],
+    )
+    @pytest.mark.asyncio
+    async def test_poll_endpoint_network_errors(
+        self, exception_type: type, description: str
+    ):
+        """Test poll_endpoint with various network errors."""
+
+        def handler(request):
+            raise exception_type("Mock network error")
+
+        mock_transport = httpx.MockTransport(handler)
+
+        async with HttpPollerService() as service:
+            service.client = httpx.AsyncClient(transport=mock_transport)
+
+            config = PollingConfig(
+                endpoint_identifier="test-api",
+                polling_protocol=PollingProtocol.HTTP,
+                connection_params={"url": "https://example.com/api"},
+            )
+
+            result = await service.poll_endpoint(config)
+
+            assert result.success is False, f"Should fail for {description}"
+            assert result.content == b""
+            assert "Mock network error" in result.error_message
+            assert result.metadata["error_type"] == exception_type.__name__
+
+    @pytest.mark.asyncio
+    async def test_poll_endpoint_content_hash_generation(self):
+        """Test that poll_endpoint generates correct content hash."""
+        test_content = b"test content for hashing"
+        expected_hash = hashlib.sha256(test_content).hexdigest()
+
+        def handler(request):
+            return httpx.Response(status_code=200, content=test_content)
+
+        mock_transport = httpx.MockTransport(handler)
+
+        async with HttpPollerService() as service:
+            service.client = httpx.AsyncClient(transport=mock_transport)
+
+            config = PollingConfig(
+                endpoint_identifier="test-api",
+                polling_protocol=PollingProtocol.HTTP,
+                connection_params={"url": "https://example.com/api"},
+            )
+
+            result = await service.poll_endpoint(config)
+
+            assert result.success is True
+            assert result.content == test_content
+            assert result.content_hash == expected_hash
+
+    @pytest.mark.asyncio
+    async def test_poll_endpoint_uses_config_parameters(self):
+        """Test that poll_endpoint uses configuration parameters correctly."""
+        captured_request = None
+
+        def handler(request):
+            nonlocal captured_request
+            captured_request = request
+            return httpx.Response(status_code=200, content=b"success")
+
+        mock_transport = httpx.MockTransport(handler)
+
+        async with HttpPollerService() as service:
+            service.client = httpx.AsyncClient(transport=mock_transport)
+
+            config = PollingConfig(
+                endpoint_identifier="test-api",
+                polling_protocol=PollingProtocol.HTTP,
+                connection_params={
+                    "url": "https://api.example.com/data",
+                    "headers": {"Authorization": "Bearer token123"},
+                },
+                polling_params={"method": "POST"},
+                timeout_seconds=30,
+            )
+
+            result = await service.poll_endpoint(config)
+
+            assert result.success is True
+            assert captured_request is not None
+            assert str(captured_request.url) == "https://api.example.com/data"
+            assert captured_request.method == "POST"
+            assert captured_request.headers["Authorization"] == "Bearer token123"

julee/docs/__init__.py

@@ -0,0 +1,5 @@
+"""Julee documentation utilities.
+
+This package provides Sphinx extensions and utilities for documenting
+Julee-based solutions using Human-Centered Design patterns.
+"""