exonware-xwapi 0.9.0.2__py3-none-any.whl

exonware/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

exonware/xwapi/__init__.py

@@ -0,0 +1,227 @@
+#exonware/xwapi/src/exonware/xwapi/__init__.py
+"""
+xwapi: Entity-to-Web-API Conversion Library
+Company: eXonware.com
+Author: eXonware Backend Team
+Email: connect@exonware.com
+Version: 0.9.0.2
+"""
+# =============================================================================
+# XWLAZY — GUIDE_00_MASTER: config_package_lazy_install_enabled (EARLY)
+# =============================================================================
+# Dependency: exonware-xwlazy ([lazy] extra). Canonical import: exonware.xwlazy
+try:
+    from exonware.xwlazy import config_package_lazy_install_enabled
+
+    config_package_lazy_install_enabled(
+        __package__ or "exonware.xwapi",
+        enabled=True,
+        mode="smart",
+    )
+except ImportError:
+    # xwlazy not installed — omit [lazy] extra or install exonware-xwlazy for lazy mode.
+    pass
+# Core imports - safe, no dependencies
+from exonware.xwapi.version import __version__, __author__, __email__
+# Config imports - safe, minimal dependencies
+from exonware.xwapi.config import XWAPIConfig
+# Base imports - safe, only imports contracts
+# Import from xwapi.base for consistency (these re-export from server/client/base for backward compatibility)
+from exonware.xwapi.base import AApiServer, AApiAgent, AApiServicesProvider
+# Errors - direct import (no circular dependency since errors.py doesn't import from __init__.py)
+from exonware.xwapi.errors import (
+    XWAPIError,
+    ValidationError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    InternalError,
+    OpenAPIGenerationError,
+    FastAPICreationError,
+    EntityMappingError,
+    OAuth2ConfigurationError,
+    EndpointConfigurationError,
+    ServerLifecycleError,
+    StorageUnavailableError,
+    ServicePausedError,
+    create_error_response,
+    xwapi_error_to_http_parts,
+    http_status_to_xwapi_error,
+    get_http_status_code,
+    error_to_http_response,
+    get_error_headers,
+    # HTTP Status Code Constants
+    HTTP_200_OK,
+    HTTP_201_CREATED,
+    HTTP_202_ACCEPTED,
+    HTTP_204_NO_CONTENT,
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_403_FORBIDDEN,
+    HTTP_404_NOT_FOUND,
+    HTTP_405_METHOD_NOT_ALLOWED,
+    HTTP_409_CONFLICT,
+    HTTP_422_UNPROCESSABLE_ENTITY,
+    HTTP_429_TOO_MANY_REQUESTS,
+    HTTP_500_INTERNAL_SERVER_ERROR,
+    HTTP_501_NOT_IMPLEMENTED,
+    HTTP_502_BAD_GATEWAY,
+    HTTP_503_SERVICE_UNAVAILABLE,
+    HTTP_504_GATEWAY_TIMEOUT,
+)
+# Engine system - engine-agnostic: only interfaces and registry imported
+# Specific engines (FastAPIServerEngine, etc.) should be imported directly from their modules
+from exonware.xwapi.server.engines import (
+    IApiServerEngine,
+    AApiServerEngineBase,
+    ApiServerEngineRegistry,
+    api_server_engine_registry,
+)
+# App factory - direct import
+from exonware.xwapi.common.app import (
+    create_app,
+    register_module,
+    add_version_router,
+    add_openapi_endpoints,
+)
+# Query parameter parsing is handled directly in engine implementations
+# Use XWQuery directly for query execution - no wrapper needed
+# Middleware - direct import
+from exonware.xwapi.server.middleware import (
+    trace_middleware,
+    tenant_middleware,
+    rate_limit_middleware,
+    auth_middleware,
+    observability_middleware,
+)
+# OpenAPI - direct import
+from exonware.xwapi.common.openapi import (
+    merge_openapi_schemas,
+    validate_openapi_schema,
+    export_openapi_schema,
+    add_openapi_metadata,
+    get_openapi_version,
+)
+# Server - direct import
+from exonware.xwapi.server.xwserver import XWApiServer
+from exonware.xwapi.server.pipeline import ActionPipelineManager, BackgroundWorker, InMemoryOutboxStore
+from exonware.xwapi.providers import (
+    LocalAuthProvider,
+    XWAuthLibraryProvider,
+    InMemoryStorageProvider,
+    XWStorageProvider,
+    InMemoryPaymentProvider,
+)
+from exonware.xwapi.token_management import APITokenManager
+from exonware.xwapi.contracts import IApiServer
+# Agent - direct import
+from exonware.xwapi.client.xwclient import XWApiAgent
+from exonware.xwapi.contracts import IApiAgent, IApiServicesProvider
+from exonware.xwapi.contracts import IAuthProvider, IStorageProvider, IPaymentProvider
+# Agent engines - direct import
+from exonware.xwapi.client.engines import (
+    IApiAgentEngine,
+    AgentType,
+    ApiAgentEngineRegistry,
+    api_agent_engine_registry,
+    NativeAgentEngine,
+)
+# Serialization - use XWData/XWSystem directly, no wrapper needed
+# Facade - direct import (import last to ensure all dependencies are loaded)
+from exonware.xwapi.facade import XWAPI
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    # Facade
+    "XWAPI",
+    "XWAPIConfig",
+    # App factory
+    "create_app",
+    "register_module",
+    "add_version_router",
+    "add_openapi_endpoints",
+    # Errors
+    "XWAPIError",
+    "ValidationError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InternalError",
+    "OpenAPIGenerationError",
+    "FastAPICreationError",
+    "EntityMappingError",
+    "OAuth2ConfigurationError",
+    "EndpointConfigurationError",
+    "ServerLifecycleError",
+    "StorageUnavailableError",
+    "ServicePausedError",
+    "create_error_response",
+    "xwapi_error_to_http_parts",
+    "http_status_to_xwapi_error",
+    "get_http_status_code",
+    "error_to_http_response",
+    "get_error_headers",
+    # HTTP Status Code Constants
+    "HTTP_200_OK",
+    "HTTP_201_CREATED",
+    "HTTP_202_ACCEPTED",
+    "HTTP_204_NO_CONTENT",
+    "HTTP_400_BAD_REQUEST",
+    "HTTP_401_UNAUTHORIZED",
+    "HTTP_403_FORBIDDEN",
+    "HTTP_404_NOT_FOUND",
+    "HTTP_405_METHOD_NOT_ALLOWED",
+    "HTTP_409_CONFLICT",
+    "HTTP_422_UNPROCESSABLE_ENTITY",
+    "HTTP_429_TOO_MANY_REQUESTS",
+    "HTTP_500_INTERNAL_SERVER_ERROR",
+    "HTTP_501_NOT_IMPLEMENTED",
+    "HTTP_502_BAD_GATEWAY",
+    "HTTP_503_SERVICE_UNAVAILABLE",
+    "HTTP_504_GATEWAY_TIMEOUT",
+    # Serialization - use XWData/XWSystem directly
+    # Server management - XWApiServer (extends AApiServer)
+    "XWApiServer",
+    "ActionPipelineManager",
+    "BackgroundWorker",
+    "InMemoryOutboxStore",
+    "APITokenManager",
+    "LocalAuthProvider",
+    "XWAuthLibraryProvider",
+    "InMemoryStorageProvider",
+    "XWStorageProvider",
+    "InMemoryPaymentProvider",
+    "AApiServer",
+    "AApiAgent",
+    "AApiServicesProvider",
+    "IApiServer",
+    "IAuthProvider",
+    "IStorageProvider",
+    "IPaymentProvider",
+    "IApiServicesProvider",
+    # Agent system
+    "XWApiAgent",
+    "IApiAgent",
+    # Engine system (engine-agnostic: engines imported from their modules)
+    "IApiServerEngine",
+    "AApiServerEngineBase",
+    "ApiServerEngineRegistry",
+    "api_server_engine_registry",
+    # Query - use XWQuery directly
+    # Action - use XWAction engines directly
+    # Middleware
+    "trace_middleware",
+    "tenant_middleware",
+    "rate_limit_middleware",
+    "auth_middleware",
+    "observability_middleware",
+    # OpenAPI
+    "merge_openapi_schemas",
+    "validate_openapi_schema",
+    "export_openapi_schema",
+    "add_openapi_metadata",
+    "get_openapi_version",
+]

