strapi-kit 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

strapi_kit/models/request/query.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 import copy
 from typing import Any
 
+from strapi_kit.exceptions import ValidationError
 from strapi_kit.models.enums import PublicationState, SortDirection
 from strapi_kit.models.request.fields import FieldSelection
 from strapi_kit.models.request.filters import FilterBuilder
@@ -220,7 +221,9 @@ class StrapiQuery:
             Self for method chaining
 
         Raises:
-            ValueError: If mixing page-based and offset-based parameters
+            strapi_kit.exceptions.ValidationError: If mixing page-based and
+                offset-based parameters, or if pagination values are invalid
+                (page < 1, page_size < 1, start < 0, limit < 1)
 
         Examples:
             >>> # Page-based
@@ -234,15 +237,15 @@ class StrapiQuery:
         offset_based = start is not None or limit is not None
 
         if page_based and offset_based:
-            raise ValueError("Cannot mix page-based and offset-based pagination")
+            raise ValidationError("Cannot mix page-based and offset-based pagination")
 
         if page_based:
             # Validate page value if explicitly provided
             if page is not None and page < 1:
-                raise ValueError("page must be >= 1")
+                raise ValidationError("page must be >= 1")
             # Validate page_size value if explicitly provided
             if page_size is not None and page_size < 1:
