Metadata-Version: 2.4
Name: stapel-shop
Version: 0.2.3
Summary: Composite: catalog shop — categories + attributes + listings + reviews, with cross-domain glue projections
License: MIT
Project-URL: Homepage, https://github.com/usestapel/stapel-shop
Project-URL: Repository, https://github.com/usestapel/stapel-shop
Project-URL: Documentation, https://github.com/usestapel/stapel-shop#readme
Project-URL: Changelog, https://github.com/usestapel/stapel-shop/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/usestapel/stapel-shop/issues
Keywords: django,stapel,shop,composite,marketplace
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: stapel-core<1.0,>=0.10
Requires-Dist: stapel-categories<0.6,>=0.4
Requires-Dist: stapel-attributes<0.5,>=0.3
Requires-Dist: stapel-listings<0.7,>=0.4
Requires-Dist: stapel-reviews<0.4,>=0.2
Provides-Extra: all
Dynamic: license-file

<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->

# stapel-shop

[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-shop/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-shop/actions/workflows/ci.yml?query=branch%3Amain)
[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-shop?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-shop)
[![pypi](https://img.shields.io/pypi/v/stapel-shop?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-shop/)
[![downloads](https://static.pepy.tech/badge/stapel-shop/month)](https://pepy.tech/project/stapel-shop)
[![python](https://img.shields.io/pypi/pyversions/stapel-shop?logo=python&logoColor=white)](https://pypi.org/project/stapel-shop/)
[![license](https://img.shields.io/github/license/usestapel/stapel-shop)](https://github.com/usestapel/stapel-shop/blob/main/LICENSE)
[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-shop/blob/main/docs/llms.txt)

> Composite preset for a catalog shop (categories + typed attributes + listings + reviews): wires stapel-categories, stapel-listings and stapel-reviews into one INSTALLED_APPS/urls/config bundle, defaults reviews' TARGET_TYPES to the catalog's listings, and owns the one piece of real cross-domain glue a composite is allowed to know both sides of: ListingReviewSummaryProjection (reviews -> listings per-listing rating aggregate, local live_query in the monolith or event-carried state transfer when reviews is split into its own service).

Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.

## Install

```bash
pip install stapel-shop
```

## At a glance

| Fact | Value |
|---|---|
| Version | `0.2.3` |
| Python | `>=3.11` (3.11, 3.12, 3.13, 3.14) |
| Fleet dependencies | [`stapel-attributes`](https://github.com/usestapel/stapel-attributes) · [`stapel-categories`](https://github.com/usestapel/stapel-categories) · [`stapel-listings`](https://github.com/usestapel/stapel-listings) · [`stapel-reviews`](https://github.com/usestapel/stapel-reviews) |

## Documentation

[capabilities.json](https://github.com/usestapel/stapel-shop/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-shop/blob/main/docs/llms.txt)

> Likes/favourites are NOT included yet: `stapel-engagement` does not
> exist. They arrive as a MINOR bump of this composite once it does.

## Assemble (one line)

```bash
pip install stapel-tools
stapel-assemble myshop --libs shop
cd myshop && make test
```

That expands `shop` through the STAPEL_LIBS `requires`
closure and wires every member module into INSTALLED_APPS,
requirements.txt, urls.py and CONFIG.MD, then runs the verify gates.

## Manual wiring (no scaffold)

```python
# settings.py
from stapel_shop import preset

INSTALLED_APPS = [
    # ... django/stapel-core baseline (incl. stapel_core.django.projections)
    "stapel_categories",
    "stapel_listings",
    "stapel_reviews",
    "stapel_shop",
]
for _k, _v in preset.SETTINGS_DEFAULTS.items():
    globals().setdefault(_k, _v)

# urls.py
from django.urls import include, path

urlpatterns = [
    path("categories/", include("stapel_categories.urls")),
    path("listings/", include("stapel_listings.urls")),
    path("reviews/", include("stapel_reviews.urls")),
]
```

## Config checklist (fill these, in the generated project's CONFIG.MD too)

| Key | Note |
|-----|------|
| `STAPEL_REVIEWS["TARGET_TYPES"]` | prefilled by `stapel_shop.preset.SETTINGS_DEFAULTS` (targets `listing`); add `can_review`/`can_moderate` Functions to restrict |
| `STAPEL_LISTINGS["BASE_CURRENCY"]` | default `USD` — set your currency |
| `STAPEL_LISTINGS["DEFAULT_LISTING_TTL_DAYS"]` | default 30 |
| `STAPEL_REVIEWS["RATING_MIN"/"RATING_MAX"]` | defaults 1..5 |

## Glue (what this package actually contains)

- `stapel_shop.projections.ListingReviewSummaryProjection` — reviews→listings
  rating aggregate. Local mode (monolith): live reads through
  `reviews.aggregates_by_keys`. Remote mode: `ListingReviewSummary` table fed
  from `reviews.review.published/hidden` facts, rebuilt from
  `reviews.aggregates_export`.
- Read it ONLY through
  `stapel_core.comm.projections.read("shop.listing_review_summary", keys=[...])`
  — `{key: {"avg": float, "count": int}}`, the same shape in both modes; a key
  with no published review is absent from the answer.
- Requires stapel-reviews >= 0.2, the release that shipped both Functions this
  projection is declared against.

## License

MIT — see [LICENSE](https://github.com/usestapel/stapel-shop/blob/main/LICENSE).

---

<sub>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`.</sub>
