feat(amazon): Add system & user setting for Amazon region

Adds a setting to the system and user settings pages to allow users to
select their Amazon region. This setting does nothing in this PR, but
will be used in a PR further up the stack to select the correct Amazon
regional site when searching for books.

Author: jgoguen

cps/admin.py

@@ -9,7 +9,6 @@
 import re
 import json
 import operator
-import time
 import sys
 import string
 import requests
@@ -26,7 +25,7 @@
 from markupsafe import Markup
 from .cw_login import current_user
 from flask_babel import gettext as _
-from flask_babel import get_locale, format_time, format_datetime, format_timedelta
+from flask_babel import get_locale, format_time, format_timedelta
 from sqlalchemy import and_
 from sqlalchemy.orm.attributes import flag_modified
 from sqlalchemy.exc import IntegrityError, OperationalError, InvalidRequestError
@@ -39,6 +38,10 @@
     valid_email, check_username
 from .embed_helper import get_calibre_binarypath
 from .gdriveutils import is_gdrive_ready, gdrive_support
+from .metadata_provider_settings import (
+    apply_user_metadata_provider_regions,
+    get_metadata_provider_context,
+)
 from .render_template import render_title_template, get_sidebar_config
 from .services.worker import WorkerThread
 from .usermanagement import user_login_required
@@ -1688,6 +1691,7 @@ def new_user():
                                  config=config, translations=translations,
                                  languages=languages, title=_("Add New User"), page="newuser",
                                  kobo_support=kobo_support, registered_oauth=oauth_bb.oauth_check,
+                                 **get_metadata_provider_context(content),
                                  opds_root_order_string=opds_context["opds_root_order_string"],
                                  opds_hidden_entries_string=opds_context["opds_hidden_entries_string"],
                                  opds_root_labels=opds_context["opds_root_labels"],
@@ -1940,6 +1944,7 @@ def edit_user(user_id):
                                  hidden_custom_shelf_ids=hidden_custom_shelf_ids,
                                  hidden_custom_shelves=hidden_custom_shelves,
                                  visible_public_shelves=visible_public_shelves,
+                                 **get_metadata_provider_context(content),
                                  opds_root_order_string=opds_context["opds_root_order_string"],
                                  opds_hidden_entries_string=opds_context["opds_hidden_entries_string"],
                                  opds_root_labels=opds_context["opds_root_labels"],
@@ -2530,6 +2535,7 @@ def _handle_new_user(to_save, content, languages, translations, kobo_support):
                                      translations=translations,
                                      languages=languages, title=_("Add new user"), page="newuser",
                                      kobo_support=kobo_support, registered_oauth=oauth_bb.oauth_check,
+                                     **get_metadata_provider_context(content),
                                      opds_root_order_string=opds_context["opds_root_order_string"],
                                      opds_hidden_entries_string=opds_context["opds_hidden_entries_string"],
                                      opds_root_labels=opds_context["opds_root_labels"],
@@ -2543,6 +2549,7 @@ def _handle_new_user(to_save, content, languages, translations, kobo_support):
         content.denied_column_value = config.config_denied_column_value
         # No default value for kobo sync shelf setting
         content.kobo_only_shelves_sync = to_save.get("kobo_only_shelves_sync", 0) == "on"
+        apply_user_metadata_provider_regions(content, to_save)
         ub.session.add(content)
         ub.session.commit()
         flash(_("User '%(user)s' created", user=content.name), category="success")
@@ -2635,6 +2642,7 @@ def _handle_edit_user(to_save, content, languages, translations, kobo_support):
     # Auto-send and metadata fetch settings
     content.auto_send_enabled = to_save.get("auto_send_enabled") == "on"
     content.auto_metadata_fetch = to_save.get("auto_metadata_fetch") == "on"
+    apply_user_metadata_provider_regions(content, to_save)
 
     # OPDS root order
     opds_order_raw = to_save.get("opds_root_order", "").strip()
@@ -2808,6 +2816,7 @@ def _handle_edit_user(to_save, content, languages, translations, kobo_support):
                                      content=content,
                                      config=config,
                                      registered_oauth=oauth_bb.oauth_check,
+                                     **get_metadata_provider_context(content),
                                      opds_root_order_string=opds_context["opds_root_order_string"],
                                      opds_hidden_entries_string=opds_context["opds_hidden_entries_string"],
                                      opds_root_labels=opds_context["opds_root_labels"],