exonware/xwapi/action.py

@@ -0,0 +1,46 @@
+#exonware/xwapi/action.py
+"""
+xwapi action helpers: register_action_endpoint, create_action_context_dependency.
+Thin wrapper over xwaction FastAPIActionEngine. GUIDE_TEST root-cause fix.
+Company: eXonware.com
+Author: eXonware Backend Team
+Email: connect@exonware.com
+Version: 0.9.0.2
+"""
+
+from __future__ import annotations
+from typing import Any
+
+
+def register_action_endpoint(
+    app: Any,
+    action: Any,
+    *,
+    path: str | None = None,
+    method: str = "POST",
+) -> bool:
+    """Register an XWAction as a FastAPI endpoint. Uses xwaction FastAPIActionEngine."""
+    try:
+        from exonware.xwaction.engines import action_engine_registry
+        from exonware.xwaction.engines.fastapi import FastAPIActionEngine
+    except ImportError:
+        return False
+    engine = action_engine_registry.get_engine("fastapi")
+    if not engine:
+        engine = FastAPIActionEngine()
+        action_engine_registry.register(engine)
+    return engine.register_action(action, app, path=path or f"/{getattr(action, 'api_name', 'unknown')}", method=method)
+
+
+def create_action_context_dependency(request: Any) -> Any:
+    """FastAPI Depends(): build ActionContext from Request (trace_id, path, method)."""
+    from exonware.xwaction.context import ActionContext
+    trace_id = getattr(getattr(request, "state", None), "trace_id", None)
+    path = getattr(getattr(request, "url", None), "path", "unknown")
+    method = getattr(request, "method", "GET")
+    return ActionContext(
+        actor="request",
+        source=path,
+        trace_id=trace_id,
+        metadata={"method": method, "path": path},
+    )

