stapel-listings

Listings and catalog vertical: a Listing core (owner, opaque category, typed attribute values, price + price_base, inventory) with a draft/publish lifecycle including the moderation takedown state 'blocked', an independent moderation status, a value-validation pipeline delegated to stapel-attributes against a category schema fetched over comm, a publish service, first-class favorites, and the two pull seams its consumers read it through — listings.search_documents / listings.search_export for an indexer and listings.moderation_content for a moderation queue.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-listings

At a glance

Documentation

capabilities.json · llms.txt (for agents)

What this is

Listing is the marketplace core: an owner, an opaque category, typed attribute values, a two-machine lifecycle + moderation status, a publish pipeline, and first-class favorites. It consumes stapel-categories (feature schema, over comm) and stapel-attributes (value validation), and stays decoupled from search, moderation and currencies (see the boundaries below).

Quick start

INSTALLED_APPS = [
    # ...
    "stapel_listings",
]

# urls.py
path("listings/", include("stapel_listings.urls"))

Requires a categories.features comm Function provider (stapel-categories) for value validation against a category's schema.

Settings

All configuration lives in the STAPEL_LISTINGS namespace (dict setting, flat setting, or env var — resolved lazily). Full table with seam semantics in MODULE.md.

comm surface

Emits (Actions): listing.submitted (moderation boundary), listing.published / listing.updated / listing.removed (search boundary). Consumes: category.changed, moderation.completed, user.deleted. Provides Functions: listings.status, listings.search_documents, listings.search_export, listings.moderation_content. Calls: categories.features.

Boundaries: search/filtering is a separate stapel-search module; this module builds features_search, signals with the listing.* events and hands over the document through listings.search_documents (keyed batch) and listings.search_export (cursor snapshot), but exposes no search endpoints — the events carry identity, so no listing content rides the durable bus and no indexer reads this database. Moderation is a separate stapel-moderation module: this module emits listing.submitted, serves the content over listings.moderation_content and applies the target-generic moderation.completed verdict (including the published → blocked takedown), but runs no moderation pipeline. Re-moderating an edit of a live listing is post-moderation: the lifecycle stays published, moderation_status goes to pending, the edit is visible immediately, and a rejecting verdict removes it through the takedown edge.

Extension points

See MODULE.md — the agent-facing map of every fork-free seam (settings, serializer seams, comm surface, GDPR provider).

Development

pip install -e . && pip install pytest pytest-django ruff
./setup-hooks.sh
pytest tests/

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}