Metadata-Version: 2.4
Name: catalogue-client
Version: 0.1.0
Summary: Django client for showing products from a catalogue-server site
Author: Vasudeva Server
License-Expression: MIT
Project-URL: Homepage, https://vasudevaserver.org
Project-URL: Source, https://gitlab.com/vasudeva-server/catalogue-client
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6.0,>=5.2
Requires-Dist: requests>=2.31
Dynamic: license-file

# catalogue-client

`catalogue-client` lets a Django site show products from another site that runs
[catalogue-server](https://gitlab.com/vasudeva-server/catalogue-server): titles,
descriptions, images, and the buying options for the visitor's country. It
stores nothing locally. Every product is a Python value object built from the
server's read-only JSON API and cached.

## Setup

```python
INSTALLED_APPS += ["catalogue_client.apps.CatalogueClientConfig"]

CATALOGUE_SERVER_URL = "https://catalogue.example.org"
```

Optionally mount the list page:

```python
path("products/", include("catalogue_client.urls")),
```

## Reading products

```python
from catalogue_client.utils import products_for_request, product_for_request

products = products_for_request(request, kinds=["book"], attributes={"language": "en"})
product = product_for_request(request, "trail-pack")
```

Filters: `slugs`, `kinds`, `groups`, `q`, and `attributes` (attribute name to one
value or a list of values). Calls made for a request pass the visitor's country
(`?country=`, Cloudflare's `CF-IPCountry`, then the site's country), because
without one the server would locate the web server instead of the visitor.
`products_for_site(site)` does the same outside a request, for example in a
management command.

A `Product` has the server's generic fields (`slug`, `title`, `subtitle`,
`kind`, `identifier`, `group`, `short_description`, `description_html`,
`image_url`, `images`, `url`, `external_url`, `related_products`) and a
`purchase` (`PurchaseInfo`: price, offers, store links, note, distributors).

## Fields the server site added

A catalogue-server site keeps its own fields in each product's `attributes`
(a books site stores the author, language, publisher and so on there), and can
add computed keys to the API with its `CATALOGUE_API_PRODUCT_DATA` setting. Both
reach the client unchanged: `product.attributes` and `product.attr("author")`
for the first, `product.extra` for the second.

To give them names, subclass `Product` in your own app and point
`CATALOGUE_CLIENT_PRODUCT_CLASS` at it. Every product the client returns is then
built as your class:

```python
# my_site/catalogue.py
from catalogue_client.models import Product


class Book(Product):
    @property
    def author(self):
        return self.attr("author")

    @property
    def choice_label(self):  # how CatalogueProductChoiceField lists it
        return f"{self.title} ({self.attr('language').upper()})"
```

```python
CATALOGUE_CLIENT_PRODUCT_CLASS = "my_site.catalogue.Book"
```

Filters that always apply to a site, such as showing a Czech site only Czech
editions, come from `CATALOGUE_CLIENT_SITE_FILTERS`, a function
`(site) -> dict` of the filters above.

## Settings

| Setting | Default | |
|---|---|---|
| `CATALOGUE_SERVER_URL` | (required) | catalogue-server origin, no path |
| `CATALOGUE_CLIENT_API_PATH` | `/api/v1/` | |
| `CATALOGUE_CLIENT_TIMEOUT` | `10` | seconds |
| `CATALOGUE_CLIENT_CACHE_SECONDS` | `3600` | |
| `CATALOGUE_CLIENT_DEFAULT_COUNTRY` | `""` | when neither the request nor the site gives one |
| `CATALOGUE_CLIENT_TEMPLATE` | `catalogue_client/product_list.html` | template of the list page (context: `products`, `selected_product`, `catalogue_error`) |
| `CATALOGUE_CLIENT_PRODUCT_CLASS` | `""` | dotted path to your `Product` subclass |
| `CATALOGUE_CLIENT_SITE_FILTERS` | `""` | dotted path to `(site) -> dict` of filters |

The site's country is read from `site.domain_settings.country` when the site
uses [servicetrees](https://gitlab.com/vasudeva-server/servicetrees); otherwise
set `CATALOGUE_CLIENT_DEFAULT_COUNTRY`.

## Status

Unmaintained and provided as-is. There is no commitment to updates, security fixes, or support.

Pull requests are welcome and may be looked at. There is no commitment to review or merge them. Contributions are licensed under the same license as this project.

Issues are not tracked. Please do not open bug reports or feature requests.

This repository is [MIT licensed](LICENSE).

[Vasudeva Server](https://vasudevaserver.org)