exonware/xwapi/base.py

@@ -0,0 +1,357 @@
+#exonware/xwapi/src/exonware/xwapi/base.py
+"""
+Abstract base classes for xwapi library.
+Company: eXonware.com
+Author: eXonware Backend Team
+Email: connect@exonware.com
+Version: 0.9.0.2
+"""
+
+from typing import Any, Optional
+from abc import ABC, abstractmethod
+from datetime import datetime
+from exonware.xwaction.base import AActionsProvider
+from exonware.xwapi.contracts import (
+    IAPIEndpoint,
+    IAPIGenerator,
+    IOAuth2Provider,
+    IApiServer,
+    IApiAgent,
+    IApiServicesProvider,
+    HTTPMethod,
+    SecurityType,
+)
+
+
+class AApiServicesProvider(IApiServicesProvider, AActionsProvider, ABC):
+    """
+    Abstract base for API-level providers that expose @XWAction commands.
+    Extends AActionsProvider (xwaction); used by command providers (xwbots).
+    """
+
+    pass
+
+
+class AAPIEndpoint(ABC, IAPIEndpoint):
+    """Abstract base class for API endpoint configuration implementing IAPIEndpoint interface."""
+
+    def __init__(
+        self,
+        endpoint_id: str,
+        path: str,
+        method: HTTPMethod,
+        entity_type: str,
+        action_name: Optional[str] = None,
+    ):
+        self.endpoint_id = endpoint_id
+        self.path = path
+        self.method = method
+        self.entity_type = entity_type
+        self.action_name = action_name
+
+    def get_path(self) -> str:
+        """Get endpoint path."""
+        return self.path
+
+    def get_method(self) -> HTTPMethod:
+        """Get HTTP method."""
+        return self.method
+
+    def get_entity_type(self) -> str:
+        """Get entity type name."""
+        return self.entity_type
+
+
+class AAPIGenerator(ABC, IAPIGenerator):
+    """Abstract base class for API generator implementing IAPIGenerator interface."""
+    @abstractmethod
+
+    async def generate_openapi(self) -> dict[str, Any]:
+        """Generate OpenAPI specification."""
+        pass
+    @abstractmethod
+
+    def create_app(self):
+        """Create application instance (engine-specific)."""
+        pass
+
+
+class AOAuth2Provider(ABC, IOAuth2Provider):
+    """Abstract base class for OAuth 2.0 provider implementing IOAuth2Provider interface."""
+
+    def __init__(
+        self,
+        provider_name: str,
+        authorization_url: str,
+        token_url: str,
+        userinfo_url: Optional[str] = None,
+    ):
+        self.provider_name = provider_name
+        self.authorization_url = authorization_url
+        self.token_url = token_url
+        self.userinfo_url = userinfo_url
+
+    def get_authorization_url(self) -> str:
+        """Get authorization URL."""
+        return self.authorization_url
+
+    def get_token_url(self) -> str:
+        """Get token URL."""
+        return self.token_url
+
+    def get_userinfo_url(self) -> Optional[str]:
+        """Get userinfo URL."""
+        return self.userinfo_url
+
+
+class AApiServer(ABC, IApiServer):
+    """Abstract base class for API server implementing IApiServer interface."""
+
+    def __init__(self):
+        """Initialize AApiServer with logging."""
+        from exonware.xwsystem import get_logger
+        self.logger = get_logger(self.__class__.__name__)
+        self._is_running = False
+        self._start_time: Optional[datetime] = None
+        self._services_running = False
+        # Track flushable handlers for shutdown
+        self._flushable_handlers: list[Any] = []
+        # Call on_init hook
+        self.on_init()
+
+    def on_init(self) -> None:
+        """
+        Lifecycle hook: Called during initialization.
+        Subclasses can override this to perform initialization tasks.
+        This is called automatically in __init__.
+        """
+        pass
+
+    def pre_server_start(self) -> None:
+        """
+        Lifecycle hook: Called before server starts (protocol-agnostic).
+        For HTTP engines, this is equivalent to pre_http_start().
+        For other protocols (gRPC, WebSocket, etc.), this is the generic hook.
+        Subclasses can override this to perform tasks before the server
+        starts (e.g., validate configuration, check dependencies).
+        """
+        pass
+
+    def post_server_start(self) -> None:
+        """
+        Lifecycle hook: Called after server starts (protocol-agnostic).
+        For HTTP engines, this is equivalent to post_http_start().
+        For other protocols (gRPC, WebSocket, etc.), this is the generic hook.
+        Subclasses can override this to perform tasks after the server
+        has started (e.g., register routes, warm up caches).
+        """
+        pass
+
+    def pre_http_start(self) -> None:
+        """
+        Lifecycle hook: Called before HTTP server starts (HTTP-specific).
+        For backward compatibility. Delegates to pre_server_start().
+        Subclasses can override this for HTTP-specific logic.
+        """
+        self.pre_server_start()
+
+    def post_http_start(self) -> None:
+        """
+        Lifecycle hook: Called after HTTP server starts (HTTP-specific).
+        For backward compatibility. Delegates to post_server_start().
+        Subclasses can override this for HTTP-specific logic.
+        """
+        self.post_server_start()
+
+    def pre_services_start(self) -> None:
+        """
+        Lifecycle hook: Called before domain services start.
+        Subclasses can override this to perform tasks before domain services
+        start (e.g., load data, initialize connections).
+        """
+        pass
+
+    def post_services_start(self) -> None:
+        """
+        Lifecycle hook: Called after domain services start.
+        Subclasses can override this to perform tasks after domain services
+        have started (e.g., verify services are ready, start background tasks).
+        """
+        pass
+
+    def pre_stop(self) -> None:
+        """
+        Lifecycle hook: Called before stopping.
+        Subclasses can override this to perform cleanup tasks before stopping
+        (e.g., save state, notify clients).
+        """
+        pass
+
+    def post_stop(self) -> None:
+        """
+        Lifecycle hook: Called after stopping.
+        Subclasses can override this to perform final cleanup tasks after
+        stopping (e.g., close connections, cleanup resources).
+        """
+        pass
+
+    def register_flushable(self, handler: Any) -> None:
+        """
+        Register a flushable handler for shutdown cleanup.
+        Handlers must implement flush() and optionally close() methods.
+        These will be called during shutdown to ensure all logs/data are flushed.
+        Args:
+            handler: Object with flush() and optionally close() methods
+        """
+        if handler not in self._flushable_handlers:
+            self._flushable_handlers.append(handler)
+            self.logger.debug(f"Registered flushable handler: {type(handler).__name__}")
+
+    def unregister_flushable(self, handler: Any) -> None:
+        """
+        Unregister a flushable handler.
+        Args:
+            handler: Handler to unregister
+        """
+        if handler in self._flushable_handlers:
+            self._flushable_handlers.remove(handler)
+            self.logger.debug(f"Unregistered flushable handler: {type(handler).__name__}")
+    @abstractmethod
+
+    def start(self, host: str = "0.0.0.0", port: int = 8000, **kwargs) -> None:
+        """Start the API server services."""
+        pass
+    @abstractmethod
+
+    def stop(self) -> None:
+        """Stop the API server services."""
+        pass
+
+    def restart(self, host: str = "0.0.0.0", port: int = 8000, **kwargs) -> None:
+        """Restart the API server."""
+        self.logger.info("Restarting server...")
+        self.stop()
+        self.start(host=host, port=port, **kwargs)
+        self.logger.info("Server restarted")
+
+    def status(self) -> dict[str, Any]:
+        """
+        Get server status.
+        Returns:
+            Dictionary with server status information
+        """
+        uptime = None
+        if self._start_time:
+            from datetime import datetime
+            uptime = (datetime.now() - self._start_time).total_seconds()
+        return {
+            "status": "running" if self._is_running else "stopped",
+            "is_running": self._is_running,
+            "services_running": getattr(self, '_services_running', False),
+            "start_time": self._start_time.isoformat() if self._start_time else None,
+            "uptime_seconds": uptime,
+        }
+
+    def health(self) -> dict[str, Any]:
+        """
+        Get server health check.
+        Returns:
+            Dictionary with health check information
+        """
+        from datetime import datetime
+        return {
+            "status": "healthy" if self._is_running else "unhealthy",
+            "timestamp": datetime.now().isoformat(),
+            "is_running": self._is_running,
+        }
+
+    def log(self, level: str = "INFO", message: str = "") -> None:
+        """
+        Log a message.
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+            message: Log message
+        """
+        log_method = getattr(self.logger, level.lower(), self.logger.info)
+        log_method(message)
+    @property
+
+    def is_running(self) -> bool:
+        """Check if server is running."""
+        return self._is_running
+
+    def pre_register_action(self, action: Any) -> Any:
+        """
+        Lifecycle hook: Called before registering an action.
+        Subclasses can override this to transform actions before registration
+        (e.g., inject authorizers, add middleware, modify metadata).
+        Args:
+            action: Action to be registered
+        Returns:
+            Transformed action (or original if no transformation needed)
+        """
+        return action
+
+    def post_register_action(self, action: Any, route_info: dict[str, Any]) -> None:
+        """
+        Lifecycle hook: Called after registering an action.
+        Subclasses can override this to perform tasks after action registration
+        (e.g., log registration, update metrics, validate route).
+        Args:
+            action: Registered action
+            route_info: Dictionary with route information (path, method, etc.)
+        """
+        pass
+
+
+class AApiAgent(ABC, IApiAgent):
+    """Abstract base class for API agent implementing IApiAgent interface."""
+
+    def __init__(self, name: Optional[str] = None):
+        """
+        Initialize API agent.
+        Args:
+            name: Optional name for this agent
+        """
+        self._name = name or self.__class__.__name__
+        self._actions: list[Any] = []
+    @property
+
+    def name(self) -> str:
+        """Get agent name."""
+        return self._name
+    @abstractmethod
+
+    def get_actions(self) -> list[Any]:
+        """
+        Get list of XWAction instances provided by this agent.
+        Subclasses must implement this to return their actions.
+        Returns:
+            List of XWAction instances or decorated functions
+        """
+        pass
+
+    def register_to_server(self, server: Any, path_prefix: str = "") -> int:
+        """
+        Register all actions from this agent to an ApiServer.
+        Args:
+            server: ApiServer instance to register actions to
+            path_prefix: Optional path prefix for all actions
+        Returns:
+            Number of successfully registered actions
+        """
+        actions = self.get_actions()
+        if not actions:
+            return 0
+        # Use server's register_actions method
+        if hasattr(server, 'register_actions'):
+            return server.register_actions(actions, path_prefix=path_prefix)
+        elif hasattr(server, 'register_action'):
+            # Fallback: register one by one
+            registered = 0
+            for action in actions:
+                if server.register_action(action, path=path_prefix):
+                    registered += 1
+            return registered
+        else:
+            raise TypeError(f"Server must have register_actions or register_action method, got {type(server)}")

exonware/xwapi/client/__init__.py

@@ -0,0 +1,12 @@
+#exonware/xwapi/src/exonware/xwapi/client/__init__.py
+"""
+Client package for xwapi library.
+Contains all client/agent-related functionality:
+- XWApiAgent: Main agent implementation
+- engines/: Client engine implementations
+"""
+
+from exonware.xwapi.client.xwclient import XWApiAgent
+__all__ = [
+    "XWApiAgent",
+]

exonware/xwapi/client/base.py

@@ -0,0 +1,16 @@
+#exonware/xwapi/src/exonware/xwapi/client/base.py
+"""
+Abstract base classes for xwapi client library.
+This module re-exports AApiAgent from exonware.xwapi.base for backward compatibility.
+All new code should import from exonware.xwapi.base directly.
+Company: eXonware.com
+Author: eXonware Backend Team
+Email: connect@exonware.com
+Version: 0.9.0.2
+"""
+# Re-export AApiAgent from xwapi.base for backward compatibility
+
+from exonware.xwapi.base import AApiAgent
+__all__ = ['AApiAgent']
+# Original implementation moved to exonware.xwapi.base for consistency
+# This module kept for backward compatibility with existing imports