strapi-kit 0.0.1__py3-none-any.whl

strapi_kit/protocols.py

@@ -0,0 +1,455 @@
+"""Protocol definitions for dependency injection.
+
+This module defines interfaces for core components, enabling:
+- Dependency injection
+- Easy mocking in tests
+- Loose coupling between components
+- Custom implementations
+"""
+
+from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
+
+import httpx
+
+from .models.response.normalized import (
+    NormalizedCollectionResponse,
+    NormalizedSingleResponse,
+)
+
+if TYPE_CHECKING:
+    from .models.schema import ContentTypeSchema
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Protocol for authentication providers.
+
+    Implementations must provide methods to generate auth headers
+    and validate credentials.
+    """
+
+    def get_headers(self) -> dict[str, str]:
+        """Get authentication headers for HTTP requests.
+
+        Returns:
+            Dictionary with authentication headers (e.g., Authorization: Bearer ...)
+        """
+        ...
+
+    def validate_token(self) -> bool:
+        """Validate that authentication credentials are valid.
+
+        Returns:
+            True if credentials are valid, False otherwise
+        """
+        ...
+
+
+@runtime_checkable
+class HTTPClient(Protocol):
+    """Protocol for synchronous HTTP clients.
+
+    Defines the interface for making HTTP requests in sync mode.
+    """
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            url: Full URL to request
+            params: URL query parameters
+            json: JSON request body
+            headers: HTTP headers
+
+        Returns:
+            HTTP response object
+        """
+        ...
+
+    def post(
+        self,
+        url: str,
+        *,
+        files: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make a POST request with multipart data.
+
+        Args:
+            url: Full URL to request
+            files: Files for multipart upload
+            data: Form data
+            headers: HTTP headers
+
+        Returns:
+            HTTP response object
+        """
+        ...
+
+    def stream(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Stream an HTTP request.
+
+        Args:
+            method: HTTP method
+            url: Full URL to request
+            **kwargs: Additional request parameters
+
+        Returns:
+            Context manager for streaming response
+        """
+        ...
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        ...
+
+
+@runtime_checkable
+class AsyncHTTPClient(Protocol):
+    """Protocol for asynchronous HTTP clients.
+
+    Defines the interface for making HTTP requests in async mode.
+    """
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make an async HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            url: Full URL to request
+            params: URL query parameters
+            json: JSON request body
+            headers: HTTP headers
+
+        Returns:
+            HTTP response object
+        """
+        ...
+
+    async def post(
+        self,
+        url: str,
+        *,
+        files: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make an async POST request with multipart data.
+
+        Args:
+            url: Full URL to request
+            files: Files for multipart upload
+            data: Form data
+            headers: HTTP headers
+
+        Returns:
+            HTTP response object
+        """
+        ...
+
+    def stream(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Stream an async HTTP request.
+
+        Args:
+            method: HTTP method
+            url: Full URL to request
+            **kwargs: Additional request parameters
+
+        Returns:
+            Async context manager for streaming response.
+            Note: httpx.AsyncClient.stream() is NOT an async method itself -
+            it returns an async context manager directly. Use with `async with`.
+        """
+        ...
+
+    async def aclose(self) -> None:
+        """Close the HTTP client and release resources."""
+        ...
+
+
+@runtime_checkable
+class ResponseParser(Protocol):
+    """Protocol for response parsers.
+
+    Implementations must handle parsing of Strapi responses
+    into normalized format.
+    """
+
+    def parse_single(self, response_data: dict[str, Any]) -> NormalizedSingleResponse:
+        """Parse a single entity response.
+
+        Args:
+            response_data: Raw JSON response from Strapi
+
+        Returns:
+            Normalized single entity response
+        """
+        ...
+
+    def parse_collection(self, response_data: dict[str, Any]) -> NormalizedCollectionResponse:
+        """Parse a collection response.
+
+        Args:
+            response_data: Raw JSON response from Strapi
+
+        Returns:
+            Normalized collection response
+        """
+        ...
+
+
+@runtime_checkable
+class ConfigProvider(Protocol):
+    """Protocol for configuration providers.
+
+    Defines the interface for accessing client configuration.
+    This allows for alternative config sources (files, databases, etc.)
+    while maintaining type safety.
+    """
+
+    def get_base_url(self) -> str:
+        """Get the base URL of the Strapi instance.
+
+        Returns:
+            Base URL (without trailing slash)
+        """
+        ...
+
+    def get_api_token(self) -> str:
+        """Get the API token for authentication.
+
+        Returns:
+            API token string
+        """
+        ...
+
+    @property
+    def api_version(self) -> Literal["v4", "v5", "auto"]:
+        """Get the configured API version.
+
+        Returns:
+            API version ("v4", "v5", or "auto")
+        """
+        ...
+
+    @property
+    def timeout(self) -> float:
+        """Get request timeout in seconds.
+
+        Returns:
+            Timeout value
+        """
+        ...
+
+    @property
+    def max_connections(self) -> int:
+        """Get maximum concurrent connections.
+
+        Returns:
+            Max connections count
+        """
+        ...
+
+    @property
+    def verify_ssl(self) -> bool:
+        """Get SSL verification setting.
+
+        Returns:
+            Whether to verify SSL certificates
+        """
+        ...
+
+    @property
+    def retry(self) -> Any:
+        """Get retry configuration.
+
+        Returns:
+            Retry config object
+        """
+        ...
+
+
+@runtime_checkable
+class StrapiClient(Protocol):
+    """Protocol for Strapi client implementations.
+
+    Defines the interface that both SyncClient and AsyncClient implement,
+    allowing for type-safe dependency injection in export/import modules.
+
+    Note: This protocol defines the sync version. Async methods follow the
+    same signature but are awaitable.
+    """
+
+    @property
+    def base_url(self) -> str:
+        """Get the base URL of the Strapi instance."""
+        ...
+
+    @property
+    def api_version(self) -> str | None:
+        """Get the detected or configured API version."""
+        ...
+
+    def get_one(
+        self,
+        endpoint: str,
+        query: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> NormalizedSingleResponse:
+        """Get a single entity.
+
+        Args:
+            endpoint: API endpoint path
+            query: Optional query configuration
+            headers: Additional headers
+
+        Returns:
+            Normalized single entity response
+        """
+        ...
+
+    def get_many(
+        self,
+        endpoint: str,
+        query: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> NormalizedCollectionResponse:
+        """Get multiple entities.
+
+        Args:
+            endpoint: API endpoint path
+            query: Optional query configuration
+            headers: Additional headers
+
+        Returns:
+            Normalized collection response
+        """
+        ...
+
+    def create(
+        self,
+        endpoint: str,
+        data: dict[str, Any],
+        query: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> NormalizedSingleResponse:
+        """Create a new entity.
+
+        Args:
+            endpoint: API endpoint path
+            data: Entity data to create
+            query: Optional query configuration
+            headers: Additional headers
+
+        Returns:
+            Normalized single entity response
+        """
+        ...
+
+    def update(
+        self,
+        endpoint: str,
+        data: dict[str, Any],
+        query: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> NormalizedSingleResponse:
+        """Update an existing entity.
+
+        Args:
+            endpoint: API endpoint path
+            data: Entity data to update
+            query: Optional query configuration
+            headers: Additional headers
+
+        Returns:
+            Normalized single entity response
+        """
+        ...
+
+    def remove(
+        self,
+        endpoint: str,
+        headers: dict[str, str] | None = None,
+    ) -> NormalizedSingleResponse:
+        """Delete an entity.
+
+        Args:
+            endpoint: API endpoint path
+            headers: Additional headers
+
+        Returns:
+            Normalized single entity response
+        """
+        ...
+
+
+@runtime_checkable
+class SchemaProvider(Protocol):
+    """Protocol for content type schema providers.
+
+    Defines the interface for accessing and caching content type schemas.
+    Enables proper relation resolution during export/import operations.
+    """
+
+    def get_schema(self, content_type: str) -> "ContentTypeSchema":
+        """Get schema for a content type.
+
+        Args:
+            content_type: Content type UID (e.g., "api::article.article")
+
+        Returns:
+            Content type schema
+        """
+        ...
+
+    def cache_schema(self, content_type: str, schema: "ContentTypeSchema") -> None:
+        """Cache schema for a content type.
+
+        Args:
+            content_type: Content type UID
+            schema: Schema to cache
+        """
+        ...
+
+    def clear_cache(self) -> None:
+        """Clear all cached schemas."""
+        ...
+
+    def has_schema(self, content_type: str) -> bool:
+        """Check if schema is cached.
+
+        Args:
+            content_type: Content type UID
+
+        Returns:
+            True if schema is cached, False otherwise
+        """
+        ...

strapi_kit/utils/__init__.py

@@ -0,0 +1,15 @@
+"""Utility modules for strapi-kit.
+
+This package contains helper utilities including:
+- Rate limiting
+- UID handling
+"""
+
+from strapi_kit.utils.rate_limiter import AsyncTokenBucketRateLimiter, TokenBucketRateLimiter
+from strapi_kit.utils.uid import uid_to_endpoint
+
+__all__ = [
+    "TokenBucketRateLimiter",
+    "AsyncTokenBucketRateLimiter",
+    "uid_to_endpoint",
+]

strapi_kit/utils/rate_limiter.py

@@ -0,0 +1,201 @@
+"""Rate limiting utilities using token bucket algorithm.
+
+Provides both synchronous and asynchronous rate limiters to control
+request rates when communicating with the Strapi API.
+"""
+
+import asyncio
+import logging
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+
+class TokenBucketRateLimiter:
+    """Synchronous rate limiter using token bucket algorithm.
+
+    The token bucket algorithm allows bursting up to the bucket capacity
+    while maintaining the specified average rate over time.
+
+    Example:
+        >>> limiter = TokenBucketRateLimiter(rate=5.0)  # 5 requests per second
+        >>> for _ in range(10):
+        ...     limiter.acquire()
+        ...     # make_request()
+    """
+
+    def __init__(
+        self,
+        rate: float,
+        capacity: float | None = None,
+    ) -> None:
+        """Initialize the rate limiter.
+
+        Args:
+            rate: Maximum requests per second
+            capacity: Bucket capacity (defaults to rate for 1 second burst)
+        """
+        if rate <= 0:
+            raise ValueError("Rate must be positive")
+
+        self._rate = rate
+        self._capacity = capacity if capacity is not None else rate
+        self._tokens = self._capacity
+        self._last_update = time.monotonic()
+        self._lock = threading.Lock()
+
+        logger.debug(f"Rate limiter initialized: {rate}/s, capacity: {self._capacity}")
+
+    def acquire(self, tokens: float = 1.0, blocking: bool = True) -> bool:
+        """Acquire tokens from the bucket.
+
+        Args:
+            tokens: Number of tokens to acquire (default: 1)
+            blocking: Whether to block until tokens are available (default: True)
+
+        Returns:
+            True if tokens were acquired, False if non-blocking and not available
+        """
+        with self._lock:
+            while True:
+                self._refill()
+
+                if self._tokens >= tokens:
+                    self._tokens -= tokens
+                    return True
+
+                if not blocking:
+                    return False
+
+                # Calculate wait time until enough tokens are available
+                tokens_needed = tokens - self._tokens
+                wait_time = tokens_needed / self._rate
+
+                # Release lock while sleeping
+                self._lock.release()
+                try:
+                    time.sleep(wait_time)
+                finally:
+                    self._lock.acquire()
+
+    def _refill(self) -> None:
+        """Refill tokens based on elapsed time."""
+        now = time.monotonic()
+        elapsed = now - self._last_update
+        self._last_update = now
+
+        # Add tokens based on elapsed time
+        self._tokens = min(self._capacity, self._tokens + elapsed * self._rate)
+
+    @property
+    def available_tokens(self) -> float:
+        """Get current available tokens."""
+        with self._lock:
+            self._refill()
+            return self._tokens
+
+
+class AsyncTokenBucketRateLimiter:
+    """Asynchronous rate limiter using token bucket algorithm.
+
+    The token bucket algorithm allows bursting up to the bucket capacity
+    while maintaining the specified average rate over time.
+
+    Example:
+        >>> limiter = AsyncTokenBucketRateLimiter(rate=5.0)  # 5 requests per second
+        >>> for _ in range(10):
+        ...     await limiter.acquire()
+        ...     # await make_request()
+    """
+
+    def __init__(
+        self,
+        rate: float,
+        capacity: float | None = None,
+    ) -> None:
+        """Initialize the rate limiter.
+
+        Args:
+            rate: Maximum requests per second
+            capacity: Bucket capacity (defaults to rate for 1 second burst)
+        """
+        if rate <= 0:
+            raise ValueError("Rate must be positive")
+
+        self._rate = rate
+        self._capacity = capacity if capacity is not None else rate
+        self._tokens = self._capacity
+        self._last_update = time.monotonic()
+        self._lock = asyncio.Lock()
+
+        logger.debug(f"Async rate limiter initialized: {rate}/s, capacity: {self._capacity}")
+
+    async def acquire(self, tokens: float = 1.0, blocking: bool = True) -> bool:
+        """Acquire tokens from the bucket.
+
+        Args:
+            tokens: Number of tokens to acquire (default: 1)
+            blocking: Whether to block until tokens are available (default: True)
+
+        Returns:
+            True if tokens were acquired, False if non-blocking and not available
+        """
+        async with self._lock:
+            while True:
+                self._refill()
+
+                if self._tokens >= tokens:
+                    self._tokens -= tokens
+                    return True
+
+                if not blocking:
+                    return False
+
+                # Calculate wait time until enough tokens are available
+                tokens_needed = tokens - self._tokens
+                wait_time = tokens_needed / self._rate
+
+                # Release lock while sleeping
+                self._lock.release()
+                try:
+                    await asyncio.sleep(wait_time)
+                finally:
+                    await self._lock.acquire()
+
+    def _refill(self) -> None:
+        """Refill tokens based on elapsed time."""
+        now = time.monotonic()
+        elapsed = now - self._last_update
+        self._last_update = now
+
+        # Add tokens based on elapsed time
+        self._tokens = min(self._capacity, self._tokens + elapsed * self._rate)
+
+    @property
+    def available_tokens(self) -> float:
+        """Get current available tokens (requires holding the lock)."""
+        # Note: This is not thread-safe without holding the lock
+        self._refill()
+        return self._tokens
+
+
+def create_rate_limiter(
+    rate_per_second: float | None,
+    async_mode: bool = False,
+) -> TokenBucketRateLimiter | AsyncTokenBucketRateLimiter | None:
+    """Factory function to create appropriate rate limiter.
+
+    Args:
+        rate_per_second: Rate limit (None to disable)
+        async_mode: Whether to create async limiter
+
+    Returns:
+        Rate limiter instance or None if rate is None
+    """
+    if rate_per_second is None:
+        return None
+
+    if async_mode:
+        return AsyncTokenBucketRateLimiter(rate=rate_per_second)
+    return TokenBucketRateLimiter(rate=rate_per_second)