strapi-kit 0.0.2__tar.gz → 0.0.4__tar.gz

strapi_kit-0.0.4/AGENTS.md

@@ -0,0 +1,54 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/strapi_kit/`: library source (clients, models, query builder, migrations, etc.).
+- `tests/`: automated tests organized by scope: `unit/`, `integration/`, `e2e/`.
+- `docs/`: MkDocs documentation source; `site/` is generated output.
+- `examples/`: runnable usage samples and migration scripts.
+
+## Build, Test, and Development Commands
+```bash
+# Install (uv preferred)
+uv pip install -e ".[dev]"    # or: make install-dev
+
+# Quality and tests
+make test                     # pytest
+make coverage                 # coverage report (htmlcov/)
+make lint                     # ruff check
+make format                   # ruff format
+make type-check               # mypy strict
+make pre-commit               # format + lint-fix + type-check + test
+
+# Docs
+make docs-serve               # local docs at http://127.0.0.1:8000
+
+# E2E (requires Strapi via Docker)
+make e2e-setup                # start Strapi
+make e2e                      # run e2e tests
+make e2e-teardown             # stop Strapi
+```
+
+## Coding Style & Naming Conventions
+- Python 3.12+, PEP 8, line length 100 (enforced by Ruff).
+- Use `ruff format` for formatting and `ruff check` for linting.
+- `mypy` runs in strict mode on `src/strapi_kit/`; type hints are expected for all functions.
+- Prefer f-strings and Google-style docstrings.
+- Use project exception types (e.g., from `strapi_kit.exceptions`) and chain errors with `raise ... from e`.
+
+## Testing Guidelines
+- Frameworks: `pytest`, `pytest-asyncio` (auto mode), `respx` for HTTP mocking.
+- Naming: `test_*.py`, `Test*` classes, `test_*` functions (per pytest config).
+- Organize by scope: unit tests are fast/isolated; integration tests require a real Strapi instance; e2e tests are Docker-backed.
+- Coverage target: 85%+ overall.
+
+## Commit & Pull Request Guidelines
+- Recent history uses descriptive sentence-style messages (e.g., “Add…”, “Refactor…”), but the contributing guide requests **Conventional Commits**.
+- Use conventional commit format in commits and PR titles, e.g. `feat(client): add retry logic`.
+- PRs should describe what/why, link issues, note breaking changes, and include screenshots for UI changes.
+- Expect automated review by CodeRabbit; ensure `pytest`, `mypy`, and `ruff` pass.
+
+## Security & Configuration
+- Run security checks with `make security` (Bandit). Use `make security-baseline` to refresh `.secrets.baseline` when needed.
+
+## Agent-Specific Instructions
+- If you are an AI assistant, consult `CLAUDE.md` and `LLM.md` for workflow conventions and architecture notes.

strapi_kit-0.0.4/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- **Exception handling improvements** ([#23](https://github.com/MehdiZare/strapi-kit/pull/23))
+  - Use `StrapiError` instead of bare `Exception` in examples for precise error handling
+  - Catch `PydanticValidationError` specifically in Content-Type Builder parsing
+  - Add proper exception chaining when re-raising validation errors
+  - Fix docstring to document `ConfigurationError` instead of `ValueError`
+
+- **Singularization bug fix** ([#23](https://github.com/MehdiZare/strapi-kit/pull/23))
+  - Fix `api_id_to_singular()` for `-zzes` endings: `quizzes` → `quiz`, `buzzes` → `buzz`
+  - Use length-based heuristic to distinguish single-z doubled vs double-z base words
+
+### Added
+
+- **Content-Type Builder API** ([#15](https://github.com/MehdiZare/strapi-kit/issues/15))
+  - `get_content_types(include_plugins=False)` - List all content types from Strapi
+  - `get_components()` - List all components
+  - `get_content_type_schema(uid)` - Get full schema for a content type
+  - New models: `ContentTypeListItem`, `ComponentListItem`, `CTBContentTypeSchema`, `CTBContentTypeInfo`
+  - Schema helper methods: `get_field_type()`, `is_relation_field()`, `is_component_field()`, `get_relation_target()`, `get_component_uid()`
+  - Full async support for all methods
+
+- **UID Conversion Utilities** ([#16](https://github.com/MehdiZare/strapi-kit/issues/16))
+  - `api_id_to_singular()` - Convert plural API IDs to singular form (handles irregular plurals like people→person, children→child)
+  - `uid_to_admin_url()` - Build Strapi admin panel URLs from content type UIDs
+  - `uid_to_api_id` - Alias for `uid_to_endpoint` for clarity
+  - Export of existing utilities: `extract_model_name()`, `is_api_content_type()`
+
+- **SEO Configuration Detection** ([#17](https://github.com/MehdiZare/strapi-kit/issues/17))
+  - `detect_seo_configuration()` - Detect SEO setup in content type schemas
+  - `SEOConfiguration` dataclass for structured detection results
+  - Support for component-based SEO (shared.seo, meta, metadata)
+  - Support for flat SEO fields (metaTitle, meta_description, ogTitle, etc.)
+  - Case-insensitive matching for field names and component UIDs
+
+### Changed
+
+- Test coverage increased from 85% to 86% (528 passing tests)
+- Added 68 new tests for Content-Type Builder, UID utilities, and SEO detection
+
+## [0.0.2] - 2025-01-XX
+
+### Added
+
+- Export/Import functionality with automatic relation resolution
+- Schema caching for efficient content type metadata handling
+- Media file export/download support
+- Full migration examples (simple and production-ready)
+
+### Changed
+
+- Improved test coverage to 85%
+
+## [0.0.1] - 2025-01-XX
+
+### Added
+
+- Initial release
+- HTTP clients (sync and async)
+- Configuration with Pydantic and environment variable support
+- Authentication (API tokens)
+- Exception hierarchy with semantic error types
+- API version detection (v4/v5)
+- Type-safe query builder with 24 filter operators
+- Response normalization for both Strapi v4 and v5
+- Media upload/download operations
+- Dependency injection support with protocols
+- Full type hints and mypy strict mode compliance
+
+[Unreleased]: https://github.com/MehdiZare/strapi-kit/compare/v0.0.2...HEAD
+[0.0.2]: https://github.com/MehdiZare/strapi-kit/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/MehdiZare/strapi-kit/releases/tag/v0.0.1

{strapi_kit-0.0.2 → strapi_kit-0.0.4}/CLAUDE.md

@@ -284,10 +284,11 @@ assert len(mock_http.requests) == 1
 
 ```
 StrapiError (base)
