stapel-categories 0.1.0__tar.gz

stapel_categories-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_categories-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: stapel-categories
+Version: 0.1.0
+Summary: Category tree for the Stapel framework
+License: MIT
+Keywords: django,stapel,categories
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Requires-Dist: stapel-attributes<0.2,>=0.1
+Requires-Dist: django-treenode<0.24,>=0.23
+Requires-Dist: drf-spectacular>=0.27
+Provides-Extra: all
+Dynamic: license-file
+
+# stapel-categories
+
+Category tree with typed features for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices without
+changing module code.
+
+A hierarchical **category** tree (django-treenode) and a parallel **feature**
+tree whose typed `config` is validated by
+[stapel-attributes](https://github.com/usestapel/stapel-attributes). Categories
+own the tree structure, feature inheritance, the ordered category↔feature M2M,
+and the feature-editor lifecycle; the attribute *engine* (types, config/DTO/DAO
+validation, polymorphic serializers, admin widgets) lives in stapel-attributes
+and is imported, never re-implemented.
+
+## Install
+
+```bash
+pip install stapel-categories
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "treenode",            # django-treenode (tree-cache signals)
+    "stapel_categories",
+]
+
+# urls.py — the host chooses the prefix
+path("categories/", include("stapel_categories.urls"))
+```
+
+`stapel-attributes` is an imported library (no app to install); its config
+editor ships static assets, so run `collectstatic` if you use the admin.
+
+## Settings
+
+All configuration lives in the `STAPEL_CATEGORIES` namespace (dict setting,
+flat setting, or env var — resolved lazily):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `CAROUSEL_CACHE_TIMEOUT` | `300` | Seconds the `carousel` response is cached. |
+| `FEATURE_DISPLAY_CACHE_TIMEOUT` | `60` | Seconds an admin feature display label is memoized. |
+| `DISPLAY_TRANSLATOR` | `stapel_categories.translation.identity_translator` | Dotted path `(key)->str` for rendering translation keys (default: identity). |
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Function | `categories.features` | `{"category_id": int}` -> `{"category_id", "revision", "features":[{id,slug,name,mandatory,config}]}` — resolved schema (own + inherited), cacheable by `revision` |
+| Action (emit) | `category.changed` | `{"category_id": int, "revision": int}` on any category/feature mutation — for downstream cache invalidation |
+
+`categories.features` lets stapel-listings validate attribute values against a
+category's schema without importing this module.
+
+## Extension points
+
+See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
+(settings, serializer seams, comm surface, feature-editor actions, admin-UI
+pointer to stapel-attributes).
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_categories-0.1.0/README.md

@@ -0,0 +1,72 @@
+# stapel-categories
+
+Category tree with typed features for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices without
+changing module code.
+
+A hierarchical **category** tree (django-treenode) and a parallel **feature**
+tree whose typed `config` is validated by
+[stapel-attributes](https://github.com/usestapel/stapel-attributes). Categories
+own the tree structure, feature inheritance, the ordered category↔feature M2M,
+and the feature-editor lifecycle; the attribute *engine* (types, config/DTO/DAO
+validation, polymorphic serializers, admin widgets) lives in stapel-attributes
+and is imported, never re-implemented.
+
+## Install
+
+```bash
+pip install stapel-categories
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "treenode",            # django-treenode (tree-cache signals)
+    "stapel_categories",
+]
+
+# urls.py — the host chooses the prefix
+path("categories/", include("stapel_categories.urls"))
+```
+
+`stapel-attributes` is an imported library (no app to install); its config
+editor ships static assets, so run `collectstatic` if you use the admin.
+
+## Settings
+
+All configuration lives in the `STAPEL_CATEGORIES` namespace (dict setting,
+flat setting, or env var — resolved lazily):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `CAROUSEL_CACHE_TIMEOUT` | `300` | Seconds the `carousel` response is cached. |
+| `FEATURE_DISPLAY_CACHE_TIMEOUT` | `60` | Seconds an admin feature display label is memoized. |
+| `DISPLAY_TRANSLATOR` | `stapel_categories.translation.identity_translator` | Dotted path `(key)->str` for rendering translation keys (default: identity). |
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Function | `categories.features` | `{"category_id": int}` -> `{"category_id", "revision", "features":[{id,slug,name,mandatory,config}]}` — resolved schema (own + inherited), cacheable by `revision` |
+| Action (emit) | `category.changed` | `{"category_id": int, "revision": int}` on any category/feature mutation — for downstream cache invalidation |
+
+`categories.features` lets stapel-listings validate attribute values against a
+category's schema without importing this module.
+
+## Extension points
+
+See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
+(settings, serializer seams, comm surface, feature-editor actions, admin-UI
+pointer to stapel-attributes).
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_categories-0.1.0/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-categories — Category tree for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``categories_settings`` — resolved app settings (``stapel_categories.conf``).
+"""
+
+__all__ = [
+    "categories_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_categories` stays Django-free.
+_LAZY_EXPORTS = {
+    "categories_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_categories-0.1.0/admin.py

@@ -0,0 +1,211 @@
+"""Django admin for Category and Feature.
+
+The config editor UI is supplied by stapel-attributes (its ``ConfigEditorWidget``
+ships the Lit bundle via ``Media``); this module wires the models, the
+feature-editor forms, and validation admin-actions that delegate to the
+attribute engine. CDN icons are opaque strings — no cdn dependency, no
+image preview coupling.
+"""
+from django.contrib import admin
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.utils.html import format_html
+from django.utils.safestring import mark_safe
+from django.utils.translation import gettext_lazy as _
+from treenode.admin import TreeNodeModelAdmin
+
+from stapel_attributes import get_feature_type, parse_config
+from stapel_core.django.admin.mixins import RevisionAdmin
+
+from .forms import CategoryAdminForm, FeatureAdminForm
+from .models import Category, CategoryFeature, Feature
+
+
+class SubFeatureInline(admin.TabularInline):
+    model = Feature
+    fields = ["name", "slug", "config", "mandatory", "show_as_badge", "show_at_title", "translate", "tn_priority"]
+    show_change_link = True
+    extra = 1
+
+
+class FeatureCategoryInline(admin.TabularInline):
+    model = CategoryFeature
+    fk_name = "feature"
+    fields = ["category", "order"]
+    show_change_link = True
+    extra = 0
+    ordering = ["order", "id"]
+
+
+@admin.register(Category)
+class CategoryAdmin(RevisionAdmin, TreeNodeModelAdmin):
+    """Category admin with revision tracking + treenode display.
+
+    Inlines are intentionally omitted — use the Feature Editor and Children
+    Editor screens (built on stapel-attributes components) instead.
+    """
+
+    form = CategoryAdminForm
+    inlines = []
+    autocomplete_fields = ["tn_parent"]
+
+    list_display = [
+        "name_with_status", "tn_priority", "feature_count", "active",
+        "carousel_enabled", "catalog_icon", "carousel_icon", "translatable",
+        "revision", "deleted",
+    ]
+    list_filter = ["active", "carousel_enabled", "translatable", "deleted"]
+    search_fields = ["name", "slug"]
+    readonly_fields = ["revision"]
+    actions = ["undelete_branch", "validate_category_features"]
+
+    fieldsets = (
+        ("Basic Information", {
+            "fields": ("tn_parent", "translatable", "slug", "name", "comment", "active", "tn_priority"),
+        }),
+        ("Icons", {
+            "fields": ("catalog_icon", "carousel_icon", "carousel_enabled"),
+            "description": "CDN asset references as opaque strings (e.g. catalog/electronics).",
+        }),
+        ("Feature Editor", {"fields": ("draft",), "description": "Manage features for this category"}),
+        ("Advanced", {"fields": ("revision",), "classes": ("collapse",)}),
+    )
+
+    @admin.display(description="ID / Slug", ordering="slug")
+    def name_with_status(self, obj):
+        id_badge = format_html(
+            '<span style="color:#888;font-size:11px;margin-right:4px;">{}</span>', obj.id
+        )
+        if obj.deleted:
+            return format_html(
+                "{}"
+                '<span style="color:#e74c3c;text-decoration:line-through;opacity:0.6;">{}</span> '
+                '<span style="background:#e74c3c;color:#fff;padding:2px 6px;border-radius:3px;'
+                'font-size:10px;font-weight:bold;">DELETED</span>',
+                id_badge, obj.slug,
+            )
+        return format_html("{}{}", id_badge, obj.slug)
+
+    @admin.display(description="Features")
+    def feature_count(self, obj):
+        return obj.features.count()
+
+    @admin.action(description=_("Undelete category branch (category and all descendants)"))
+    def undelete_branch(self, request, queryset):
+        count = 0
+        for category in queryset:
+            if category.deleted:
+                category.deleted = False
+                category.save()
+                count += 1
+                descendants_pks = category.tn_descendants_pks
+                if descendants_pks:
+                    descendant_ids = [int(pk) for pk in str(descendants_pks).split(",") if pk]
+                    count += Category.objects.filter(
+                        id__in=descendant_ids, deleted=True
+                    ).update(deleted=False)
+        self.message_user(request, _("%d category/categories restored (including descendants).") % count)
+
+    @admin.action(description=_("Validate feature configs in category"))
+    def validate_category_features(self, request, queryset):
+        errors_by_category = []
+        categories_with_errors = 0
+        validated_features = {}
+
+        for category in queryset:
+            all_features = list(category.get_all_features())
+            invalid_results = []
+            for feature in all_features:
+                if feature.pk in validated_features:
+                    result = validated_features[feature.pk]
+                else:
+                    result = _validate_feature(feature)
+                    validated_features[feature.pk] = result
+                if result is not None:
+                    invalid_results.append(result)
+
+            if invalid_results:
+                categories_with_errors += 1
+                lines = [f"Category: {category.name} ({category.slug}) [id={category.pk}] "
+                         f"— {len(invalid_results)} error(s) of {len(all_features)} feature(s)"]
+                for result in invalid_results:
+                    lines.append(
+                        f"  - feature {result['id']} ({result['slug']}): {result['error']}"
+                    )
+                errors_by_category.append("\n".join(lines))
+
+        if categories_with_errors > 0:
+            message = (
+                f"Found errors in {categories_with_errors} of {queryset.count()} category/categories:\n\n"
+                + "\n".join(errors_by_category)
+            )
+            self.message_user(request, message, level="error")
+        else:
+            self.message_user(request, f"All features in {queryset.count()} category/categories are valid.")
+
+
+@admin.register(Feature)
+class FeatureAdmin(TreeNodeModelAdmin):
+    form = FeatureAdminForm
+    inlines = [SubFeatureInline, FeatureCategoryInline]
+    autocomplete_fields = ["tn_parent"]
+    list_display = [
+        "name", "slug", "feature_type_display", "config_status", "mandatory",
+        "show_as_badge", "show_at_title", "translate", "tn_priority",
+    ]
+    list_filter = ["mandatory", "show_as_badge", "show_at_title", "translate"]
+    search_fields = ["name", "slug", "comment"]
+    actions = ["validate_configs"]
+
+    fieldsets = (
+        ("Basic Information", {
+            "fields": ("tn_parent", "translate", "slug", "name", "icon", "comment", "tn_priority"),
+        }),
+        ("Type Configuration", {"fields": ("config",)}),
+        ("Display Options", {"fields": ("mandatory", "show_as_badge", "show_at_title")}),
+    )
+
+    @admin.display(description="Type")
+    def feature_type_display(self, obj):
+        return obj.feature_type
+
+    @admin.display(description="Config")
+    def config_status(self, obj):
+        result = _validate_feature(obj)
+        if result is None:
+            return mark_safe('<span style="color:#27ae60;font-size:16px;" title="Config is valid">&#10003;</span>')
+        return format_html(
+            '<span style="color:#e74c3c;font-size:16px;" title="{}">&#10007;</span>', result["error"]
+        )
+
+    @admin.action(description=_("Validate feature configs"))
+    def validate_configs(self, request, queryset):
+        errors = []
+        valid_count = 0
+        for feature in queryset:
+            result = _validate_feature(feature)
+            if result is None:
+                valid_count += 1
+            else:
+                errors.append(
+                    f"id={feature.pk} name={feature.name} slug={feature.slug}: {result['error']}"
+                )
+        if errors:
+            message = (
+                f"Validation failed for {len(errors)} of {queryset.count()} feature(s):\n\n"
+                + "\n".join(errors)
+            )
+            self.message_user(request, message, level="error")
+        else:
+            self.message_user(request, f"All {valid_count} feature(s) are valid.")
+
+
+def _validate_feature(feature):
+    """Validate one feature's config via stapel-attributes. Returns None if valid."""
+    try:
+        config = parse_config(feature.get_config_with_defaults())
+        feature_type = get_feature_type(config.type)
+        feature_type.validate_config(config)
+        return None
+    except (DjangoValidationError, ValueError) as exc:
+        error_msg = str(exc.messages[0]) if hasattr(exc, "messages") else str(exc)
+        return {"id": feature.pk, "slug": feature.slug, "name": feature.name, "error": error_msg}

stapel_categories-0.1.0/apps.py

@@ -0,0 +1,15 @@
+from django.apps import AppConfig
+
+
+class CategoriesConfig(AppConfig):
+    name = "stapel_categories"
+    label = "categories"
+    verbose_name = "Category tree"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: comm functions/actions, system checks,
+        # error-key registration. Keep each in its own module.
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+        from . import functions  # noqa: F401

stapel_categories-0.1.0/checks.py

@@ -0,0 +1,16 @@
+"""Django system checks for stapel-categories configuration.
+
+Policy (docs/library-standard.md §3.7): E-level for configuration the
+service cannot run with; W-level for entries that degrade lazily (a broken
+*unused* dotted path must not block deploys).
+
+Example:
+
+    from django.core import checks
+
+    @checks.register(checks.Tags.compatibility)
+    def check_default_provider(app_configs, **kwargs):
+        if ...:
+            return [checks.Error("...", id="stapel_categories.E001")]
+        return []
+"""

stapel_categories-0.1.0/conf.py

@@ -0,0 +1,32 @@
+"""Settings namespace for stapel-categories.
+
+All configuration is read through ``categories_settings`` (lazily, at call
+time) — never via module-level ``os.getenv`` (values would freeze at import).
+Resolution order per key: ``settings.STAPEL_CATEGORIES`` dict -> flat Django
+setting of the same name -> environment variable -> default below.
+
+Dotted-path keys listed in ``import_strings`` are resolved with
+``import_string`` — the fork-free escape hatch for swappable behavior.
+"""
+from stapel_core.conf import AppSettings
+
+categories_settings = AppSettings(
+    "STAPEL_CATEGORIES",
+    defaults={
+        # Seconds the ``categories/carousel`` response is cached in the
+        # Django cache backend.
+        "CAROUSEL_CACHE_TIMEOUT": 300,
+        # Seconds an admin feature display-name translation is memoized.
+        "FEATURE_DISPLAY_CACHE_TIMEOUT": 60,
+        # Dotted path to a callable ``(key: str) -> str`` used to render a
+        # translation key for admin/``__str__`` display (single strategy,
+        # REPLACE semantics). Default is identity: this module stores
+        # translation *keys* and does not resolve them — a host that wants
+        # resolved names points this at its translation backend (e.g. a
+        # wrapper over the ``translate.resolve`` comm Function).
+        "DISPLAY_TRANSLATOR": "stapel_categories.translation.identity_translator",
+    },
+    import_strings=("DISPLAY_TRANSLATOR",),
+)
+
+__all__ = ["categories_settings"]

stapel_categories-0.1.0/conftest.py

@@ -0,0 +1,87 @@
+def pytest_configure(config):
+    from django.conf import settings
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.staticfiles",
+                "django.contrib.admin",
+                "django.contrib.messages",
+                "stapel_core.django.users",
+                "rest_framework",
+                # treenode (django-treenode) registers the tree-cache signals
+                # its AppConfig.ready() wires up — required for tn_* fields.
+                "treenode",
+                # stapel_attributes is an L1 library (no Django app); imported,
+                # not installed. Categories depends on its type registry.
+                "stapel_categories",
+            ],
+            AUTH_USER_MODEL="users.User",
+            STATIC_URL="/static/",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            ROOT_URLCONF="stapel_categories.tests.urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                },
+            },
+            # Synchronous in-process comm with schema validation ON, so the
+            # committed contracts in schemas/ are enforced by the tests.
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            STAPEL_COMM={
+                "OUTBOX_ENABLED": False,
+                "ACTION_TRANSPORT": "inprocess",
+                "VALIDATE_SCHEMAS": True,
+            },
+            MIGRATION_MODULES={
+                "users": None,
+            },
+        )
+        import django
+        django.setup()
+
+        from stapel_core.comm.schemas import autoload_schemas
+        autoload_schemas()
+
+
+import pytest  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def _clear_treenode_state():
+    """django-treenode keeps two process-global stores that survive the
+    per-test transaction rollback: a tree cache (Django cache backend) and a
+    WeakSet of live model instances it back-fills tn_* fields into
+    (``treenode.memory.__refs__``). Under sqlite ``:memory:`` PKs are reused
+    across rolled-back tests, so a stale ref/cache entry from an earlier test
+    would shadow a new instance with the same PK — clear both around every
+    test so tree lookups are always recomputed from the current DB."""
+    from django.core.cache import cache
+    from treenode.memory import clear_refs
+
+    from stapel_categories.models import Category, Feature
+
+    def _reset():
+        cache.clear()
+        clear_refs(Category)
+        clear_refs(Feature)
+
+    _reset()
+    yield
+    _reset()
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+    return APIClient()

