Config

app.config

Use-case configuration. Adapt a deployment by editing this file (and env overrides).

Config

Bases: BaseSettings

Use-case knobs: API metadata, languages, and the stories provider.

stories_base_urls property

Map language code to public stories index URL.

supported_langs property

Language codes accepted by the lang query parameter.

create_stories_base_url(lang)

Return the stories index for lang, falling back to English.

Parameters:

Name	Type	Description	Default
lang	str	Requested language code.	required

Returns:

Type	Description
str	Public index URL.

Source code in src/backend/app/config.py

def create_stories_base_url(self, lang: str) -> str:
    """Return the stories index for *lang*, falling back to English.

    Args:
        lang: Requested language code.

    Returns:
        Public index URL.
    """
    return self.stories_base_urls.get(lang, self.stories_base_url_en)

entity_stories_url(entity_tag_id, lang)

Build a public stories index URL filtered to one entity's term id.

Parameters:

Name	Type	Description	Default
entity_tag_id	str	Upstream term id (wpEntityTagId).	required
lang	str	UI language.	required

Returns:

Type	Description
str	URL with a tag query parameter.

Source code in src/backend/app/config.py

def entity_stories_url(self, entity_tag_id: str, lang: str) -> str:
    """Build a public stories index URL filtered to one entity's term id.

    Args:
        entity_tag_id: Upstream term id (``wpEntityTagId``).
        lang: UI language.

    Returns:
        URL with a ``tag`` query parameter.
    """
    return f"{self.create_stories_base_url(lang)}?tag={entity_tag_id}"

create_stories_frontend_url(ids, lang)

Build a public stories index URL filtered to ids.

Default shape: ?tag=<id1,id2,...>. Override for a different scheme.

Parameters:

Name	Type	Description	Default
ids	list[int]	Upstream term ids.	required
lang	str	UI language.	required

Returns:

Type	Description
str	Public URL for user navigation.

Source code in src/backend/app/config.py

def create_stories_frontend_url(self, ids: list[int], lang: str) -> str:
    """Build a public stories index URL filtered to *ids*.

    Default shape: ``?tag=<id1,id2,...>``. Override for a different scheme.

    Args:
        ids: Upstream term ids.
        lang: UI language.

    Returns:
        Public URL for user navigation.
    """
    base = self.create_stories_base_url(lang)
    if not ids:
        return base
    tags_param = ",".join(str(i) for i in ids)
    return f"{base}?tag={tags_param}"

create_stories_api_url(ids, lang)

Build the upstream stories API URL that returns a count for ids.

Default query shape matches the OceanCare WordPress REST API. Override for a different API.

Parameters:

Name	Type	Description	Default
ids	list[int]	Upstream term ids.	required
lang	str	UI language.	required

Returns:

Type	Description
str	Upstream request URL.

Source code in src/backend/app/config.py

def create_stories_api_url(self, ids: list[int], lang: str) -> str:
    """Build the upstream stories API URL that returns a count for *ids*.

    Default query shape matches the OceanCare WordPress REST API.
    Override for a different API.

    Args:
        ids: Upstream term ids.
        lang: UI language.

    Returns:
        Upstream request URL.
    """
    if len(ids) == 1:
        return f"{self.stories_api_url}?tags={ids[0]}&lang={lang}&per_page=1&_fields=id"
    terms = ",".join(str(i) for i in ids)
    return (
        f"{self.stories_api_url}?tags[terms]={terms}"
        f"&tags[operator]=AND&lang={lang}&per_page=1&_fields=id"
    )

parse_stories_count(response)

Extract the story count from an upstream HTTP response.

Default: read the configured count header (WordPress X-WP-Total). Override for a different response shape.

Parameters:

Name	Type	Description	Default
response	Response	Successful upstream response.	required

Returns:

Type	Description
int	Integer story count (0 when the header is missing).

Source code in src/backend/app/config.py

def parse_stories_count(self, response: httpx.Response) -> int:
    """Extract the story count from an upstream HTTP response.

    Default: read the configured count header (WordPress ``X-WP-Total``).
    Override for a different response shape.

    Args:
        response: Successful upstream response.

    Returns:
        Integer story count (0 when the header is missing).
    """
    return int(response.headers.get(self.stories_count_header, 0))