@@ -3113,4 +3122,4 @@ def restore_calibre_db():
                 except Exception:
                     pass
         except Exception:
-            pass
+            pass

cps/config_sql.py

@@ -90,6 +90,9 @@ class _Settings(_Base):
     config_kobo_sync = Column(Boolean, default=False)
     config_kobo_sync_magic_shelves = Column(Boolean, default=False)
 
+    # Metadata provider settings
+    config_amazon_region = Column(String, default="")
+
     # Sync read progress to Hardcover - should this be renamed?
     config_hardcover_sync = Column(Boolean, default=False) 
     # Sync annotations to Hardcover
@@ -372,6 +375,8 @@ def load(self):
                 else:
                     setattr(self, k, v)
 
+        self.amazon_region = self.config_amazon_region or constants.AMAZON_REGIONS[0]
+
         # Enforce unified logging to stdout for Docker deployments
         if self.config_logfile not in (logger.LOG_TO_STDOUT, logger.LOG_TO_STDERR):
             self.config_logfile = logger.LOG_TO_STDOUT

cps/constants.py

@@ -232,3 +232,26 @@ def _read_text(path: str, default: str = "") -> str:
     "zh_Hans_CN": _("Chinese (Simplified, China)"),
     "zh_Hant_TW": _("Chinese (Traditional, Taiwan)"),
 }
+
+# NOTE: Keep "com" as the first entry, whichever region is first is the default region until one is chosen by the admin
+# or the user. All other regions should be kept in alphabetical order.
+AMAZON_REGIONS = [
+    "com",
+    "ae",
+    "ca",
+    "co.jp",
+    "co.uk",
+    "com.au",
+    "com.br",
+    "com.mx",
+    "de",
+    "es",
+    "fr",
+    "ie",
+    "in",
+    "it",
+    "nl",
+    "sa",
+    "se",
+    "sg",
+]

cps/cwa_functions.py

@@ -39,6 +39,10 @@
 from .tasks.database import TaskReconnectDatabase
 from .tasks.auto_send import TaskAutoSend
 from .tasks.ops import TaskConvertLibraryRun, TaskEpubFixerRun
+from .metadata_provider_settings import (
+    apply_config_metadata_provider_regions,
+    get_metadata_provider_context,
+)
 
 switch_theme = Blueprint('switch_theme', __name__)
 library_refresh = Blueprint('library_refresh', __name__)
@@ -968,6 +972,7 @@ def set_cwa_settings():
 
             # Save Kobo Sync Magic Shelves setting (stored in app.db, not cwa.db)
             config.config_kobo_sync_magic_shelves = 'config_kobo_sync_magic_shelves' in request.form
+            apply_config_metadata_provider_regions(config, request.form)
             config.save()
 
             duplicate_criteria_changed = False
@@ -1053,10 +1058,13 @@ def set_cwa_settings():
     next_scan_run = get_next_duplicate_scan_run(cwa_settings)
 
     return render_title_template("cwa_settings.html", title=_("Calibre-Web Automated User Settings"), page="cwa-settings",
-                                    cwa_settings=cwa_settings, ignorable_formats=ignorable_formats, target_formats=target_formats,
-                                    automerge_options=automerge_options, autoingest_options=autoingest_options,
-                                    hardcover_token_available=hardcover_token_available,
-                                    next_duplicate_scan_run=next_scan_run, config=config)
+                                     cwa_settings=cwa_settings, ignorable_formats=ignorable_formats, target_formats=target_formats,
+                                     automerge_options=automerge_options, autoingest_options=autoingest_options,
+                                     hardcover_token_available=hardcover_token_available,
+                                     next_duplicate_scan_run=next_scan_run, config=config,
+                                     **get_metadata_provider_context(
+                                         amazon_region=getattr(config, "config_amazon_region", ""),
+                                     ))
 
 
 def get_next_duplicate_scan_run(settings):

