ub-project 1.0.0__tar.gz

ub_project-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 useblocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ub_project-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: ub-project
+Version: 1.0.0
+Summary: The shared reader for ubproject.toml and its variant data, for the sphinx-needs family and ubCode
+Keywords: ubproject.toml,sphinx-needs,ubcode,configuration,variants
+Author-email: team useblocks <info@useblocks.com>
+Requires-Python: >=3.11,<4
+Description-Content-Type: text/x-rst
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+License-File: LICENSE
+Project-URL: Changelog, https://github.com/useblocks/sphinx-needs/blob/master/packages/ub-project/docs/changelog.rst
+Project-URL: Issues, https://github.com/useblocks/sphinx-needs/issues
+Project-URL: Repository, https://github.com/useblocks/sphinx-needs
+Import-Name: ub_project
+
+ub-project
+==========
+
+A library for the sphinx-needs family, which the extensions pull in -- not a Sphinx
+extension, and nothing to add to ``conf.py``.
+
+It is the shared reader for ``ubproject.toml``, the declarative file that describes a
+project to every useblocks tool: the sphinx-needs family of Sphinx extensions
+(sphinx-needs, sphinx-mounts, sphinx-codelinks, sphinx-test-reports), their command lines,
+and ubCode.
+
+It holds the parts of that file more than one tool reads, so that they are read one way:
+
+- **finding, loading and anchoring** the file -- the walk up to the repository root (or,
+  outside a repository, the distribution root), TOML read with every failure named, a dotted table selected, and relative paths anchored at
+  the file's own directory;
+- **the** ``[variants]`` **table**, with the legacy ``[needs] variant_data*`` keys as its
+  fallback;
+- **the variant-data merge** -- validate, load from JSON, deep-merge, resolve -- in one copy.
+
+Standard library only: no Sphinx, no docutils, no sibling distribution. A converter or a
+build action that runs without the documentation toolchain can use it.
+
+The three calls
+---------------
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from ub_project import find_project_config, load_toml, read_variants
+
+   toml_path = find_project_config(Path.cwd())   # or the path your tool is configured with
+   if toml_path is not None:
+       result = read_variants(load_toml(toml_path), toml_path)
+       result.data          # the merged variant map
+       result.data_file     # the data file, anchored at the TOML's directory, or None
+       result.location      # "variants", "needs" or None
+       result.diagnostics   # findings to report -- or not
+
+Every hard failure is an ``ProjectConfigError`` whose message names the file and the rule that
+was broken.
+
+``[variants]``
+--------------
+
+.. code-block:: toml
+
+   [variants]
+   data_file = "variants.json"   # one path, anchored at this file's directory
+
+   [variants.data]               # deep-merged over the file; the inline table wins
+   edition = "pro"
+   build = { debug = false }
+
+If ``[variants]`` declares neither key, the reader falls back to ``[needs] variant_data``
+and ``[needs] variant_data_file``. If both locations are set, ``[variants]`` is read whole
+and every ignored ``[needs]`` key is reported.
+
+Consumers decide the policy
+---------------------------
+
+This package decides nothing a consumer has reason to decide differently. **Discovery**
+(walk up, or read the Sphinx ``confdir``), **warnings** (a diagnostic is returned, never
+logged: whether the legacy location deserves one is each tool's call), and **the command
+line** (``-D`` in Sphinx, ``-c`` in ubCode) are all the consumer's.
+
+The contract
+------------
+
+``design/reading-contract.md`` is the normative specification, and
+``tests/fixtures/ubproject_reading_conformance.toml`` is its executable half: a corpus of
+inputs and expected results that this package's suite runs, and that ubCode is to vendor
+and run against its own reader (its reader does not read ``[variants]`` yet).
+

ub_project-1.0.0/README.rst

@@ -0,0 +1,74 @@
+ub-project
+==========
+
+A library for the sphinx-needs family, which the extensions pull in -- not a Sphinx
+extension, and nothing to add to ``conf.py``.
+
+It is the shared reader for ``ubproject.toml``, the declarative file that describes a
+project to every useblocks tool: the sphinx-needs family of Sphinx extensions
+(sphinx-needs, sphinx-mounts, sphinx-codelinks, sphinx-test-reports), their command lines,
+and ubCode.
+
+It holds the parts of that file more than one tool reads, so that they are read one way:
+
+- **finding, loading and anchoring** the file -- the walk up to the repository root (or,
+  outside a repository, the distribution root), TOML read with every failure named, a dotted table selected, and relative paths anchored at
+  the file's own directory;
+- **the** ``[variants]`` **table**, with the legacy ``[needs] variant_data*`` keys as its
+  fallback;
+- **the variant-data merge** -- validate, load from JSON, deep-merge, resolve -- in one copy.
+
+Standard library only: no Sphinx, no docutils, no sibling distribution. A converter or a
+build action that runs without the documentation toolchain can use it.
+
+The three calls
+---------------
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from ub_project import find_project_config, load_toml, read_variants
+
+   toml_path = find_project_config(Path.cwd())   # or the path your tool is configured with
+   if toml_path is not None:
+       result = read_variants(load_toml(toml_path), toml_path)
+       result.data          # the merged variant map
+       result.data_file     # the data file, anchored at the TOML's directory, or None
+       result.location      # "variants", "needs" or None
+       result.diagnostics   # findings to report -- or not
+
+Every hard failure is an ``ProjectConfigError`` whose message names the file and the rule that
+was broken.
+
+``[variants]``
+--------------
+
+.. code-block:: toml
+
+   [variants]
+   data_file = "variants.json"   # one path, anchored at this file's directory
+
+   [variants.data]               # deep-merged over the file; the inline table wins
+   edition = "pro"
+   build = { debug = false }
+
+If ``[variants]`` declares neither key, the reader falls back to ``[needs] variant_data``
+and ``[needs] variant_data_file``. If both locations are set, ``[variants]`` is read whole
+and every ignored ``[needs]`` key is reported.
+
+Consumers decide the policy
+---------------------------
+
+This package decides nothing a consumer has reason to decide differently. **Discovery**
+(walk up, or read the Sphinx ``confdir``), **warnings** (a diagnostic is returned, never
+logged: whether the legacy location deserves one is each tool's call), and **the command
+line** (``-D`` in Sphinx, ``-c`` in ubCode) are all the consumer's.
+
+The contract
+------------
+
+``design/reading-contract.md`` is the normative specification, and
+``tests/fixtures/ubproject_reading_conformance.toml`` is its executable half: a corpus of
+inputs and expected results that this package's suite runs, and that ubCode is to vendor
+and run against its own reader (its reader does not read ``[variants]`` yet).

ub_project-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "ub-project"
+version = "1.0.0"
+description = "The shared reader for ubproject.toml and its variant data, for the sphinx-needs family and ubCode"
+authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
+license = { file = "LICENSE" }
+readme = "README.rst"
+requires-python = ">=3.11,<4"
+# EMPTY, and that is the package's whole contract with its consumers: `tomllib` and `json`
+# are the standard library, and a dependency here -- Sphinx above all -- would reach every
+# tool that reads the file, including the ones that run with no documentation toolchain.
+# `tests/test_imports.py` fences the import graph, and the `toolchain-free` CI job runs the
+# suite in an environment with no Sphinx in it
+dependencies = []
+keywords = [
+  "ubproject.toml",
+  "sphinx-needs",
+  "ubcode",
+  "configuration",
+  "variants",
+]
+# NOT `Framework :: Sphinx`: nothing here depends on Sphinx
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Documentation",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/useblocks/sphinx-needs"
+Issues = "https://github.com/useblocks/sphinx-needs/issues"
+Changelog = "https://github.com/useblocks/sphinx-needs/blob/master/packages/ub-project/docs/changelog.rst"
+
+[build-system]
+requires = ["flit_core >=3.4,<5"]
+build-backend = "flit_core.buildapi"
+
+# Deliberately NO `[tool.flit.sdist]`: flit's default sdist is the module, its `py.typed`
+# marker, README, LICENSE and this file, and nothing else (measured). Everything else -- ruff, ty, pytest and the dependency groups --
+# is the ROOT's, and `tools/src/sn_tools/check_workspace.py` refuses those tables here.

ub_project-1.0.0/src/ub_project/__init__.py

@@ -0,0 +1,60 @@
+"""The shared reader for ``ubproject.toml`` and its variant data.
+
+One implementation of the parts of ``ubproject.toml`` that more than one tool reads -- the
+sphinx-needs family of Sphinx extensions and their command lines, which will depend on it,
+and ubCode, which is to be held to the same behaviour through the conformance corpus in
+this package's tests. Standard library only: no Sphinx, no docutils, no sibling
+distribution.
+
+It decides no policy. Discovery (walk up or read the ``confdir``), whether a finding is
+worth a warning, and how ``-D`` / ``-c`` on a command line interact with the file are each
+consumer's to decide; this package returns what it found and raises
+:class:`ProjectConfigError` for what it cannot accept.
+"""
+
+from ub_project.project import (
+    DEFAULT_FILENAME,
+    ProjectConfigError,
+    anchor,
+    find_project_config,
+    load_toml,
+    select_table,
+    table_path,
+)
+from ub_project.variant_data import (
+    deep_merge,
+    load_variant_data_file,
+    resolve_variant_data,
+    validate_variant_data,
+)
+from ub_project.variants import (
+    VARIANT_DATA_LEGACY_LOCATION,
+    VARIANT_DATA_LOCATION,
+    VARIANTS_UNKNOWN_KEY,
+    Diagnostic,
+    VariantsResult,
+    read_variants,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "DEFAULT_FILENAME",
+    "VARIANTS_UNKNOWN_KEY",
+    "VARIANT_DATA_LEGACY_LOCATION",
+    "VARIANT_DATA_LOCATION",
+    "Diagnostic",
+    "ProjectConfigError",
+    "VariantsResult",
+    "__version__",
+    "anchor",
+    "deep_merge",
+    "find_project_config",
+    "load_toml",
+    "load_variant_data_file",
+    "read_variants",
+    "resolve_variant_data",
+    "select_table",
+    "table_path",
+    "validate_variant_data",
+]

ub_project-1.0.0/src/ub_project/project.py

@@ -0,0 +1,258 @@
+"""Find, load, select and anchor: the plumbing every reader of ``ubproject.toml`` repeats.
+
+**Nothing in this package may import Sphinx, docutils or any other distribution** -- only
+the standard library. The file describes a project to tools that run with no documentation
+toolchain installed (a converter, a build action, a CI step that only reads the file), and a
+shared reader that pulled Sphinx in would take that away from all of them at once.
+
+What this module deliberately does NOT decide is policy. Whether a consumer walks up to
+find the file or reads it from its ``confdir``, whether a missing file is worth a warning,
+whether a ``-D`` on the command line beats a key in the file: those are the consumer's
+decisions, and they differ today for reasons each consumer owns. This module provides the
+mechanisms, and reports through return values and :class:`ProjectConfigError` -- never through
+a logger.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+
+#: The file name every useblocks tool reads by default.
+DEFAULT_FILENAME = "ubproject.toml"
+
+#: Directory entries that end the upward search of :func:`find_project_config`. A
+#: directory carrying one is the repository root, and nothing above it belongs to the
+#: project, so a consumer never adopts the configuration of an unrelated parent.
+#: ``pyproject.toml`` is deliberately *not* a marker here: it marks a Python distribution,
+#: not the project. A ``docs/`` directory with its own ``pyproject.toml``, or a workspace
+#: member (``packages/<name>/pyproject.toml`` with the docs below it), sits *inside* the
+#: project whose shared file is at the repository root, and a marker there would end the
+#: search before it reached the file -- silently. It does bound the walk where there is no
+#: repository at all, see :data:`_DIST_MARKERS`.
+_ROOT_MARKERS = (".git",)
+
+#: Directory entries that end the search when *no* :data:`_ROOT_MARKERS` marker exists
+#: anywhere above the starting directory. A tree outside any repository -- an unpacked
+#: sdist, a CI artefact directory, an exported docs tree -- has nothing else to bound the
+#: walk, so it would reach the filesystem root and adopt whatever unrelated file sits
+#: above it. The distribution root is the outermost thing that still belongs to such a
+#: tree.
+_DIST_MARKERS = ("pyproject.toml",)
+
+#: A TOML bare key; any other key is written quoted (:func:`render_path`).
+_BARE_KEY = re.compile(r"[A-Za-z0-9_-]+")
+
+#: The TOML basic-string escapes with a short form; other control characters use ``\\uXXXX``.
+_TOML_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\t": "\\t",
+    "\n": "\\n",
+    "\f": "\\f",
+    "\r": "\\r",
+}
+
+#: ``tomllib.TOMLDecodeError`` bound through an annotation, so that the ``except`` clause
+#: below is typed as precisely as everything else in the module.
+_TOML_DECODE_ERROR: type[Exception] = tomllib.TOMLDecodeError
+
+
+class ProjectConfigError(Exception):
+    """The one exception this package raises, for every hard failure.
+
+    Each message names the file (or the dotted path inside it) and the rule that was
+    broken. A consumer re-raises it in its own vocabulary -- a Sphinx extension as a
+    configuration error, a command line as a non-zero exit -- which is why it derives from
+    nothing more specific than :class:`Exception`.
+    """
+
+
+def find_project_config(
+    start: Path,
+    filename: str = DEFAULT_FILENAME,
+    report: Callable[[str], None] | None = None,
+) -> Path | None:
+    """Search *start* and its parents for *filename*.
+
+    The file conventionally sits at the repository root while its consumers run from
+    below it -- ``conf.py`` in ``docs/``, a build action from wherever CI invoked it -- so
+    anchoring strictly at the caller's own directory would leave the shared file unread
+    by one of them, silently.
+
+    The walk ends at the first directory holding *filename*, or at the project boundary
+    when that does not hold the file either. The boundary is the repository root
+    (a directory holding ``.git``), or -- outside any repository only -- the distribution
+    root (a directory holding ``pyproject.toml``).
+
+    Whether to call this at all is the consumer's decision: providing the walk is not a
+    ruling that every consumer should walk.
+
+    :param start: Directory to start from. Made absolute -- without resolving symlinks --
+        so that a relative path has parents to walk.
+    :param filename: The file to look for.
+    :param report: Called with one message when the search ends without the file, naming
+        the directory whose marker ended it; ``None`` discards it. A missing file is not
+        necessarily a problem, but a fruitless search must be diagnosable.
+    :return: The file, or ``None`` when the search reached the project boundary or the
+        filesystem root without finding one.
+    """
+    start = start.absolute()
+    directories = (start, *start.parents)
+    boundary, described = _boundary(directories)
+    for directory in directories:
+        candidate = directory / filename
+        if candidate.is_file():
+            return candidate
+        if directory == boundary:
+            break
+    if report is not None:
+        report(f"no {filename} in {start} or its parents up to {described}")
+    return None
+
+
+def _boundary(directories: tuple[Path, ...]) -> tuple[Path | None, str]:
+    """The directory the upward search must not walk past, and its description.
+
+    A repository root anywhere above the start wins: inside a repository the only thing
+    that bounds the project is the repository itself. Only when there is none does the
+    distribution root bound the walk.
+    """
+    for markers, label in (
+        (_ROOT_MARKERS, "repository"),
+        (_DIST_MARKERS, "distribution"),
+    ):
+        for directory in directories:
+            marker = _marker(directory, markers)
+            if marker is not None:
+                return directory, f"the {label} root {directory} (holding {marker})"
+    return None, "the filesystem root"
+
+
+def _marker(directory: Path, markers: tuple[str, ...]) -> str | None:
+    """The entry of *markers* that *directory* holds, if any."""
+    for marker in markers:
+        if (directory / marker).exists():
+            return marker
+    return None
+
+
+def load_toml(path: Path) -> dict[str, object]:
+    """Parse *path*, reporting every failure as an :class:`ProjectConfigError` naming it.
+
+    A missing file is a failure here too: whether an absent file is fine is the
+    consumer's decision, taken before it calls this.
+
+    :raises ProjectConfigError: If the file cannot be read, is not UTF-8, or is not valid TOML.
+    """
+    try:
+        with path.open("rb") as handle:
+            # tomllib is typed ``-> dict[str, Any]``; everything downstream is ``object``
+            data: dict[str, object] = tomllib.load(handle)
+    except _TOML_DECODE_ERROR as error:
+        msg = f"{path}: invalid TOML: {error}"
+        raise ProjectConfigError(msg) from error
+    except UnicodeDecodeError as error:
+        # tomllib decodes the bytes itself, and a file saved in another encoding raises
+        # neither of the two errors around it
+        msg = f"{path}: not valid UTF-8 TOML: {error}"
+        raise ProjectConfigError(msg) from error
+    except OSError as error:
+        msg = f"{path}: cannot be read: {error}"
+        raise ProjectConfigError(msg) from error
+    return data
+
+
+def _basic_string(key: str) -> str:
+    """*key* as a TOML basic string: only ``"``, ``\\`` and control characters escaped.
+
+    Everything else is written as itself -- ``café`` is ``"café"``, not the ``\\u00e9``
+    that ``json.dumps`` would produce -- because that is how the user wrote the key.
+    """
+    out = []
+    for char in key:
+        if char in _TOML_ESCAPES:
+            out.append(_TOML_ESCAPES[char])
+        elif ord(char) < 0x20 or ord(char) == 0x7F:
+            out.append(f"\\u{ord(char):04X}")
+        else:
+            out.append(char)
+    return '"' + "".join(out) + '"'
+
+
+def render_path(segments: Sequence[str]) -> str:
+    """Spell a table path the way TOML does: dotted, a segment that is not a bare key quoted.
+
+    A segment matching ``[A-Za-z0-9_-]+`` is written bare; any other is a TOML basic string
+    (:func:`_basic_string`). ``("tool", "acme.docs", "needs")`` renders as
+    ``tool."acme.docs".needs`` -- joined naively it would read as four segments, and name
+    a table that does not exist.
+    """
+    return ".".join(
+        segment if _BARE_KEY.fullmatch(segment) else _basic_string(segment)
+        for segment in segments
+    )
+
+
+def table_path(table: str | Sequence[str]) -> tuple[str, ...]:
+    """The segments of a table path, given dotted (``"a.b.c"``) or as a sequence.
+
+    The sequence form exists for a key that itself contains a dot, which the dotted
+    spelling cannot express -- TOML allows ``[tool."acme.docs".needs]``.
+
+    :raises ValueError: If the path is empty or has an empty segment -- a caller's
+        mistake, not a problem with the file.
+    """
+    segments = tuple(table.split(".")) if isinstance(table, str) else tuple(table)
+    if not segments or any(not segment for segment in segments):
+        msg = f"invalid table path {table!r}: expected one or more non-empty segments"
+        raise ValueError(msg)
+    return segments
+
+
+def select_table(
+    data: Mapping[str, object],
+    table: str | Sequence[str],
+    *,
+    source: Path | None = None,
+) -> dict[str, object] | None:
+    """Select the table at *table* inside *data*.
+
+    :param data: A parsed TOML document, or any table inside one.
+    :param table: The path to select, dotted (``"tool.acme.needs"``) or as a sequence of
+        keys.
+    :param source: The file *data* came from, for error messages only.
+    :return: The table, or ``None`` when any segment of the path is absent.
+    :raises ProjectConfigError: If a segment is present but is not a table.
+    """
+    segments = table_path(table)
+    current: Mapping[str, object] = data
+    for depth, segment in enumerate(segments):
+        value = current.get(segment)
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            where = "" if source is None else f"{source}: "
+            dotted = render_path(segments[: depth + 1])
+            msg = f"{where}[{dotted}] must be a table, got {type(value).__name__}"
+            raise ProjectConfigError(msg)
+        current = value
+    return dict(current)
+
+
+def anchor(value: str | Path, base: Path) -> Path:
+    """Anchor a path read from the file at *base*, the file's own directory.
+
+    A relative *value* is joined onto *base*; an absolute one is returned untouched.
+    Joined, deliberately never ``resolve()``\\ d and never normalised: whether symlinks
+    are collapsed, or ``..`` folded away, is the consumer's decision -- one resolves for
+    symlink confinement, another keeps the form it was handed -- and the reader must not
+    take it behind their back.
+    """
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    return base / path

ub_project-1.0.0/src/ub_project/variant_data.py

@@ -0,0 +1,164 @@
+"""Variant data: validate it, load it from a JSON file, merge it, resolve it.
+
+The one copy of these four functions for the sphinx-needs family, to replace the copies
+sphinx-needs and sphinx-mounts carry once they adopt it (mounts' copy exists so that it
+never depends on sphinx-needs). Measured, the two copies differ in six places, and this
+one takes a side on each:
+
+* :func:`resolve_variant_data` always returns a FRESH merged mapping -- never one of its
+  arguments -- so that a consumer can store and change it freely at the top level
+  (mounts' behaviour; sphinx-needs handed back the inline object when there was no file);
+* the error wording is the set below, each message naming the dotted path (``var.a.b``)
+  and the rule it broke;
+* every failure to load the file is an :class:`~ub_project.project.ProjectConfigError`
+  (mounts'; sphinx-needs let ``OSError`` and ``UnicodeDecodeError`` escape);
+* an empty path is not "no file": the API takes ``Path | None``, and ``""`` names nothing
+  (mounts'; sphinx-needs read ``""`` as no file -- on the ``conf.py``/``-D`` route BOTH
+  consumers do, so a consumer maps ``""`` to ``None`` before calling this);
+* :func:`deep_merge` returns plain ``dict`` s at every level it builds, where both copies
+  returned the input's own mapping type (``.copy()``) -- unobservable through TOML or JSON,
+  which only produce plain dicts;
+* :func:`load_variant_data_file` takes a ``str`` path as well as a ``Path`` (sphinx-needs';
+  mounts' copy refused a ``str`` with ``AttributeError``).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ub_project.project import ProjectConfigError
+
+#: The types a leaf value, or every element of an array, may have. ``bool`` is listed
+#: although it is an ``int``: an array is checked by EXACT type, so ``[1, True]`` is mixed.
+_SCALAR_TYPES = (str, bool, int, float)
+
+_SCALARS = "str, bool, int or float"
+
+
+def validate_variant_data(data: object, path: str = "var") -> None:
+    """Check that *data* has the shape a variant map is allowed to have.
+
+    A table with string keys, whose values are scalars (``str``, ``bool``, ``int``,
+    ``float``), arrays that are empty or hold scalars of one exact type, or tables of the
+    same shape, recursively.
+
+    :param data: The value to check.
+    :param path: The dotted path of *data*, for the error message.
+    :raises ProjectConfigError: On the first violation, naming its dotted path.
+    """
+    if not isinstance(data, dict):
+        msg = f"{path}: variant data must be a table, got {type(data).__name__}"
+        raise ProjectConfigError(msg)
+    for key, value in data.items():
+        if not isinstance(key, str):
+            msg = f"{path}: keys must be strings, got {type(key).__name__} {key!r}"
+            raise ProjectConfigError(msg)
+        full = f"{path}.{key}"
+        if isinstance(value, dict):
+            validate_variant_data(value, full)
+        elif isinstance(value, list):
+            _validate_array(value, full)
+        elif not isinstance(value, _SCALAR_TYPES):
+            msg = (
+                f"{full}: a value must be a {_SCALARS}, an array or a table, "
+                f"got {type(value).__name__}"
+            )
+            raise ProjectConfigError(msg)
+
+
+def _validate_array(value: list[Any], path: str) -> None:
+    """An array must be empty, or hold scalars of one exact type."""
+    if not value:
+        return
+    first = type(value[0])
+    if first not in _SCALAR_TYPES:
+        msg = f"{path}: array elements must be a {_SCALARS}, got {first.__name__}"
+        raise ProjectConfigError(msg)
+    for index, item in enumerate(value):
+        if type(item) is not first:
+            msg = (
+                f"{path}[{index}]: an array must hold one type, expected "
+                f"{first.__name__} but got {type(item).__name__}"
+            )
+            raise ProjectConfigError(msg)
+
+
+def load_variant_data_file(path: Path | str) -> dict[str, Any]:
+    """Load a variant-data JSON file and validate its shape.
+
+    :param path: The file, already anchored by the caller.
+    :return: The validated mapping.
+    :raises ProjectConfigError: If the file is missing or unreadable, is not JSON, does not
+        hold a JSON object, or holds one of the wrong shape.
+    """
+    file = Path(path)
+    if file.is_dir():
+        msg = f"variant data file {file} is a directory"
+        raise ProjectConfigError(msg)
+    if not file.is_file():
+        msg = f"variant data file not found: {file}"
+        raise ProjectConfigError(msg)
+    try:
+        raw: object = json.loads(file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        msg = f"variant data file {file} is not valid JSON: {error}"
+        raise ProjectConfigError(msg) from error
+    except OSError as error:
+        msg = f"variant data file {file} cannot be read: {error}"
+        raise ProjectConfigError(msg) from error
+    if not isinstance(raw, dict):
+        msg = (
+            f"variant data file {file} must hold a JSON object, "
+            f"got {type(raw).__name__}"
+        )
+        raise ProjectConfigError(msg)
+    try:
+        validate_variant_data(raw)
+    except ProjectConfigError as error:
+        msg = f"variant data file {file}: {error}"
+        raise ProjectConfigError(msg) from error
+    return raw
+
+
+def deep_merge(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    """Merge *override* into *base*; *override* wins at the leaves.
+
+    Recurses ONLY when both sides hold a table under the same key. Everything else is a
+    wholesale replacement: an array replaces an array, a scalar replaces a table and a
+    table a scalar. That rule is what makes the merge idempotent --
+    ``deep_merge(base, deep_merge(base, override)) == deep_merge(base, override)`` -- so
+    re-merging an already-merged map is a no-op.
+
+    Neither argument is modified, and the result is a new mapping at every level the merge
+    recursed into. (Not a contract, and not something a second reader can reproduce: a
+    value taken whole from one side is, in this implementation, that side's object.)
+    """
+    result = dict(base)
+    for key, value in override.items():
+        existing = result.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            result[key] = deep_merge(existing, value)
+        else:
+            result[key] = value
+    return result
+
+
+def resolve_variant_data(
+    inline: Mapping[str, Any] | None, data_file: Path | None
+) -> dict[str, Any]:
+    """The merged variant map: the file first, the inline table deep-merged on top.
+
+    :param inline: The inline table; ``None`` and an empty table both mean "none".
+    :param data_file: An ALREADY ANCHORED path, or ``None``.
+    :return: A fresh mapping, never *inline* itself, even when there is no file.
+    :raises ProjectConfigError: If the file or the inline table is malformed.
+    """
+    base: dict[str, Any] = {}
+    if data_file is not None:
+        base = load_variant_data_file(data_file)
+    if inline:
+        validate_variant_data(inline)
+    return deep_merge(base, inline or {})

ub_project-1.0.0/src/ub_project/variants.py

@@ -0,0 +1,216 @@
+"""The top-level ``[variants]`` table, with the ``[needs] variant_data*`` fallback.
+
+``[variants]`` holds the project's variant data for every tool that reads it::
+
+    [variants]
+    data_file = "variants.json"   # ONE path, a string, anchored at this file's directory
+    [variants.data]               # deep-merged over the file; the inline table wins
+    edition = "pro"
+
+Before it existed the same two values lived in the ``[needs]`` table, as
+``variant_data_file`` and ``variant_data``, and every reader still accepts them there.
+Which location is read is decided WHOLE: both keys come from one table, never one from
+each.
+
+========================================  =================================================
+declared                                  read
+========================================  =================================================
+``[variants]`` only                       ``[variants]``
+``[needs] variant_data*`` only            ``[needs]``, plus ``variant_data_legacy_location``
+both                                      ``[variants]``, plus ``variant_data_location``
+                                          for every ``[needs]`` key it ignores
+neither                                   nothing: an empty map
+========================================  =================================================
+
+A location is DECLARED when it holds at least one of its two keys. A ``[variants]`` table
+holding neither -- empty, or only keys this version does not know -- declares nothing, so
+it cannot switch a project's ``[needs]`` data off.
+
+Diagnostics are RETURNED, never logged, and the package takes no side on them: whether
+the legacy location deserves a warning is the consumer's policy (sphinx-needs will warn,
+to move users; ubCode will not, because it supports several sphinx-needs versions at
+once). Hard failures raise :class:`~ub_project.project.ProjectConfigError`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from ub_project.project import (
+    ProjectConfigError,
+    anchor,
+    render_path,
+    select_table,
+    table_path,
+)
+from ub_project.variant_data import resolve_variant_data
+
+#: The top-level table this module reads.
+VARIANTS_TABLE = "variants"
+
+#: The keys of ``[variants]``, and their legacy spellings in ``[needs]``, in that order.
+VARIANTS_KEYS = ("data", "data_file")
+LEGACY_KEYS = ("variant_data", "variant_data_file")
+
+#: Diagnostic codes. Fixed: consumers suppress and test against them. They are the BARE
+#: subcodes; ubCode is to carry them under its own ``config.`` prefix
+#: (``config.variant_data_location``), and the conformance corpus compares the bare form.
+VARIANT_DATA_LOCATION = "variant_data_location"
+VARIANT_DATA_LEGACY_LOCATION = "variant_data_legacy_location"
+VARIANTS_UNKNOWN_KEY = "variants_unknown_key"
+
+Severity = Literal["warning", "info"]
+Location = Literal["variants", "needs"]
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """A non-fatal finding, returned for the consumer to report -- or not.
+
+    ``code``, ``path`` and ``message`` are those of ubCode's ``ConfigResolutionDiagnostic``
+    (whose ``code``, where it has one, carries a ``config.`` prefix), so that the conformance corpus can compare
+    the two readers' findings by ``code`` and ``path``; ``severity`` is this package's.
+    """
+
+    code: str
+    """One of the fixed codes above."""
+    path: str
+    """The dotted TOML path the finding is about, e.g. ``needs.variant_data_file``."""
+    message: str
+    """A sentence for a human; its wording is not part of any contract."""
+    severity: Severity
+    """``"warning"`` for something the file should change, ``"info"`` otherwise."""
+
+
+@dataclass(frozen=True, slots=True)
+class VariantsResult:
+    """What :func:`read_variants` found."""
+
+    data: dict[str, Any]
+    """The merged variant map: the file, with the inline table deep-merged on top."""
+    data_file: Path | None
+    """The data file of the location read, anchored at the TOML's directory."""
+    location: Location | None
+    """The table the data came from, or ``None`` when neither declared any."""
+    diagnostics: tuple[Diagnostic, ...]
+    """Every non-fatal finding, in a stable order."""
+
+
+def read_variants(
+    root_table: Mapping[str, object],
+    toml_path: Path,
+    *,
+    needs_table: str | Sequence[str] = "needs",
+) -> VariantsResult:
+    """Read the project's variant data from ``[variants]``, or from the legacy location.
+
+    :param root_table: The parsed TOML document (or the table a consumer's prefix
+        selected): ``[variants]`` is read from its top level.
+    :param toml_path: The file *root_table* came from. Relative ``data_file`` values are
+        anchored at its directory, and error messages name it.
+    :param needs_table: Where the legacy keys live inside *root_table*, dotted or as a
+        sequence of keys -- ``"tool.acme.needs"`` for a project that nests its sphinx-needs
+        configuration under a prefix.
+    :raises ProjectConfigError: If a table or key has the wrong type, if the inline data is
+        malformed, or if the data file of the location read is missing or malformed.
+    """
+    needs_path = table_path(needs_table)
+    needs_dotted = render_path(needs_path)
+
+    diagnostics: list[Diagnostic] = []
+    # an error, not something to skip, when `variants` is not a table: the name is this
+    # contract's, and a `variants = "..."` read as "no variant data" would be the silent
+    # vanishing the table exists to end
+    variants = select_table(root_table, VARIANTS_TABLE, source=toml_path) or {}
+    for key in sorted(set(variants) - set(VARIANTS_KEYS)):
+        diagnostics.append(
+            Diagnostic(
+                code=VARIANTS_UNKNOWN_KEY,
+                path=render_path((VARIANTS_TABLE, key)),
+                message=(
+                    f"{toml_path}: ignoring unknown key {key!r} in [{VARIANTS_TABLE}]; "
+                    f"this version reads {' and '.join(VARIANTS_KEYS)}"
+                ),
+                severity="warning",
+            )
+        )
+    needs = select_table(root_table, needs_path, source=toml_path) or {}
+    # "declared" is "set to a value": TOML has no null, and a Python caller's `None` means
+    # absent everywhere else in this package (`select_table` included)
+    declared_legacy = [key for key in LEGACY_KEYS if needs.get(key) is not None]
+
+    if any(variants.get(key) is not None for key in VARIANTS_KEYS):
+        location: Location = "variants"
+        table, keys, where = variants, VARIANTS_KEYS, f"[{VARIANTS_TABLE}]"
+        for key in declared_legacy:
+            diagnostics.append(
+                Diagnostic(
+                    code=VARIANT_DATA_LOCATION,
+                    path=f"{needs_dotted}.{key}",
+                    message=(
+                        f"{toml_path}: [{needs_dotted}] {key} is ignored because "
+                        f"[{VARIANTS_TABLE}] is set, and only one location is read; "
+                        f"remove the [{needs_dotted}] key"
+                    ),
+                    severity="warning",
+                )
+            )
+    elif declared_legacy:
+        location = "needs"
+        table, keys, where = needs, LEGACY_KEYS, f"[{needs_dotted}]"
+        for key in declared_legacy:
+            current = VARIANTS_KEYS[LEGACY_KEYS.index(key)]
+            diagnostics.append(
+                Diagnostic(
+                    code=VARIANT_DATA_LEGACY_LOCATION,
+                    path=f"{needs_dotted}.{key}",
+                    message=(
+                        f"{toml_path}: variant data is read from its legacy location "
+                        f"[{needs_dotted}] {key}; [{VARIANTS_TABLE}] {current} is the "
+                        "current one"
+                    ),
+                    severity="info",
+                )
+            )
+    else:
+        return VariantsResult(
+            data={}, data_file=None, location=None, diagnostics=tuple(diagnostics)
+        )
+
+    inline_key, file_key = keys
+    inline = table.get(inline_key)
+    if inline is not None and not isinstance(inline, dict):
+        msg = (
+            f"{toml_path}: {where} {inline_key} must be a table, "
+            f"got {type(inline).__name__}"
+        )
+        raise ProjectConfigError(msg)
+    file_value = table.get(file_key)
+    data_file: Path | None = None
+    if file_value is not None:
+        if not isinstance(file_value, str) or not file_value:
+            got = (
+                repr(file_value)
+                if isinstance(file_value, str)
+                else type(file_value).__name__
+            )
+            msg = (
+                f"{toml_path}: {where} {file_key} must be one non-empty path string, "
+                f"got {got}"
+            )
+            raise ProjectConfigError(msg)
+        data_file = anchor(file_value, toml_path.parent)
+    try:
+        data = resolve_variant_data(inline, data_file)
+    except ProjectConfigError as error:
+        msg = f"{toml_path}: {where}: {error}"
+        raise ProjectConfigError(msg) from error
+    return VariantsResult(
+        data=data,
+        data_file=data_file,
+        location=location,
+        diagnostics=tuple(diagnostics),
+    )