catalogue-server

catalogue-server is a reusable Django product catalogue with public pages, a read-only JSON API, country-aware availability, and optional synchronization from online shops.

It deliberately models products rather than a particular industry. A Product has common catalogue fields plus an attributes JSON object for host-specific metadata. Related variants can share a ProductGroup; prices and availability can vary by country; and an Offer records a shop selling a product.

Install and start

pip install catalogue-server
# Optional integrations:
pip install "catalogue-server[geoip,shops]"

Add the app and URLs:

INSTALLED_APPS += ["catalogue_server.apps.CatalogueServerConfig"]

urlpatterns = [
    path("api/v1/", include("catalogue_server.api_urls")),
    path("products/", include("catalogue_server.urls")),
]

Then initialize the database:

python manage.py migrate
python manage.py runserver

Products and distributors can be maintained in Django admin or through a host project's own editor. The HTML catalogue is now at /products/; the API is at /api/v1/. See API.md for its complete contract.

Data model

• ProductGroup: optional grouping for variants of one product.
• Product: title, type (kind), identifier, descriptions, image, arbitrary JSON attributes, default price, and publication state.
• ProductImage: additional images.
• ProductCountryInfo: country-specific price, text, and availability date.
• Distributor: a retailer or trade distributor and the countries it serves.
• Offer: a manual or scanned shop listing, including price and stock.

The package does not prescribe the meaning of kind, identifier, or attributes. For example, one host might use kind="clothing", a SKU, and size/material attributes, while another chooses an entirely different schema. Keep that interpretation, validation, and presentation in the host project.

Settings

• GEOIP_COUNTRY_DB: optional GeoLite2 Country database path.
• CATALOGUE_DEFAULT_COUNTRY: fallback ISO country code.
• CATALOGUE_API_CACHE_SECONDS: API cache lifetime; default 3600.
• CATALOGUE_SHOP_USER_AGENT: user agent used during shop scans.
• CATALOGUE_SHOP_PARSERS: additional parser registry entries.
• CATALOGUE_PRODUCT_MATCHER: dotted path to a custom matcher class.
• CATALOGUE_API_PRODUCT_DATA: dotted path to (product, request) -> dict whose keys are added to each product in the API, for data a site computes rather than stores in attributes.
• CATALOGUE_PRODUCT_LIST_FILTER: dotted path to (request, products) -> (products, context) that narrows the product list (e.g. by a language attribute); a list_filters_template in the context is shown beside the country picker.
• CATALOGUE_NAME: name used in page titles when the site has none.
• CATALOGUE_PRODUCTS_NOUN: what the products are called in counts and short text; default products (e.g. books).
• CATALOGUE_PRODUCTS_TITLE: product list heading; default the noun capitalised (e.g. Books by Jane Doe).
• CATALOGUE_PRODUCTS_PHRASE: used in "Where to buy …" and ": … in " page titles; default the noun (e.g. Jane Doe's books).

The default matcher conservatively uses an exact identifier, then a unique exact title. A custom matcher receives the product queryset, implements match(shop_product), and may implement keep_unmatched(shop_product). This is the extension point for domain-specific matching rules.

Shop synchronization

Install the shops extra and configure a distributor's shop_parser and shop_options. The built-in parsers support:

Run scans periodically:

python manage.py scan_shops

A parser is a callable receiving (options, session) and yielding ShopProduct instances. Register host-specific parsers with CATALOGUE_SHOP_PARSERS; wrappers may reuse a built-in platform parser and add host-owned attributes. Scans preserve an editor's manual product assignment.

Optional integrations and overrides

The package uses servicetrees' DisplayPage for an optional richer product page; without one, catalogue-server generates its own detail page. Standard Django template and static-file override rules let a host supply its own design.

Image fields use ordinary Django storage. If servicetrees media storage is configured, those files also appear in its media library.

For local package development:

pip install -e ./path/to/catalogue_server
python manage.py test catalogue_server

Vasudeva Server