cps/metadata_provider_settings.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+# Calibre-Web Automated – fork of Calibre-Web
+# Copyright (C) 2026 Calibre-Web Automated contributors
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Helpers for metadata provider region settings."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from . import constants
+
+
+def validate_provider_region(value: Any, allowed_regions: Sequence[str]) -> str:
+    """Return a normalized region value or an empty string when invalid."""
+    if value is None:
+        return ""
+
+    region = str(value).strip().lower()
+    return region if region in allowed_regions else ""
+
+
+def validate_amazon_region(value: Any) -> str:
+    """Return a validated Amazon region."""
+    return validate_provider_region(value, constants.AMAZON_REGIONS)
+
+
+def get_effective_amazon_region(
+    user: Any | None = None,
+    *,
+    config_amazon_region: Any | None = None,
+) -> str:
+    """Return the effective Amazon region using user, config, then default fallback."""
+    user_region = validate_amazon_region(getattr(user, "amazon_region", None)) if user is not None else ""
+    if user_region:
+        return user_region
+
+    config_region = validate_amazon_region(config_amazon_region)
+    if config_region:
+        return config_region
+
+    return constants.AMAZON_REGIONS[0]
+
+
+def apply_config_metadata_provider_regions(config_obj: Any, form_data: dict[str, Any]) -> None:
+    """Apply validated metadata provider regions to a config-like object."""
+    config_obj.config_amazon_region = validate_amazon_region(form_data.get("amazon_region"))
+
+
+def apply_user_metadata_provider_regions(user: Any, form_data: dict[str, Any]) -> None:
+    """Apply validated metadata provider regions to a user-like object."""
+    user.amazon_region = validate_amazon_region(form_data.get("amazon_region"))
+
+
+def get_metadata_provider_context(
+    user: Any | None = None,
+    *,
+    amazon_region: str | None = None,
+) -> dict[str, Any]:
+    """Return shared template context for metadata provider region settings."""
+    return {
+        "amazon_regions": constants.AMAZON_REGIONS,
+        "amazon_region": amazon_region
+        if amazon_region is not None
+        else getattr(user, "amazon_region", "")
+        if user is not None
+        else "",
+    }

cps/templates/cwa_settings.html

@@ -734,6 +734,19 @@ <h4 class="settings-section-header">🔖 {{_('Hardcover Auto-Fetch Settings')}}<
       </div>
     </div>
 
+    <div class="settings-container">
+      <div class="form-group">
+        <h4 class="settings-section-header">{{_('Metadata Provider Settings')}}</h4>
+        <label for="amazon_region" style="padding-right: 10px; margin-bottom: 16px !important;">{{_('Choose an Amazon region')}}:</label>
+        <select class="cwa-settings-select" name="amazon_region" id="amazon_region">
+          <option value="">({{ _('Default') }})</option>
+          {% for region in amazon_regions -%}
+          <option value="{{ region }}"{% if amazon_region == region %} selected{% endif %}>www.amazon.{{ region }}</option>
+          {% endfor %}
+        </select>
+      </div>
+    </div>
+
     <div class="settings-container">
         <h4 class="settings-section-header">{{_('Web UI Settings')}}</h4>
 

cps/templates/user_edit.html

@@ -292,6 +292,19 @@ <h4 class="settings-section-header">{{_('Book Language Filter')}}</h4>
     </div>
     {% endif %}
 
+    <div class="settings-container" style="max-width: none; margin-inline: 0rem;">
+      <div class="form-group" style="margin-bottom: 20px; display: flex; flex-direction: column; gap: 0.5rem;">
+        <h4 class="settings-section-header">{{_('Metadata Provider Settings')}}</h4>
+        <label for="amazon_region" style="margin-bottom: 8px !important;">{{_('Choose an Amazon region')}}:</label>
+        <select class="form-control" name="amazon_region" id="amazon_region">
+          <option value="">({{ _('Global Default') }})</option>
+          {% for region in amazon_regions -%}
+          <option value="{{ region }}"{% if amazon_region == region %} selected{% endif %}>www.amazon.{{ region }}</option>
+          {% endfor %}
+        </select>
+      </div>
+    </div>
+
     <!-- OAuth & API Integrations Card -->
     {% if (registered_oauth.keys()| length > 0 and not new_user and profile) or (hardcover_support and not new_user) or (kobo_support and not new_user) %}
     <div class="settings-container" style="max-width: none; margin-inline: 0rem;">

cps/ub.py

@@ -287,6 +287,7 @@ class User(UserBase, Base):
     auto_send_enabled = Column(Boolean, default=False)
     # Allow entering additional email addresses on send-to-eReader
     allow_additional_ereader_emails = Column(Boolean, default=True)