stapel_categories-0.1.0/dto.py

@@ -0,0 +1,25 @@
+"""Dataclass DTOs — the API models of stapel-categories (never ORM instances)."""
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class UndeleteResponse:
+    """Restored soft-deleted categories.
+
+    Attributes:
+        restored: List of restored category IDs. Example: [1, 2, 3]
+    """
+
+    restored: List[int]
+
+
+@dataclass
+class FeatureEditorDraftResponse:
+    """Feature editor draft state.
+
+    Attributes:
+        draft: JSON-encoded draft string, null if no draft saved. Example: {"features": []}
+    """
+
+    draft: Optional[str]

stapel_categories-0.1.0/errors.py

@@ -0,0 +1,34 @@
+"""i18n error keys of stapel-categories.
+
+Only ``error.<status>.<slug>`` keys leave this package — human-readable
+strings are translations, never literals in responses.
+"""
+from stapel_core.django.api.errors import register_service_errors
+
+ERR_400_EXPECTED_LIST = "error.400.categories_expected_list"
+ERR_400_DUPLICATE_SLUG = "error.400.categories_duplicate_slug"
+ERR_400_DATABASE_ERROR = "error.400.categories_database_error"
+ERR_400_CATEGORY_NOT_DELETED = "error.400.categories_not_deleted"
+ERR_400_INVALID_CONVERSION = "error.400.categories_invalid_conversion"
+ERR_400_CONFIG_REQUIRED = "error.400.categories_config_required"
+
+STAPEL_CATEGORIES_ERRORS = {
+    ERR_400_EXPECTED_LIST: "Expected a list of objects",
+    ERR_400_DUPLICATE_SLUG: "A feature with slug '{slug}' already exists",
+    ERR_400_DATABASE_ERROR: "Database error while applying changes",
+    ERR_400_CATEGORY_NOT_DELETED: "Category is not deleted",
+    ERR_400_INVALID_CONVERSION: "Invalid type conversion (only select<->string is supported)",
+    ERR_400_CONFIG_REQUIRED: "A config object is required",
+}
+
+register_service_errors(STAPEL_CATEGORIES_ERRORS)
+
+__all__ = [
+    "STAPEL_CATEGORIES_ERRORS",
+    "ERR_400_EXPECTED_LIST",
+    "ERR_400_DUPLICATE_SLUG",
+    "ERR_400_DATABASE_ERROR",
+    "ERR_400_CATEGORY_NOT_DELETED",
+    "ERR_400_INVALID_CONVERSION",
+    "ERR_400_CONFIG_REQUIRED",
+]