+├─ ConfigurationError (invalid config, missing token, bad URL)
 ├─ AuthenticationError (401)
 ├─ AuthorizationError (403)
 ├─ NotFoundError (404)
-├─ ValidationError (400)
+├─ ValidationError (400, input validation)
 ├─ ConflictError (409)
 ├─ ServerError (5xx)
 ├─ NetworkError (connection issues)
@@ -302,6 +303,12 @@ StrapiError (base)
 
 **Usage pattern**: Always catch specific exceptions before generic ones. All exceptions carry optional `details: dict[str, Any]` for context.
 
+**Non-HTTP exceptions**:
+- `ConfigurationError`: Invalid API token, missing config, bad base URL
+- `ValidationError`: Invalid query parameters (pagination, filters), invalid function arguments
+- `FormatError`: Invalid export data format, path traversal prevention
+- `MediaError`: File not found, upload/download failures, context manager misuse
+
 **HTTP mapping** (client/base.py:_handle_error_response):
 - 401 → AuthenticationError
 - 403 → AuthorizationError

strapi_kit-0.0.4/LLM.md

@@ -0,0 +1,502 @@
+# LLM Guide for strapi-kit
+
+This guide helps AI coding agents work effectively with the strapi-kit Python package for Strapi CMS integration.
+
+## Reporting Issues
+
+**If you encounter bugs, unexpected behavior, or errors while using strapi-kit, please file an issue:**
+
+- **GitHub Issues**: https://github.com/MehdiZare/strapi-kit/issues
+
+When filing an issue, include:
+1. Python version and strapi-kit version
+2. Strapi version (v4 or v5)
+3. Minimal code to reproduce the error
+4. Full error traceback
+5. Expected vs actual behavior
+
+Filing issues helps improve the library for all users. Don't hesitate to report problems, even if you're unsure whether it's a bug or user error.
+
+## Package Overview
+
+**strapi-kit** is a type-safe Python client for Strapi CMS with:
+- Sync and async clients
+- Automatic Strapi v4/v5 detection
+- Type-safe query building with 24 filter operators
+- Media upload/download
+- Content export/import with relation resolution
+
+## Installation
+
+```bash
+pip install strapi-kit
+```
+
+## Quick Reference
+
+### Imports
+
+```python
+# Core clients and config
+from strapi_kit import SyncClient, AsyncClient, StrapiConfig
+
+# Query building
+from strapi_kit.models import StrapiQuery, FilterBuilder, SortDirection, Populate
+
+# For SecretStr (API tokens)
+from pydantic import SecretStr
+```
+
+### Basic Client Setup
+
+```python
+from strapi_kit import SyncClient, StrapiConfig
+from pydantic import SecretStr
+
+config = StrapiConfig(
+    base_url="http://localhost:1337",
+    api_token=SecretStr("your-api-token"),
+)
+
+# Always use context manager
+with SyncClient(config) as client:
+    response = client.get_many("articles")
+```
+
+### Async Client
+
+```python
+from strapi_kit import AsyncClient, StrapiConfig
+
+async with AsyncClient(config) as client:
+    response = await client.get_many("articles")
+```
+
+## CRUD Operations
+
+### Read
+
+```python
+# Get many (returns NormalizedCollectionResponse)
+response = client.get_many("articles")
+for article in response.data:
+    print(article.id, article.attributes["title"])
+
+# Get one (returns NormalizedSingleResponse)
+response = client.get_one("articles/1")
+article = response.data
+print(article.attributes["title"])
+
+# Raw API (returns dict)
+response = client.get("articles")  # dict
+```
+
+### Create
+
+```python
+data = {"title": "New Article", "content": "Body text"}
+response = client.create("articles", data)
+new_id = response.data.id
+```
+
+### Update
+
+```python
+data = {"title": "Updated Title"}
+response = client.update("articles/1", data)
+```
+
+### Delete
+
+```python
+response = client.remove("articles/1")
+```
+
+## Query Building
+
+### Filters
+
+```python
+from strapi_kit.models import StrapiQuery, FilterBuilder
+
+# Basic equality
+query = StrapiQuery().filter(FilterBuilder().eq("status", "published"))
+
+# Multiple conditions (AND)
+query = StrapiQuery().filter(
+    FilterBuilder()
+        .eq("status", "published")
+        .gt("views", 100)
+        .contains("title", "Python")
+)
+
+# OR conditions
+query = StrapiQuery().filter(
+    FilterBuilder()
+        .eq("status", "published")
+        .or_group(
+            FilterBuilder().gt("views", 1000),
+            FilterBuilder().gt("likes", 500)
+        )
+)
+
+# Available operators
+# eq, ne, gt, gte, lt, lte, contains, not_contains,
+# starts_with, ends_with, in_, not_in, null, not_null,
+# between, is_empty, is_not_empty
+```
+
+### Sorting
+
+```python
+from strapi_kit.models import StrapiQuery, SortDirection
+
+query = (StrapiQuery()
+    .sort_by("publishedAt", SortDirection.DESC)
+    .then_sort_by("title", SortDirection.ASC))
+```
+
+### Pagination
+
+```python
+# Page-based
+query = StrapiQuery().paginate(page=1, page_size=25)
+
+# Offset-based
+query = StrapiQuery().paginate(start=0, limit=50)
+```
+
+### Population (Relations)
+
+```python
+from strapi_kit.models import StrapiQuery, Populate
+
+# Populate all
+query = StrapiQuery().populate_all()
+
+# Specific fields
+query = StrapiQuery().populate_fields(["author", "category"])
+
+# Advanced with nested
+query = StrapiQuery().populate(
+    Populate()
+        .add_field("author", fields=["name", "email"])
+        .add_field("comments", nested=Populate().add_field("author"))
+)
+```
+
+### Complete Query Example
+
+```python
+query = (StrapiQuery()
+    .filter(FilterBuilder().eq("status", "published").gt("views", 100))
+    .sort_by("publishedAt", SortDirection.DESC)
+    .paginate(page=1, page_size=20)
+    .populate_fields(["author", "category"])
+    .select(["title", "slug", "publishedAt"]))
+
+response = client.get_many("articles", query=query)
+```
+
+## Media Operations
+
+### Upload
+
+```python
+# Single file
+media = client.upload_file(
+    "image.jpg",
+    alternative_text="Alt text",
+    caption="Caption"
+)
+print(media.id, media.url)
+
+# Attach to entity
+media = client.upload_file(
+    "cover.jpg",
+    ref="api::article.article",
+    ref_id="abc123",
+    field="cover"
+)
+
+# Multiple files
+media_list = client.upload_files(["img1.jpg", "img2.jpg"])
+```
+
+### Download
+
+```python
+# Get bytes
+content = client.download_file("/uploads/image.jpg")
+
+# Save to file
+client.download_file("/uploads/image.jpg", save_path="local.jpg")
+```
+
+### Manage
+
+```python
+# List media
+response = client.list_media()
+
+# Get specific
+media = client.get_media(42)
+
+# Update metadata
+client.update_media(42, alternative_text="New alt text")
+
+# Delete
+client.delete_media(42)
+```
+
+## Export/Import
+
+```python
+from strapi_kit import StrapiExporter, StrapiImporter
+
+# Export
+with SyncClient(source_config) as client:
+    exporter = StrapiExporter(client)
+    export_data = exporter.export_content_types([
+        "api::article.article",
+        "api::author.author"
+    ])
+    exporter.save_to_file(export_data, "backup.json")
+
+# Import
+with SyncClient(target_config) as client:
+    importer = StrapiImporter(client)
+    export_data = StrapiExporter.load_from_file("backup.json")
+    result = importer.import_data(export_data)
+    print(f"Imported {result.entities_imported} entities")
+```
+
+## Error Handling
+
+```python
+from strapi_kit.exceptions import (
+    StrapiError,          # Base exception
+    AuthenticationError,  # 401
+    AuthorizationError,   # 403
+    NotFoundError,        # 404
+    ValidationError,      # 400
+    ServerError,          # 5xx
+    NetworkError,         # Connection issues
+)
+
+try:
+    response = client.get_one("articles/999")
+except NotFoundError:
+    print("Article not found")
+except AuthenticationError:
+    print("Invalid API token")
+except StrapiError as e:
+    print(f"Strapi error: {e}")
+```
+
+## Response Structure
+
+### NormalizedEntity (from get_one, get_many)
+
+```python
+response = client.get_one("articles/1")
+entity = response.data
+
+entity.id            # int - Entity ID
+entity.document_id   # str | None - v5 documentId (None for v4)
+entity.attributes    # dict - Custom fields {"title": "...", "content": "..."}
+entity.published_at  # datetime | None
+entity.created_at    # datetime | None
+entity.updated_at    # datetime | None
+entity.locale        # str | None
+```
+
+### Pagination Metadata
+
+```python
+response = client.get_many("articles", query)
+
+response.meta.pagination.page        # Current page
+response.meta.pagination.page_size   # Items per page
+response.meta.pagination.page_count  # Total pages
+response.meta.pagination.total       # Total items
+```
+
+## Configuration Options
+
+```python
+from strapi_kit import StrapiConfig, RetryConfig
+
+config = StrapiConfig(
+    base_url="http://localhost:1337",      # Required
+    api_token=SecretStr("token"),          # Required
+    api_version="auto",                    # "auto" | "v4" | "v5"
+    timeout=30.0,                          # Request timeout (seconds)
+    max_connections=10,                    # Connection pool size
+    verify_ssl=True,                       # SSL verification
+    retry=RetryConfig(
+        max_attempts=3,                    # Retry count
+        initial_wait=1.0,                  # First retry delay
+        max_wait=60.0,                     # Max retry delay
+        retry_on_status={500, 502, 503, 504},
+    ),
+)
+```
+
+## Environment Variables
+
+```bash
+STRAPI_BASE_URL=http://localhost:1337
+STRAPI_API_TOKEN=your-token
+STRAPI_TIMEOUT=30.0
+STRAPI_MAX_CONNECTIONS=10
+```
+
+```python
+from strapi_kit import load_config
+
+config = load_config()  # Auto-loads from .env or environment
+```
+
+## Common Patterns
+
+### Content Type UID to Endpoint
+
+```python
+def uid_to_endpoint(uid: str) -> str:
+    """Convert 'api::article.article' to 'articles'.
+
+    Also handles plugin UIDs like 'plugin::users-permissions.user' -> 'users'.
+    """
+    parts = uid.split("::")
+    if len(parts) == 2:
+        # Extract content name from after the dot
+        name_parts = parts[1].split(".")
+        name = name_parts[1] if len(name_parts) > 1 else name_parts[0]
+        # Pluralize
+        if name.endswith("y") and not name.endswith(("ay", "ey", "oy", "uy")):
+            return name[:-1] + "ies"
+        if name.endswith(("s", "x", "z", "ch", "sh")):
+            return name + "es"
+        if not name.endswith("s"):
+            return name + "s"
+        return name
+    return uid
+```
+
+### Iterate All Pages
+
+```python
+page = 1
+while True:
+    query = StrapiQuery().paginate(page=page, page_size=100)
+    response = client.get_many("articles", query=query)
+
+    for item in response.data:
+        process(item)
+
+    if page >= response.meta.pagination.page_count:
+        break
+    page += 1
+```
+
+### Check API Version
+
+```python
+with SyncClient(config) as client:
+    # Make a request first to trigger detection
+    client.get_many("articles", query=StrapiQuery().paginate(1, 1))
+
+    if client.api_version == "v5":
+        # Use documentId
+        pass
+    else:
+        # Use numeric id
+        pass
+```
+
+## Key Files in Codebase
+
+| Path | Purpose |
+|------|---------|
+| `src/strapi_kit/client/sync_client.py` | Synchronous client |
+| `src/strapi_kit/client/async_client.py` | Async client |
+| `src/strapi_kit/client/base.py` | Shared client logic |
+| `src/strapi_kit/models/request/query.py` | StrapiQuery builder |
+| `src/strapi_kit/models/request/filters.py` | FilterBuilder |
+| `src/strapi_kit/models/response/normalized.py` | Response models |
+| `src/strapi_kit/operations/media.py` | Media utilities |
+| `src/strapi_kit/exceptions/errors.py` | Exception hierarchy |
+| `src/strapi_kit/models/config.py` | Configuration models |
+
+## Testing
+
+```python
+import pytest
+from strapi_kit import SyncClient, StrapiConfig
+from pydantic import SecretStr
+
+@pytest.fixture
+def config():
+    return StrapiConfig(
+        base_url="http://localhost:1337",
+        api_token=SecretStr("test-token"),
+    )
+
+# Use respx for HTTP mocking
+import respx
+import httpx
+
+@respx.mock
+def test_get_articles(config):
+    respx.get("http://localhost:1337/api/articles").mock(
+        return_value=httpx.Response(200, json={
+            "data": [{"id": 1, "attributes": {"title": "Test"}}],
+            "meta": {"pagination": {"page": 1, "pageSize": 25, "total": 1}}
+        })
+    )
+
+    with SyncClient(config) as client:
+        response = client.get_many("articles")
+        assert len(response.data) == 1
+```
+
+## Examples
+
+Complete working examples are available in the `examples/` directory:
+
+| File | Description |
+|------|-------------|
+| [`examples/basic_crud.py`](examples/basic_crud.py) | Basic CRUD operations (create, read, update, delete) |
+| [`examples/simple_migration.py`](examples/simple_migration.py) | Simple content migration between Strapi instances |
+| [`examples/full_migration_v5.py`](examples/full_migration_v5.py) | Production-ready migration with auto-discovery |
+| [`examples/MIGRATION_GUIDE.md`](examples/MIGRATION_GUIDE.md) | Comprehensive migration documentation |
+
+### Running Examples
+
+```bash
+# Set environment variables for migration examples
+export SOURCE_STRAPI_TOKEN='your-source-token'
+export TARGET_STRAPI_TOKEN='your-target-token'
+
+# Run basic CRUD
+python examples/basic_crud.py
+
+# Run simple migration
+python examples/simple_migration.py
+
+# Run full migration
+python examples/full_migration_v5.py migrate
+```
+
+## Tips for LLM Agents
+
+1. **Always use context managers** (`with` / `async with`) for clients
+2. **Use typed methods** (`get_many`, `create`) over raw methods (`get`, `post`)
+3. **Build queries incrementally** - chain methods on `StrapiQuery()`
+4. **Handle errors specifically** - catch `NotFoundError` before `StrapiError`
+5. **Check response.data** - it's `None` for 404 on `get_one`
+6. **API prefix is automatic** - use `"articles"` not `"/api/articles"`
+7. **SecretStr for tokens** - always wrap API tokens in `SecretStr`
+8. **v4 vs v5** - use `document_id` for v5, `id` works for both
+9. **File issues** - if something doesn't work as expected, file an issue at https://github.com/MehdiZare/strapi-kit/issues