Skip to content

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 → public stories index URL.

Returns:

Type Description
dict[str, str]

Dict keyed by language code.

supported_langs property

Language codes accepted by the lang query parameter.

Returns:

Type Description
list[str]

Keys of stories_base_urls.

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 
80
81
82
83
84
85
86
87
88
89
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 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
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 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
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 
142
143
144
145
146
147
148
149
150
151
152
153
154
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))

create_stories_base_url(lang)

Delegate to config.create_stories_base_url.

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 
170
171
172
173
174
175
176
177
178
179
def create_stories_base_url(lang: str) -> str:
    """Delegate to ``config.create_stories_base_url``.

    Args:
        lang: Requested language code.

    Returns:
        Public index URL.
    """
    return config.create_stories_base_url(lang)

entity_stories_url(entity_tag_id, lang)

Delegate to config.entity_stories_url.

Parameters:

Name Type Description Default
entity_tag_id str

Upstream term id.

 required
lang str

UI language.

 required

Returns:

Type Description
str

Public URL filtered to one entity.
Source code in src/backend/app/config.py 
182
183
184
185
186
187
188
189
190
191
192
def entity_stories_url(entity_tag_id: str, lang: str) -> str:
    """Delegate to ``config.entity_stories_url``.

    Args:
        entity_tag_id: Upstream term id.
        lang: UI language.

    Returns:
        Public URL filtered to one entity.
    """
    return config.entity_stories_url(entity_tag_id, lang)

create_stories_frontend_url(ids, lang)

Delegate to config.create_stories_frontend_url.

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 
195
196
197
198
199
200
201
202
203
204
205
def create_stories_frontend_url(ids: list[int], lang: str) -> str:
    """Delegate to ``config.create_stories_frontend_url``.

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

    Returns:
        Public URL for user navigation.
    """
    return config.create_stories_frontend_url(ids, lang)

create_stories_api_url(ids, lang)

Delegate to config.create_stories_api_url.

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 
208
209
210
211
212
213
214
215
216
217
218
def create_stories_api_url(ids: list[int], lang: str) -> str:
    """Delegate to ``config.create_stories_api_url``.

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

    Returns:
        Upstream request URL.
    """
    return config.create_stories_api_url(ids, lang)

parse_stories_count(response)

Delegate to config.parse_stories_count.

Parameters:

Name Type Description Default
response Response

Successful upstream response.

 required

Returns:

Type Description
int

Integer story count.
Source code in src/backend/app/config.py 
221
222
223
224
225
226
227
228
229
230
def parse_stories_count(response: httpx.Response) -> int:
    """Delegate to ``config.parse_stories_count``.

    Args:
        response: Successful upstream response.

    Returns:
        Integer story count.
    """
    return config.parse_stories_count(response)