stapel_categories-0.1.0/events.py

@@ -0,0 +1,31 @@
+"""comm event publishers for stapel-categories.
+
+Events go through ``stapel_core.comm`` (transport is deployment
+configuration: in-process in a monolith, bus in microservices). Emitted
+through the transactional outbox, so the event leaves iff the surrounding
+DB transaction commits. Payload contract lives in
+``schemas/emits/category.changed.json``.
+
+Downstream consumers (e.g. stapel-listings) subscribe to ``category.changed``
+to invalidate any cached ``categories.features`` result for that category.
+"""
+
+
+def publish_category_changed(category_id, revision):
+    """Emit ``category.changed`` for a mutated category (or feature affecting it).
+
+    Deliberately does NOT swallow failures: ``emit`` runs inside the mutating
+    ``save()``'s atomic block, so a raise rolls the mutation back. That is the
+    whole point of the transactional outbox — the event and the row it
+    describes commit together or not at all. Swallowing here would let a
+    mutation commit with no event, leaving every downstream
+    ``categories.features`` cache silently stale (a cache-invalidation
+    contract can't tolerate a lost invalidation). Let it propagate.
+    """
+    from stapel_core.comm import emit
+
+    emit(
+        "category.changed",
+        {"category_id": int(category_id), "revision": int(revision or 0)},
+        key=str(category_id),
+    )