+    amazon_region = Column(String, default=None)
 
 
 if oauth_support:
@@ -335,6 +336,7 @@ def __init__(self):
         self.role = None
         self.name = None
         self.auto_send_enabled = False
+        self.amazon_region = None
         self.loadSettings()
 
     def loadSettings(self):
@@ -356,6 +358,7 @@ def loadSettings(self):
         self.kobo_only_shelves_sync = data.kobo_only_shelves_sync
         self.hardcover_token = data.hardcover_token
         self.auto_send_enabled = data.auto_send_enabled
+        self.amazon_region = data.amazon_region
     def role_admin(self):
         return False
 
@@ -926,6 +929,16 @@ def migrate_user_table(engine, _session):
         print(f"[Migration] Warning: Could not update duplicates sidebar setting: {e}")
         _session.rollback()
 
+    # Migration to add Amazon region setting
+    try:
+        _session.query(exists().where(User.amazon_region)).scalar()
+        _session.commit()
+    except exc.OperationalError:
+        with engine.connect() as conn:
+            trans = conn.begin()
+            conn.execute(text("ALTER TABLE user ADD column 'amazon_region' String DEFAULT ''"))
+            trans.commit()
+
 def migrate_oauth_provider_table(engine, _session):
     try:
         _session.query(exists().where(OAuthProvider.oauth_base_url)).scalar()
@@ -1017,6 +1030,21 @@ def migrate_config_table(engine, _session):
             # Don't raise - let CWA continue without this feature
             pass
 
+    # Add Amazon region configuration
+    try:
+        _session.execute(text("SELECT config_amazon_region FROM settings LIMIT 1"))
+        _session.commit()
+    except exc.OperationalError:
+        try:
+            _safe_session_rollback(_session, "settings.config_amazon_region")
+            _run_ddl_with_retry(
+                engine,
+                "ALTER TABLE settings ADD column 'config_amazon_region' String DEFAULT ''",
+            )
+        except Exception as e:
+            log.error("Failed to add config_amazon_region column: %s", e)
+            pass
+
 
 def migrate_magic_shelf_table(engine, _session):
     """Migrate magic_shelf table to add new columns."""

cps/web.py

@@ -8,7 +8,6 @@
 import json
 import mimetypes
 import chardet  # dependency of requests
-import copy
 import importlib
 import re
 import zipfile
@@ -43,6 +42,10 @@
 from .cw_babel import get_available_locale
 from .usermanagement import login_required_if_no_ano
 from .kobo_sync_status import remove_synced_book
+from .metadata_provider_settings import (
+    apply_user_metadata_provider_regions,
+    get_metadata_provider_context,
+)
 from . import magic_shelf
 from .render_template import render_title_template
 from .kobo_sync_status import change_archived_books
@@ -55,7 +58,6 @@
 # CWA Imports
 import sqlite3
 import time
-import time
 
 import sys
 sys.path.insert(1, '/app/calibre-web-automated/scripts/')
@@ -2432,6 +2434,8 @@ def change_profile(kobo_support, hardcover_support, local_oauth_check, oauth_sta
         current_user.auto_send_enabled = to_save.get("auto_send_enabled") == "on"
         current_user.auto_metadata_fetch = to_save.get("auto_metadata_fetch") == "on"
         current_user.allow_additional_ereader_emails = to_save.get("allow_additional_ereader_emails") == "on"
+
+        apply_user_metadata_provider_regions(current_user, to_save)
 
         # Handle hidden magic shelf templates and custom shelves
         from . import magic_shelf
@@ -2648,6 +2652,7 @@ def change_profile(kobo_support, hardcover_support, local_oauth_check, oauth_sta
                                      kobo_support=kobo_support,
                                      hardcover_support=hardcover_support,
                                      registered_oauth=local_oauth_check,
+                                     **get_metadata_provider_context(current_user),
                                      oauth_status=oauth_status)
 
     val = 0
@@ -2774,6 +2779,7 @@ def profile():
                                  title=_(f"{current_user.name.capitalize()}'s Profile", name=current_user.name),
                                  page="me",
                                  registered_oauth=local_oauth_check,
+                                 **get_metadata_provider_context(current_user),
                                  oauth_status=oauth_status)