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

{strapi_kit-0.0.2.dist-info → strapi_kit-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strapi-kit
-Version: 0.0.2
+Version: 0.0.4
 Summary: A modern Python client for Strapi CMS with import/export capabilities
 Project-URL: Homepage, https://github.com/mehdizare/strapi-kit
 Project-URL: Documentation, https://mehdizare.github.io/strapi-kit/
@@ -61,6 +61,7 @@ A modern Python client for Strapi CMS with comprehensive import/export capabilit
 - 🔒 **Type Safe**: Built with Pydantic for robust data validation and type safety
 - 🔄 **Import/Export**: Comprehensive backup/restore and data migration tools
 - 🔁 **Smart Retry**: Automatic retry with exponential backoff for transient failures
+- 🔍 **Schema Introspection**: Content-Type Builder API support for schema discovery
 - 📦 **Modern Python**: Built for Python 3.12+ with full type hints
 
 ## Installation
@@ -654,6 +655,144 @@ asyncio.run(main())
 - Update metadata without re-uploading
 - Full support for both sync and async
 
+### Content-Type Builder API
+
+Query Strapi's Content-Type Builder to discover schemas, content types, and components:
+
+```python
+from strapi_kit import SyncClient, StrapiConfig
+
+config = StrapiConfig(base_url="http://localhost:1337", api_token="your-token")
+
+with SyncClient(config) as client:
+    # List all content types (excludes plugins by default)
+    content_types = client.get_content_types()
+    for ct in content_types:
+        print(f"{ct.uid}: {ct.info.display_name}")
+        # api::article.article: Article
+        # api::category.category: Category
+
+    # Include plugin content types
+    all_types = client.get_content_types(include_plugins=True)
+
+    # List all components
+    components = client.get_components()
+    for comp in components:
+        print(f"{comp.category}/{comp.uid}: {comp.info.display_name}")
+        # shared/shared.seo: SEO
+        # blocks/blocks.hero: Hero Section
+
+    # Get full schema for a content type
+    schema = client.get_content_type_schema("api::article.article")
+    print(f"Display name: {schema.display_name}")
+    print(f"Plural name: {schema.plural_name}")
+
+    # Check field types
+    print(schema.get_field_type("title"))  # "string"
+    print(schema.is_relation_field("author"))  # True
+    print(schema.get_relation_target("author"))  # "api::author.author"
+
+    # Check for components
+    print(schema.is_component_field("seo"))  # True
+    print(schema.get_component_uid("seo"))  # "shared.seo"
+```
+
+**Async version:**
+
+```python
+async with AsyncClient(config) as client:
+    content_types = await client.get_content_types()
+    components = await client.get_components()
+    schema = await client.get_content_type_schema("api::article.article")
+```
+
+### UID Utilities
+
+Utility functions for working with Strapi content type UIDs:
+
+```python
+from strapi_kit.utils import (
+    uid_to_endpoint,
+    uid_to_api_id,  # Alias for uid_to_endpoint
+    api_id_to_singular,
+    uid_to_admin_url,
+    extract_model_name,
+    is_api_content_type,
+)
+
+# Convert UID to API endpoint (pluralized)
+uid_to_endpoint("api::article.article")  # "articles"
+uid_to_endpoint("api::category.category")  # "categories"
+uid_to_endpoint("api::class.class")  # "classes"
+
+# Convert plural API ID to singular
+api_id_to_singular("articles")  # "article"
+api_id_to_singular("categories")  # "category"
+api_id_to_singular("quizzes")  # "quiz" (handles -zzes endings)
+api_id_to_singular("people")  # "person" (handles irregular plurals)
+api_id_to_singular("children")  # "child"
+
+# Build admin panel URL
+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"
+
+# Extract model name from UID
+extract_model_name("api::article.article")  # "article"
+extract_model_name("plugin::users-permissions.user")  # "user"
+
+# Check if UID is an API content type
+is_api_content_type("api::article.article")  # True
+is_api_content_type("plugin::users-permissions.user")  # False
+```
+
+### SEO Configuration Detection
+
+Detect SEO configuration patterns in content type schemas:
+
+```python
+from strapi_kit.utils import detect_seo_configuration, SEOConfiguration
+
+# Detect SEO in a schema dict
+schema = {
+    "uid": "api::article.article",
+    "attributes": {
+        "title": {"type": "string"},
+        "seo": {"type": "component", "component": "shared.seo"},
+    }
+}
+
+config = detect_seo_configuration(schema)
+print(config.has_seo)  # True
+print(config.seo_type)  # "component"
+print(config.seo_field_name)  # "seo"
+print(config.seo_component_uid)  # "shared.seo"
+print(config.fields)  # {"title": "seo.metaTitle", "description": "seo.metaDescription", ...}
+
+# Also detects flat SEO fields
+schema_flat = {
+    "uid": "api::page.page",
+    "attributes": {
+        "metaTitle": {"type": "string"},
+        "metaDescription": {"type": "text"},
+        "ogImage": {"type": "media"},
+    }
+}
+
+config = detect_seo_configuration(schema_flat)
+print(config.has_seo)  # True
+print(config.seo_type)  # "flat"
+print(config.fields)  # {"title": "metaTitle", "description": "metaDescription", "og_image": "ogImage"}
+```
+
+**Supported SEO patterns:**
+
+- **Component-based**: Fields named `seo`, `meta`, `metadata` with type `component`
+- **Component UIDs**: Components with `seo` in the UID (e.g., `shared.seo`, `custom.page-seo`)
+- **Flat fields**: `metaTitle`, `meta_title`, `seoTitle`, `metaDescription`, `ogTitle`, `canonicalUrl`, `noIndex`, etc.
+
 ### Export/Import with Relation Resolution
 
 strapi-kit provides comprehensive export/import functionality with automatic relation resolution for migrating content between Strapi instances.
@@ -732,23 +871,35 @@ We provide two complete migration examples for different use cases:
 Perfect for straightforward migrations with known content types:
 
 ```bash
-# 1. Edit examples/simple_migration.py with your configuration
-# 2. Run the migration
+# Set environment variables (or edit the script)
+export SOURCE_STRAPI_TOKEN='your-source-token'
+export TARGET_STRAPI_TOKEN='your-target-token'
+
+# Run the migration
 python examples/simple_migration.py
 ```
 
 Features:
 - ✅ Single-file, easy to understand
-- ✅ Migrates specific content types
-- ✅ Includes media files
+- ✅ Environment variable support for credentials
+- ✅ Configuration validation before migration
+- ✅ Connection verification for both instances
+- ✅ Timestamped backup files to prevent overwrites
+- ✅ Comprehensive error handling
 - ✅ Automatic relation resolution
-- ✅ Saves backup to JSON
+- ✅ Includes media files
 
 #### Full Migration (Production-Ready)
 
 Comprehensive migration tool with auto-discovery and verification:
 
 ```bash
+# Set environment variables (required)
+export SOURCE_STRAPI_URL="http://localhost:1337"
+export SOURCE_STRAPI_TOKEN="your-source-api-token"
+export TARGET_STRAPI_URL="http://localhost:1338"
+export TARGET_STRAPI_TOKEN="your-target-api-token"
+
 # Export all content from source
 python examples/full_migration_v5.py export
 
@@ -763,6 +914,7 @@ python examples/full_migration_v5.py verify
 ```
 
 Features:
+- ✅ **Environment variable configuration** (no hardcoded credentials)
 - ✅ **Auto-discovers all content types** (no manual configuration needed)
 - ✅ Progress bars for long operations
 - ✅ Detailed migration reports
@@ -946,6 +1098,42 @@ db_config = DatabaseConfig(db_connection)
 client = SyncClient(db_config)
 ```
 
+## Error Handling
+
+strapi-kit provides a rich exception hierarchy for precise error handling:
+
+```python
+from strapi_kit import (
+    StrapiError,           # Base for all errors
+    ConfigurationError,    # Invalid config (missing token, bad URL)
+    ValidationError,       # Invalid input/query params
+    AuthenticationError,   # HTTP 401
+    AuthorizationError,    # HTTP 403
+    NotFoundError,         # HTTP 404
+    ConflictError,         # HTTP 409
+    ServerError,           # HTTP 5xx
+    NetworkError,          # Connection issues (base)
+    RateLimitError,        # HTTP 429
+    ImportExportError,     # Data operations (base)
+    FormatError,           # Invalid data format
+    MediaError,            # Media upload/download errors
+)
+
+try:
+    with SyncClient(config) as client:
+        response = client.get_many("articles")
+except ConfigurationError as e:
+    print(f"Config issue: {e}")
+except ValidationError as e:
+    print(f"Invalid query: {e}")
+except NotFoundError as e:
+    print(f"Not found: {e}")
+except StrapiError as e:
+    print(f"Strapi error: {e}")
+```
+
+All exceptions inherit from `StrapiError`, making it easy to catch all package-specific errors while still allowing precise handling of specific error types.
+
 ## Development
 
 ### Setup
@@ -1045,7 +1233,7 @@ This project is in active development. Currently implemented:
 - **Query Builder**: `StrapiQuery` fluent API with full type safety
 - **Typed Client Methods**: `get_one()`, `get_many()`, `create()`, `update()`, `remove()`
 - **Dependency Injection**: Full DI support with protocols for testability
-- **93% test coverage** with 196 passing tests
+- **Full test coverage** with type-safe query building
 
 ### ✅ Phase 3: Media Operations (Complete)
 - **Media Upload**: Single and batch file uploads with metadata
@@ -1061,13 +1249,19 @@ This project is in active development. Currently implemented:
 - **Media Export**: Download and package media files
 - **Content Import**: Import with ID mapping and relation resolution
 - **Schema Caching**: Efficient content type metadata handling
-- **89% overall test coverage** with 355 passing tests
+- **85% overall test coverage** with 460 passing tests
+
+### ✅ Phase 5: Schema Introspection (Complete)
+- **Content-Type Builder API**: List content types, components, and full schemas
+- **UID Utilities**: Convert UIDs to endpoints, singularize, build admin URLs
+- **SEO Detection**: Detect SEO configuration patterns in schemas
+- **86% overall test coverage** with 528 passing tests
 
-### 🚧 Phase 5-6: Advanced Features (Planned)
+### 🚧 Phase 6: Advanced Features (Planned)
 - Bulk operations with streaming
-- Content type introspection
 - Advanced retry strategies
 - Rate limiting
+- GraphQL support
 
 ### Key Features
 - **Type-Safe**: Full Pydantic validation and mypy strict mode compliance

{strapi_kit-0.0.2.dist-info → strapi_kit-0.0.4.dist-info}/RECORD

@@ -1,28 +1,29 @@
-strapi_kit/__init__.py,sha256=GUV-N5HRlNntClmSVgCUli-vNhmsWb8VyS6huk_TV3Y,2177
+strapi_kit/__init__.py,sha256=z4BR2eysdjTvsFaTqyUX0aPnSODMC2MyhdpvtCgWHVY,2177
 strapi_kit/__version__.py,sha256=oLc_AUMPwiL7J2vgrvXdzVqbSQl2hqkPZ6dNfUx1lTU,478
-strapi_kit/_version.py,sha256=huLsL1iGeXWQKZ8bjwDdIWC7JOkj3wnzBh-HFMZl1PY,704
-strapi_kit/config_provider.py,sha256=T0KQcNLD_2CvC78Efeq9TBwbxN1WnKdWMekrg7fKQe0,12251
+strapi_kit/_version.py,sha256=QlXZ5JTjE_pgpDaeHk0GTExkc75xUZFmd0hA7kGYCJ0,704
+strapi_kit/config_provider.py,sha256=Eky8mH6XgvgrwzsQuAc4gPpbPby_miycxqQH175rlU4,11864
 strapi_kit/protocols.py,sha256=wMeGSFCSxeamv2YDzWWWSVJtiGrm__1Xg00QighEbQ4,10971
 strapi_kit/auth/__init__.py,sha256=VhjbOiyBVSafz3lf2a43bnbSm0J8PG-lguIKHlRplx8,117
 strapi_kit/auth/api_token.py,sha256=FntOxnf18ZdF0YwGjt0J6DM9tlxmIGZGIplqkLvstl0,1419
 strapi_kit/cache/__init__.py,sha256=MpqVNsjbE6_QGEwyxZ80h-PFkB8NzDv7xGxJK1g5agQ,126
 strapi_kit/cache/schema_cache.py,sha256=cmZBS2E0m0YyxpqS7_Z9evDqu_JZxQH086Vv7th7140,6552
 strapi_kit/client/__init__.py,sha256=R9Ux5bCret4mnXItnFh5MxYlMOjoS4bepPX1KpNSs5w,216
-strapi_kit/client/async_client.py,sha256=bj9tMLrTePoMKEECkII1DJ3IoaZ7X4AiB8EwPgBE_IM,35810
-strapi_kit/client/base.py,sha256=2ChQyzy-tZbhRn-fuNirsLn8bOErcIquQP1KX800Sm8,16719
-strapi_kit/client/sync_client.py,sha256=BeykD1MAFpQHZI0WUGhS8cSi8QNOpgOJiQ1568AL0kA,32927
-strapi_kit/exceptions/__init__.py,sha256=zzBuUzGBMhPHcxUMMz8GowRgSALzgP5jsgoUD9-KDHY,698
-strapi_kit/exceptions/errors.py,sha256=9Z_mB2412TZoDXZO8VyaB9PnZEeSXgXOzsAnNqWRI3E,5002
+strapi_kit/client/async_client.py,sha256=GUWFfUABcm6tJgWb9CaoYGhfEu7lmZx_nKUr0v97tJ4,39021
+strapi_kit/client/base.py,sha256=wzjDSH1bZ8us7iIuSJbi6C7cyqIKbiOaIBunMAiiIa0,19923
+strapi_kit/client/sync_client.py,sha256=bJGzhdTedIl2nnZqjzASEyejiOHM8-_AlubItp_IqcY,36078
+strapi_kit/exceptions/__init__.py,sha256=lGjEMAbbKO4MXIodY6jxF5x0WerbSZEnYL_r990tzXM,748
+strapi_kit/exceptions/errors.py,sha256=Yc051k-3tCmT7ybJjQXs9V_i6bh0pY4xW6zmTT7i4PQ,5328
 strapi_kit/export/__init__.py,sha256=s1_1e75FodxpzaC8oWmrXNBUKIXt_0wuhQk5Iz2YUpY,340
-strapi_kit/export/exporter.py,sha256=1DDMt4DcG1RaGBiPqvynFIECcZHf5r_A1lh0Llg_IzE,13945
+strapi_kit/export/exporter.py,sha256=F3ow3NlyutdC-yc-cGZwyAoIVCu-8UnbQyOSrBR4QV0,14056
 strapi_kit/export/importer.py,sha256=8ReQK7UivJGJU78W8RfPCwLSEGcYURzsNlVuI2fvugE,23010
 strapi_kit/export/media_handler.py,sha256=xmx06M4ehtpNpVDwwuppwGpLwRd9s2M-NNnQ7I1T5Pk,11014
 strapi_kit/export/relation_resolver.py,sha256=bXsrY80JWdvzmfFZc0UIpluReg9BWWBdr5SXhEqlaCs,5660
-strapi_kit/models/__init__.py,sha256=j1wg_hUY4YFycZR3jzYhOQ5wt2ajnSLzIJ_bWTvBAXQ,3104
+strapi_kit/models/__init__.py,sha256=zm-V86_4yWVS0LGezajQvK0lALmHiZtX8o0tC0QVBk0,3441
 strapi_kit/models/bulk.py,sha256=g1swXgk8nWE_C-u6LIwKJzk2E5xmqMxDMQgY6SzxY7Q,2100
 strapi_kit/models/config.py,sha256=Nq1pWlDc50wSV3RvQseKG688zlHw8vlNFRZqAPtvj0Q,4543
+strapi_kit/models/content_type.py,sha256=AIONiPq6-ZyNdoAygiR1_ynh-s2d5ti2GvtmnaktzMs,4150
 strapi_kit/models/enums.py,sha256=sxxlBNwOyxasqI7hwTanrv1kppseIkNUf-3SJF15TH8,2939
-strapi_kit/models/export_format.py,sha256=Ii-mow_ekt_1O-oLKa5VEdsJdO--RvouOSSrWi3H4IA,5301
+strapi_kit/models/export_format.py,sha256=x8cH-uktCaUVxOJCVtLdS1gs3NpNqTqExWQa5wWoEqc,5351
 strapi_kit/models/import_options.py,sha256=aRjWSI2ZOPl8j0ZiLlR8TfAjLrpzn7HBpK1LQ3Rt1IA,4795
 strapi_kit/models/schema.py,sha256=qNU7v_HF0AESDqmmKmMy_ERPOI-zUqFCujlAjTZ1Lo8,2489
 strapi_kit/models/request/__init__.py,sha256=RvuVgPvc2tAx9A_Esh04SZZ5Oi1GFiYpxdg90TLsd6A,54
@@ -30,7 +31,7 @@ strapi_kit/models/request/fields.py,sha256=VrPyf0Pg_EQ3z2IyzBhaw_4fr7N5VWJRcN2Li
 strapi_kit/models/request/filters.py,sha256=3qMzI8cTMfYCFWRAGMbw6DmEBtD2yUWB4UswABQavR4,19274
 strapi_kit/models/request/pagination.py,sha256=hXFp534JutocVgWN0L0kInwSVGmhzhCJGTPdNzpJpUc,5244
 strapi_kit/models/request/populate.py,sha256=xYjOFdauqxHtIEaYI5w-hXeX92TcfIdYGybJzrSdxYA,9399
-strapi_kit/models/request/query.py,sha256=46lLU7fajwHbqtnawedqZ4zXekX74y-MdhriGd8sz0c,14855
+strapi_kit/models/request/query.py,sha256=3s9TQlskxCb6ShCj9Lyu6Se4whRpuaxsriZukPAdPDQ,15074
 strapi_kit/models/request/sort.py,sha256=BJqBt5ZEw3LkyHWfKHmQ7NtOtZMWFP3tNxdgbrsSJhw,4654
 strapi_kit/models/response/__init__.py,sha256=1Cn009-Zp-vLcRSV-E65TaszK1b09qCVi6_LNKHBMNo,56
 strapi_kit/models/response/base.py,sha256=mutKKPSUMdd4Jsg7bv18bad9OwNUdKHjutHDloz9_5E,1982
@@ -42,14 +43,15 @@ strapi_kit/models/response/relation.py,sha256=wZb4HIwM6RChZmFDbtKgLjunGS1dauxwm8
 strapi_kit/models/response/v4.py,sha256=7i-HmNIkL6alyM0o7Y-u3v57O8ROMYH4w0HH95_p9iw,1996
 strapi_kit/models/response/v5.py,sha256=bXHK4TH15aUy3ssxZZBz2myI6JR4BYnrSRWitju1HoQ,1838
 strapi_kit/operations/__init__.py,sha256=9tUk9gZQQThF93jXjB38XM20rPCfp6QVhgmiYTC28AY,355
-strapi_kit/operations/media.py,sha256=v6RBuy4TWqVz7yMgIiOls38fEs7HjClCWL-Z2O5Ntr8,7144
-strapi_kit/operations/streaming.py,sha256=RVwzB4LSlUtHdmTyltKEUriW41PVEc6AfCJh-WfWS1k,4735
+strapi_kit/operations/media.py,sha256=26eUo-o6UDtHOKNuVc8bvoXht037-bH114glLvk-RQg,7498
+strapi_kit/operations/streaming.py,sha256=A6Czlq_c2yIc7vQMx4OwLURBgdTPnnOfa80z-Mw5pMQ,4796
 strapi_kit/parsers/__init__.py,sha256=-4WSHKbFhnbOB4j7MF2qyktgkb6t8RY3slTYKV4vhvg,142
 strapi_kit/parsers/version_detecting.py,sha256=i6Wh7NSQYPWSv0GR63ZJLuPF6BqFwQ_Y7J3q7l7h1JQ,6421
-strapi_kit/utils/__init__.py,sha256=kQdkXpAw3IgAG4fcKF7FswYag8o7MUWnwM-AA578_4g,368
-strapi_kit/utils/rate_limiter.py,sha256=sm-p7aAqsri0sHsj3bYbv9ib022goBXGtMgTsFEIlUs,6306
-strapi_kit/utils/uid.py,sha256=DRRa9MNkcQDI2RNEkwAjWK9HMx8Sg4Waxi8uA2fdPAg,2636
-strapi_kit-0.0.2.dist-info/METADATA,sha256=XgFc69X1JvE_MJ8TppUDXbz1yGTkmk9xMU5EQTiJFvU,31236
-strapi_kit-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-strapi_kit-0.0.2.dist-info/licenses/LICENSE,sha256=lN0YUtXlAFBt9MNYr2F0GJEYdprxDOTIqcVhKxMsaTI,1067
-strapi_kit-0.0.2.dist-info/RECORD,,
+strapi_kit/utils/__init__.py,sha256=FFSuu9W6Yt1r0OEU55bs9zLz2RuAy0wCVPfzN2BRz7E,823
+strapi_kit/utils/rate_limiter.py,sha256=c-oAgCILG-6nrjhxIXEx3sKqRgkxOHcNJE496ix7aVA,6367
+strapi_kit/utils/seo.py,sha256=p1CR3NGPJfarLosqRa3PAgigS9l9IB_LXUMjaZBXDeM,9317
+strapi_kit/utils/uid.py,sha256=IcGlFKxtyIIWm9TKVMDX4WseSCMS5FLLDNJItSZgIoA,6797
+strapi_kit-0.0.4.dist-info/METADATA,sha256=p7pz_bu7WnJR-3g9HenyV7hnYh-N1sGsJ_zAYKcp5TI,38069
+strapi_kit-0.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+strapi_kit-0.0.4.dist-info/licenses/LICENSE,sha256=lN0YUtXlAFBt9MNYr2F0GJEYdprxDOTIqcVhKxMsaTI,1067
+strapi_kit-0.0.4.dist-info/RECORD,,