stapel-listings

CI coverage pypi downloads python license llms.txt

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

Fact Value
Version 0.22.9
Python >=3.11 (3.11, 3.12, 3.13, 3.14)
Django djangorestframework>=3.14
HTTP operations 20
Config axes 3
Usage surface 10
Extension points 6
Error codes 72
Fleet dependencies stapel-attributes · stapel-categories (optional) · stapel-core

Documentation

OpenAPI · 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 — this module's own urls.py bakes in only `v1/`; the host
# contributes `api/`, giving the canonical `/listings/api/v1/...` prefix.
path("listings/api/", 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.

Key Default Meaning
CATEGORY_FEATURES_FUNCTION "categories.features" comm Function resolving a category's feature schema.
PRICE_BASE_CONVERTER identity Dotted-path (amount, currency, base) -> Decimal.
AUTO_APPROVE_ON_PUBLISH False Publish immediately when no moderation module is installed.
REQUIRE_IMAGE_ON_PUBLISH True Require ≥1 image to publish.
MODERATION_TARGET_TYPE "listing" target_type this module answers to in moderation.completed.
LISTING_URL_TEMPLATE "" Public URL template ({listing_id}) for the moderator's card.
DEFAULT_LISTING_TTL_DAYS 30 Days until a published listing expires.

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, listings.rename_feature_keys (the catalogue seam — a feature-slug rename moves the stored draft keys here). Calls: categories.features, categories.children.

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.

Contract

docs/{schema,flows,errors}.json are emitted from a single-module {listings + core} Django instance mounted at the canonical /listings/api/v1 prefix (make contract / make contract-check; see _codegen.py) — the same mechanism stapel-search, stapel-chat and stapel-forms already use. docs/flows.json is []: no flow is declared via @flow yet, same state as every other contract-complete module today.

Delta note — one field stays untyped on purpose. features_search (ListingDetailSerializer) is a flattened per-category search index: one dynamic key per feature slug, shaped by whatever category schema a given listing happens to carry. There is no fixed property set to declare, so the schema types it as a bare object rather than fake a closed shape that would go stale the moment any category adds a feature. Every other field that used to fall back to an untyped blob this way — images / images_draft, both lists of opaque <type>/<hash> CDN refs (models.py "Opaque list of CDN image references") — is now typed as array[string], and the ten polymorphic attribute-value shapes (FeatureDto/FeatureDao) are a proper discriminated oneOf keyed by type, contributed by stapel-attributes.

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.

Project links

Data verified by PyPI on Sep 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.22.11)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ucsoftworks from gravatar.com ucsoftworks

GitHub Statistics

Data verified by PyPI on Sep 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

all

Tags

django stapel listings

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stapel_listings-0.22.9.tar.gz (246.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

stapel_listings-0.22.9-py3-none-any.whl (183.2 kB view details)

Uploaded Python 3

File details

Details for the file stapel_listings-0.22.9.tar.gz.

File metadata

  • Download URL: stapel_listings-0.22.9.tar.gz
  • Upload date:
  • Size: 246.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for stapel_listings-0.22.9.tar.gz
Algorithm Hash digest
SHA256 2fa67668b13cfa1be28c356843e27b897f9fd5c47b1c517dcef208cdf1be1d63
MD5 d6f127d040233ac0bda05f0be6899839
BLAKE2b-256 1dd3a27cb35dcebd76e602065f3d45012cb3ce485a4716dc62faa921338847ec

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_listings-0.22.9.tar.gz:

Publisher: publish.yml on usestapel/stapel-listings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stapel_listings-0.22.9-py3-none-any.whl.

File metadata

File hashes

Hashes for stapel_listings-0.22.9-py3-none-any.whl
Algorithm Hash digest
SHA256 3128e9aed55b4a5161ab37c4e7e2d18537e5ddd99da8dfdd67b4eaa66f545326
MD5 8ec9e2d2959ec47fac8bf9ef3eaf95a8
BLAKE2b-256 730b36df2aada51ba668463cda93ff7239aff92f627da5de9e2471f50d23c7f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_listings-0.22.9-py3-none-any.whl:

Publisher: publish.yml on usestapel/stapel-listings

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.22.11

2 files

0.22.10

2 files

This release

0.22.9 This release

2 files

0.22.8

2 files

0.22.7

2 files

0.22.6

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.6

2 files

0.21.5

2 files

0.21.4

2 files

0.21.3

2 files

0.21.2

2 files

0.21.1

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.17.1

2 files

0.17.0

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.1

2 files

0.11.1

2 files

0.11.0

2 files

0.10.3

2 files

0.10.2

2 files

0.10.1

2 files

0.10.0

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.8

2 files

0.3.7

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page