stapel-reviews

Target-generic reviews and ratings for the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

A generic review core — Review (author + rating + body about an opaque target) and Response (the target owner's reply) — driven entirely by a per-target-type policy registry. The module ships knowing nothing about what gets reviewed: a host registers its target types (a seller, a listing, a driver, a course), each with a policy, and answers the domain questions — "may this author review?", "who owns this target?" — through comm Function callbacks, so the module never imports a host model.

Install

pip install stapel-reviews

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

# urls.py
path("reviews/", include("stapel_reviews.urls"))

Concepts

Target — opaque: target_type (a key the host registered) + target_key (an opaque host string — a UUID, a slug, a composite). No FK to any host model; the module is domain-blind.
Policy — per target type: who may review (can_review comm callback), pre/post moderation, one-review-per-author, whether owner responses are allowed (allow_response), who may moderate/respond (can_moderate comm callback).
Aggregate — the module owns avg/count over published reviews per target, and emits a generic fact carrying it on every visibility change, so a host catalog maintains its own rating projection (§10) without calling back.

STAPEL_REVIEWS = {
    "TARGET_TYPES": {
        "seller": {
            "can_review": "marketplace.buyer_of_seller",   # host comm Function
            "can_moderate": "marketplace.is_seller_owner",
            "moderation": "post",
            "one_per_author": True,
            "allow_response": True,
        },
        "listing": {"moderation": "pre"},
    },
}

from stapel_reviews import services

review = services.create_review(
    target_type="seller", target_key="s-42", author=user, rating=5, body="great",
)
services.moderate_review(review, actor=owner, action="hide", reason="spam")
services.respond(review, author=owner, body="thanks for the feedback")
agg = services.aggregate("seller", "s-42")   # Aggregate(avg=..., count=...)

Settings

All configuration lives in the STAPEL_REVIEWS namespace (dict setting, flat setting, or env var — resolved lazily):

Key	Default	Meaning
`TARGET_TYPES`	`{}`	The target-type registry `{type: policy}`, merged over the (empty) built-ins; `None` removes a type
`MODERATION_DEFAULT`	`"post"`	Default moderation mode (`post`/`pre`) for types that don't override it
`RESPONSES`	`True`	Whether owner responses are allowed by default
`RATING_MIN`	`1`	Inclusive minimum rating
`RATING_MAX`	`5`	Inclusive maximum rating

comm surface

Kind	Name	Contract
Emit	`reviews.review.published`	A review became visible — carries `{aggregate: {avg, count}}` for the host projection
Emit	`reviews.review.hidden`	A review left the visible set — carries the updated aggregate
Function	`reviews.aggregate`	`{target_type, target_key}` -> `{avg, count}`
Callback (host)	policy `can_review`	`{author_id, target_type, target_key}` -> bool — the host answers
Callback (host)	policy `can_moderate`	`{actor_id, target_type, target_key}` -> bool — the host answers

Extension points

See MODULE.md — the agent-facing map of every fork-free seam (the TARGET_TYPES registry and its policy callbacks, the projection emits, the aggregate Function, serializer seams, settings).

Development

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

License

MIT

Development Status
- 3 - Alpha
Framework
- Django
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
Typing
- Typed

Download files

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

Source Distribution

stapel_reviews-0.1.8.tar.gz (41.0 kB view details)

Uploaded Aug 2, 2026 Source

Built Distribution

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

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

stapel_reviews-0.1.8-py3-none-any.whl (42.4 kB view details)

Uploaded Aug 2, 2026 Python 3

File details

Details for the file stapel_reviews-0.1.8.tar.gz.

File metadata

Download URL: stapel_reviews-0.1.8.tar.gz
Upload date: Aug 2, 2026
Size: 41.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for stapel_reviews-0.1.8.tar.gz
Algorithm	Hash digest
SHA256	`184fc61938a6839e7a514e6e6e5873463de4463cf2ef9ffe23b40d895c6d211c`
MD5	`75ffac82339e6a9a5798348b9e52d25c`
BLAKE2b-256	`4a95f0c0fca449c146bbd504d39eb40628118c77c6d94b9598cac0278e3d564d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_reviews-0.1.8.tar.gz:

Publisher: publish.yml on usestapel/stapel-reviews

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: stapel_reviews-0.1.8.tar.gz
- Subject digest: 184fc61938a6839e7a514e6e6e5873463de4463cf2ef9ffe23b40d895c6d211c
- Sigstore transparency entry: 2326406075
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: usestapel/stapel-reviews@23ed846e28d682dc68602218cd2aa02be8a08382
- Branch / Tag: refs/tags/v0.1.8
- Owner: https://github.com/usestapel
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@23ed846e28d682dc68602218cd2aa02be8a08382
- Trigger Event: push