[mod] brand - partial migration of settings to msgspec.Struct (#5280)

The settings are currently an untyped key/value structure, whose types are
dynamically built at runtime.  The construction process of this structure
is *hand-crafted*.

In the long term, we want a static typing of this structure, based on a standard
tool.  The ``msgspec.Struct`` structures are suitable as a standard tool.

This patch makes a first step towards static typing and implements the "brand"
section using ``msgspec.Struct`` structures.

BTW: searx/settings_defaults.py - ``git_url`` and ``git_branch`` had been
removed in aee613d256, this is a leftover.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

1 files changed, 68 insertions, 0 deletions

diff --git a/searx/brand.py b/searx/brand.py
new file mode 100644
index 000000000..9627da07d
--- /dev/null
+++ b/searx/brand.py
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Implementations needed for a branding of SearXNG."""
+# pylint: disable=too-few-public-methods
+
+# Struct fields aren't discovered in Python 3.14
+# - https://github.com/searxng/searxng/issues/5284
+from __future__ import annotations
+
+__all__ = ["SettingsBrand"]
+
+import msgspec
+
+
+class BrandCustom(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
+    """Custom settings in the brand section."""
+
+    links: dict[str, str] = {}
+    """Custom entries in the footer of the WEB page: ``[title]: [link]``"""
+
+
+class SettingsBrand(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
+    """Options for configuring brand properties.
+
+    .. code:: yaml
+
+       brand:
+         issue_url: https://github.com/searxng/searxng/issues
+         docs_url: https://docs.searxng.org
+         public_instances: https://searx.space
+         wiki_url: https://github.com/searxng/searxng/wiki
+
+         custom:
+           links:
+             Uptime: https://uptime.searxng.org/history/example-org
+             About: https://example.org/user/about.html
+    """
+
+    issue_url: str = "https://github.com/searxng/searxng/issues"
+    """If you host your own issue tracker change this URL."""
+
+    docs_url: str = "https://docs.searxng.org"
+    """If you host your own documentation change this URL."""
+
+    public_instances: str = "https://searx.space"
+    """If you host your own https://searx.space change this URL."""
+
+    wiki_url: str = "https://github.com/searxng/searxng/wiki"
+    """Link to your wiki (or ``false``)"""
+
+    custom: BrandCustom = msgspec.field(default_factory=BrandCustom)
+    """Optional customizing.
+
+    .. autoclass:: searx.brand.BrandCustom
+       :members:
+    """
+
+    # new_issue_url is a hackish solution tailored for only one hoster (GH).  As
+    # long as we don't have a more general solution, we should support it in the
+    # given function, but it should not be expanded further.
+
+    new_issue_url: str = "https://github.com/searxng/searxng/issues/new"
+    """If you host your own issue tracker not on GitHub, then unset this URL.
+
+    Note: This URL will create a pre-filled GitHub bug report form for an
+    engine.  Since this feature is implemented only for GH (and limited to
+    engines), it will probably be replaced by another solution in the near
+    future.
+    """