-                raise ValueError("page_size must be >= 1")
+                raise ValidationError("page_size must be >= 1")
             self._pagination = PagePagination(
                 page=1 if page is None else page,
                 page_size=25 if page_size is None else page_size,
@@ -251,10 +254,10 @@ class StrapiQuery:
         elif offset_based:
             # Validate start value if explicitly provided
             if start is not None and start < 0:
-                raise ValueError("start must be >= 0")
+                raise ValidationError("start must be >= 0")
             # Validate limit value if explicitly provided
             if limit is not None and limit < 1:
-                raise ValueError("limit must be >= 1")
+                raise ValidationError("limit must be >= 1")
             self._pagination = OffsetPagination(
                 start=0 if start is None else start,
                 limit=25 if limit is None else limit,

strapi_kit/operations/media.py

@@ -5,10 +5,12 @@ and response normalization across sync and async clients.
 """
 
 import json
+import mimetypes
 from pathlib import Path
 from typing import IO, Any, Literal
 from urllib.parse import urljoin, urlparse
 
+from strapi_kit.exceptions import MediaError
 from strapi_kit.models.response.media import MediaFile
 
 
@@ -43,19 +45,24 @@ class UploadPayload:
         self._file_handle: IO[bytes] | None = None
 
     @property
-    def files_tuple(self) -> tuple[str, IO[bytes], None]:
+    def files_tuple(self) -> tuple[str, IO[bytes], str]:
         """Get the files tuple for httpx multipart upload.
 
         Returns:
-            Tuple of (filename, file_handle, content_type)
-            Content type is None to let httpx auto-detect MIME type.
+            Tuple of (filename, file_handle, mime_type) where:
+            - filename: The actual file name from the path
+            - file_handle: Open file handle for reading
+            - mime_type: Detected MIME type or 'application/octet-stream' as fallback
 
         Raises:
-            RuntimeError: If accessed outside of context manager
+            MediaError: If accessed outside of context manager
         """
         if self._file_handle is None:
-            raise RuntimeError("UploadPayload must be used as a context manager")
-        return ("file", self._file_handle, None)
+            raise MediaError("UploadPayload must be used as a context manager")
+        filename = self._file_path.name
+        mime_type, _ = mimetypes.guess_type(filename)
+        mime_type = mime_type or "application/octet-stream"
+        return (filename, self._file_handle, mime_type)
 
     @property
     def data(self) -> dict[str, Any] | None:

strapi_kit/operations/streaming.py

@@ -7,6 +7,7 @@ allowing memory-efficient iteration over large datasets.
 from collections.abc import AsyncGenerator, Generator
 from typing import TYPE_CHECKING
 
+from ..exceptions import ValidationError
 from ..models import StrapiQuery
 from ..models.response.normalized import NormalizedEntity
 
@@ -36,7 +37,7 @@ def stream_entities(
         NormalizedEntity objects one at a time
 
     Raises:
-        ValueError: If page_size < 1
+        ValidationError: If page_size < 1
 
     Example:
         >>> with SyncClient(config) as client:
@@ -45,7 +46,7 @@ def stream_entities(
         ...         # Process one at a time without loading all into memory
     """
     if page_size < 1:
-        raise ValueError("page_size must be >= 1")
+        raise ValidationError("page_size must be >= 1")
 
     current_page = 1
 
@@ -100,7 +101,7 @@ async def stream_entities_async(
         NormalizedEntity objects one at a time
 
     Raises:
-        ValueError: If page_size < 1
+        ValidationError: If page_size < 1
 
     Example:
         >>> async with AsyncClient(config) as client:
@@ -109,7 +110,7 @@ async def stream_entities_async(
         ...         # Process asynchronously without loading all into memory
     """
     if page_size < 1:
-        raise ValueError("page_size must be >= 1")
+        raise ValidationError("page_size must be >= 1")
 
     current_page = 1
 

strapi_kit/utils/__init__.py

@@ -3,13 +3,32 @@
 This package contains helper utilities including:
 - Rate limiting
 - UID handling
+- SEO detection
 """
 
 from strapi_kit.utils.rate_limiter import AsyncTokenBucketRateLimiter, TokenBucketRateLimiter
-from strapi_kit.utils.uid import uid_to_endpoint
+from strapi_kit.utils.seo import SEOConfiguration, detect_seo_configuration
+from strapi_kit.utils.uid import (
+    api_id_to_singular,
+    extract_model_name,
+    is_api_content_type,
+    uid_to_admin_url,
+    uid_to_api_id,
+    uid_to_endpoint,
+)
 
 __all__ = [
+    # Rate limiting
     "TokenBucketRateLimiter",
     "AsyncTokenBucketRateLimiter",
+    # UID utilities
     "uid_to_endpoint",
+    "uid_to_api_id",
+    "api_id_to_singular",
+    "uid_to_admin_url",
+    "extract_model_name",
+    "is_api_content_type",
+    # SEO utilities
+    "detect_seo_configuration",
+    "SEOConfiguration",
 ]

strapi_kit/utils/rate_limiter.py

@@ -9,6 +9,8 @@ import logging
 import threading
 import time
 
+from strapi_kit.exceptions import ValidationError
+
 logger = logging.getLogger(__name__)
 
 
@@ -37,7 +39,7 @@ class TokenBucketRateLimiter:
             capacity: Bucket capacity (defaults to rate for 1 second burst)
         """
         if rate <= 0:
-            raise ValueError("Rate must be positive")
+            raise ValidationError("Rate must be positive")
 
         self._rate = rate
         self._capacity = capacity if capacity is not None else rate
@@ -121,7 +123,7 @@ class AsyncTokenBucketRateLimiter:
             capacity: Bucket capacity (defaults to rate for 1 second burst)
         """
         if rate <= 0:
-            raise ValueError("Rate must be positive")
+            raise ValidationError("Rate must be positive")
 
         self._rate = rate
         self._capacity = capacity if capacity is not None else rate

strapi_kit/utils/seo.py

@@ -0,0 +1,294 @@
+"""SEO configuration detection utilities.
+
+This module provides functions for detecting SEO configurations
+in Strapi content type schemas.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from ..models.schema import ContentTypeSchema
+
+
+@dataclass
+class SEOConfiguration:
+    """SEO configuration detected from a content type schema.
+
+    Attributes:
+        has_seo: Whether SEO configuration was detected
+        seo_type: Type of SEO setup - "component" (shared SEO component),
+                  "flat" (individual fields), or None if not detected
+        seo_field_name: Name of the SEO field/component (e.g., "seo", "meta")
+        seo_component_uid: Component UID if seo_type is "component"
+        fields: Mapping of SEO purpose to field path
+                (e.g., {"title": "seo.metaTitle", "description": "seo.metaDescription"})
+    """
+
+    has_seo: bool = False
+    seo_type: Literal["component", "flat"] | None = None
+    seo_field_name: str | None = None
+    seo_component_uid: str | None = None
+    fields: dict[str, str] = field(default_factory=dict)
+
+
+# Common SEO field name patterns (case-insensitive)
+_SEO_COMPONENT_NAMES = {"seo", "meta", "metadata", "metatags", "seometa"}
+
+# Common SEO field patterns for component detection
+_SEO_COMPONENT_UIDS = {
+    "shared.seo",
+    "seo.seo",
+    "shared.meta",
+    "shared.metadata",
+}
+
+# Flat SEO field patterns (field_name -> purpose)
+_FLAT_SEO_FIELD_PATTERNS: dict[str, str] = {
+    "metatitle": "title",
+    "meta_title": "title",
+    "seotitle": "title",
+    "seo_title": "title",
+    "ogtitle": "og_title",
+    "og_title": "og_title",
+    "metadescription": "description",
+    "meta_description": "description",
+    "seodescription": "description",
+    "seo_description": "description",
+    "ogdescription": "og_description",
+    "og_description": "og_description",
+    "metakeywords": "keywords",
+    "meta_keywords": "keywords",
+    "seokeywords": "keywords",
+    "seo_keywords": "keywords",
+    "metaimage": "image",
+    "meta_image": "image",
+    "seoimage": "image",
+    "seo_image": "image",
+    "ogimage": "og_image",
+    "og_image": "og_image",
+    "canonicalurl": "canonical_url",
+    "canonical_url": "canonical_url",
+    "canonical": "canonical_url",
+    "noindex": "no_index",
+    "no_index": "no_index",
+    "nofollow": "no_follow",
+    "no_follow": "no_follow",
+    "robots": "robots",
+}
+
+
+def detect_seo_configuration(
+    schema: ContentTypeSchema | dict[str, Any],
+) -> SEOConfiguration:
+    """Detect SEO configuration in a content type schema.
+
+    Analyzes the schema to detect:
+    1. SEO components (shared.seo, seo.seo, etc.)
+    2. Flat SEO fields (metaTitle, meta_description, etc.)
+
+    Args:
+        schema: Content type schema (ContentTypeSchema or raw dict)
+
+    Returns:
+        SEOConfiguration with detection results
+
+    Examples:
+        >>> # Schema with SEO component
+        >>> schema = ContentTypeSchema(
+        ...     uid="api::article.article",
+        ...     display_name="Article",
+        ...     fields={
+        ...         "seo": FieldSchema(type=FieldType.COMPONENT),
+        ...     }
+        ... )
+        >>> config = detect_seo_configuration(schema)
+        >>> config.has_seo
+        True
+        >>> config.seo_type
+        'component'
+
+        >>> # Schema with flat SEO fields
+        >>> schema_dict = {
+        ...     "uid": "api::page.page",
+        ...     "attributes": {
+        ...         "metaTitle": {"type": "string"},
+        ...         "metaDescription": {"type": "text"},
+        ...     }
+        ... }
+        >>> config = detect_seo_configuration(schema_dict)
+        >>> config.has_seo
+        True
+        >>> config.seo_type
+        'flat'
+    """
+    config = SEOConfiguration()
+
+    # Extract attributes from schema
+    if isinstance(schema, ContentTypeSchema):
+        attributes = {name: _field_to_dict(field) for name, field in schema.fields.items()}
+    elif isinstance(schema, dict):
+        # Handle both {"fields": ...} and {"attributes": ...} formats
+        attributes = schema.get("attributes") or schema.get("fields") or {}
+    else:
+        return config
+
+    # First, try to detect SEO component
+    component_result = _detect_seo_component(attributes)
+    if component_result:
+        config.has_seo = True
+        config.seo_type = "component"
+        config.seo_field_name = component_result["field_name"]
+        config.seo_component_uid = component_result.get("component_uid")
+        config.fields = component_result.get("fields", {})
+        return config
+
+    # If no component, look for flat SEO fields
+    flat_result = _detect_flat_seo_fields(attributes)
+    if flat_result:
+        config.has_seo = True
+        config.seo_type = "flat"
+        config.fields = flat_result
+        return config
+
+    return config
+
+
+def _field_to_dict(field_schema: Any) -> dict[str, Any]:
+    """Convert a FieldSchema to dict for processing.
+
+    Args:
+        field_schema: FieldSchema instance
+
+    Returns:
+        Dictionary representation
+    """
+    if hasattr(field_schema, "type"):
+        result: dict[str, Any] = {"type": field_schema.type.value}
+        if hasattr(field_schema, "target") and field_schema.target:
+            result["component"] = field_schema.target
+        return result
+    return {}
+
+
+def _detect_seo_component(attributes: dict[str, Any]) -> dict[str, Any] | None:
+    """Detect SEO component in attributes.
+
+    Args:
+        attributes: Field attributes dictionary
+
+    Returns:
+        Detection result or None if not found
+    """
+    for field_name, field_config in attributes.items():
+        # Check if field type is component
+        field_type = _get_field_type(field_config)
+        if field_type != "component":
+            continue
+
+        # Check if field name suggests SEO
+        field_name_lower = field_name.lower()
+        is_seo_name = field_name_lower in _SEO_COMPONENT_NAMES
+
+        # Check if component UID suggests SEO
+        component_uid = _get_component_uid(field_config)
+        is_seo_component = False
+        if component_uid:
+            component_uid_lower = component_uid.lower()
+            is_seo_component = (
+                any(seo_uid in component_uid_lower for seo_uid in _SEO_COMPONENT_UIDS)
+                or "seo" in component_uid_lower
+            )
+
+        if is_seo_name or is_seo_component:
+            # Build field mappings based on common SEO component structure
+            fields = _build_component_field_mappings(field_name)
+            return {
+                "field_name": field_name,
+                "component_uid": component_uid,
+                "fields": fields,
+            }
+
+    return None
+
+
+def _detect_flat_seo_fields(attributes: dict[str, Any]) -> dict[str, str] | None:
+    """Detect flat SEO fields in attributes.
+
+    Args:
+        attributes: Field attributes dictionary
+
+    Returns:
+        Field mappings or None if not found
+    """
+    fields: dict[str, str] = {}
+
+    for field_name, _field_config in attributes.items():
+        field_name_lower = field_name.lower().replace("-", "_")
+
+        # Check if field name matches known SEO patterns
+        if field_name_lower in _FLAT_SEO_FIELD_PATTERNS:
+            purpose = _FLAT_SEO_FIELD_PATTERNS[field_name_lower]
+            fields[purpose] = field_name
+
+    return fields if fields else None
+
+
+def _get_field_type(field_config: Any) -> str | None:
+    """Extract field type from field configuration.
+
+    Args:
+        field_config: Field configuration (dict or object)
+
+    Returns:
+        Field type string or None
+    """
+    if isinstance(field_config, dict):
+        return field_config.get("type")
+    if hasattr(field_config, "type"):
+        field_type = field_config.type
+        return field_type.value if hasattr(field_type, "value") else str(field_type)
+    return None
+
+
+def _get_component_uid(field_config: Any) -> str | None:
+    """Extract component UID from field configuration.
+
+    Args:
+        field_config: Field configuration (dict or object)
+
+    Returns:
+        Component UID string or None
+    """
+    if isinstance(field_config, dict):
+        component = field_config.get("component")
+        return str(component) if component else None
+    if hasattr(field_config, "target"):
+        target = field_config.target
+        return str(target) if target else None
+    return None
+
+
+def _build_component_field_mappings(field_name: str) -> dict[str, str]:
+    """Build standard field mappings for an SEO component.
+
+    Args:
+        field_name: Name of the SEO component field
+
+    Returns:
+        Field mappings with component prefix
+    """
+    return {
+        "title": f"{field_name}.metaTitle",
+        "description": f"{field_name}.metaDescription",
+        "keywords": f"{field_name}.keywords",
+        "image": f"{field_name}.metaImage",
+        "canonical_url": f"{field_name}.canonicalURL",
+        "og_title": f"{field_name}.ogTitle",
+        "og_description": f"{field_name}.ogDescription",
+        "og_image": f"{field_name}.ogImage",
+        "twitter_title": f"{field_name}.twitterTitle",
+        "twitter_description": f"{field_name}.twitterDescription",
+        "twitter_image": f"{field_name}.twitterImage",
+        "robots": f"{field_name}.robots",
+        "structured_data": f"{field_name}.structuredData",
+    }

strapi_kit/utils/uid.py

@@ -4,6 +4,29 @@ This module provides centralized functions for handling Strapi content type UIDs
 including conversion to API endpoints with proper pluralization.
 """
 
+# Irregular plurals mapping (plural -> singular)
+_IRREGULAR_PLURALS: dict[str, str] = {
+    "people": "person",
+    "children": "child",
+    "men": "man",
+    "women": "woman",
+    "feet": "foot",
+    "teeth": "tooth",
+    "geese": "goose",
+    "mice": "mouse",
+    "oxen": "ox",
+    "indices": "index",
+    "matrices": "matrix",
+    "vertices": "vertex",
+    "analyses": "analysis",
+    "crises": "crisis",
+    "theses": "thesis",
+    "phenomena": "phenomenon",
+    "criteria": "criterion",
+    "data": "datum",
+    "media": "medium",
+}
+
 
 def uid_to_endpoint(uid: str) -> str:
     """Convert content type UID to API endpoint.
@@ -86,3 +109,109 @@ def is_api_content_type(uid: str) -> bool:
         False
     """
     return uid.startswith("api::")
+
+
+def api_id_to_singular(api_id: str) -> str:
+    """Convert plural API ID to singular form.
+
+    Handles common English pluralization patterns and irregular plurals.
+    For custom pluralization, you may need to handle edge cases manually.
+
+    Args:
+        api_id: Plural API ID (e.g., "articles", "categories", "people")
+
+    Returns:
+        Singular form (e.g., "article", "category", "person")
+
+    Examples:
+        >>> api_id_to_singular("articles")
+        'article'
+        >>> api_id_to_singular("categories")
+        'category'
+        >>> api_id_to_singular("classes")
+        'class'
+        >>> api_id_to_singular("people")
+        'person'
+        >>> api_id_to_singular("children")
+        'child'
+    """
+    # Normalize to lowercase for comparison
+    name = api_id.lower()
+
+    # Check irregular plurals first
+    if name in _IRREGULAR_PLURALS:
+        return _IRREGULAR_PLURALS[name]
+
+    # Handle -ies -> -y (categories -> category)
+    if name.endswith("ies"):
+        return name[:-3] + "y"
+
+    # Handle -zzes specifically
+    # Words with single z double it when pluralized: quiz -> quizzes (remove -zes, keep 1 z)
+    # Words with double z just add es: buzz -> buzzes, fizz -> fizzes (remove -es, keep zz)
+    if name.endswith("zzes"):
+        # Common double-z words: buzz, fizz, fuzz, jazz, razz, etc. (pattern: consonant + vowel + zz)
+        # Common single-z words that double: quiz, whiz (pattern: vowel + i + z or similar)
+        # Heuristic: 4-letter bases (buzz, fizz, jazz, fuzz) become 6-letter plurals
+        #            4-letter bases like quiz become 7-letter plurals
+        # So length 6 -> likely double-z base (remove -es)
+        #    length 7+ -> likely single-z base that was doubled (remove -zes)
+        if len(name) <= 6:
+            return name[:-2]  # buzzes -> buzz, fizzes -> fizz
+        else:
+            return name[:-3]  # quizzes -> quiz, whizzes -> whiz
+
+    # Handle -es for words ending in s, x, z, ch, sh (classes -> class, buses -> bus)
+    if name.endswith("es"):
+        base = name[:-2]
+        if base.endswith(("s", "x", "z", "ch", "sh")):
+            return base
+
+    # Handle standard -s removal (articles -> article)
+    if name.endswith("s") and len(name) > 1:
+        return name[:-1]
+
+    # Already singular or unrecognized
+    return name
+
+
+def uid_to_admin_url(
+    uid: str,
+    base_url: str,
+    kind: str = "collectionType",
+) -> str:
+    """Build Strapi admin panel URL from content type UID.
+
+    Args:
+        uid: Content type UID (e.g., "api::article.article")
+        base_url: Strapi base URL (e.g., "http://localhost:1337")
+        kind: Content type kind - "collectionType" or "singleType"
+
+    Returns:
+        Admin panel URL for the content type
+
+    Examples:
+        >>> uid_to_admin_url("api::article.article", "http://localhost:1337")
+        'http://localhost:1337/admin/content-manager/collection-types/api::article.article'
+
+        >>> uid_to_admin_url(
+        ...     "api::homepage.homepage",
+        ...     "http://localhost:1337",
+        ...     kind="singleType"
+        ... )
+        'http://localhost:1337/admin/content-manager/single-types/api::homepage.homepage'
+    """
+    # Remove trailing slash from base_url
+    base_url = base_url.rstrip("/")
+
+    # Determine the path segment based on kind
+    if kind == "singleType":
+        type_segment = "single-types"
+    else:
+        type_segment = "collection-types"
+
+    return f"{base_url}/admin/content-manager/{type_segment}/{uid}"
+
+
+# Alias for clarity - uid_to_endpoint already exists, this makes the intent explicit
+uid_to_api_id = uid_to_endpoint