Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

15.7 KB
Raw Blame
# LICENSE HEADER MANAGED BY add-license-header
#
# Copyright 2018 Kornia Team
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

"""Converted kornia modules keep the docstring style the rollout set out to give them.

``testing/docstring_rollout.py`` lists the modules that are converted. For those, this file enforces what a reader,
an IDE or a coding agent relies on and what a refactor silently breaks; the shape rule applies everywhere:

* every public function and class, exported by an ``__all__`` or documented on a docs page, has a docstring, so none
  escapes the checks below;
* every such function and class has a ``See Also:`` section whose entries name a sibling and say how it differs,
  unless its title line is a status title, ``Alias of :func:`target`.`` or ``Deprecated: use :func:`target`.``,
  which points to another public kornia object and needs none (``Deprecated: use`` only on an object that
  ``kornia.core._compat.deprecated`` wraps, ``Alias of`` only on one that forwards to its target unchanged, as
  ``testing.docstring_style.forwards_to`` checks);
* every Python-domain object role (``:func:``, ``:class:``, ``:meth:``, ``:attr:``, ``:data:``, ``:const:``,
  ``:exc:``, ``:obj:``) resolves to a name that Sphinx registers from ``docs/source``, or to a torch, Python or NumPy
  object of a type that role links in the cached intersphinx inventories, so it renders as a link and not as plain
  text (a short import alias is importable but is not a target), also in the docstrings of the methods, properties
  and attributes autodoc documents under a converted class; See Also entries name kornia objects only;
* every ``kornia/**/*.py`` file and every page Sphinx builds from ``docs/source`` writes a tensor shape as a literal
  such as ``(B, 1, H, W)``, not as ``:math:``, except for the values listed in ``MATH_NON_SHAPES``;
* the module docstring of a namespace names every export of its ``__all__`` in a role or a double-backtick literal.

The test ids are qualified names, or repository paths for the shape check, so a failure names what to fix. Run with
``-s`` to see the progress table.
"""

from __future__ import annotations

import importlib
import inspect
from pathlib import Path

import pytest

import kornia

from testing.docstring_rollout import (
    CATALOG_EXCEPTIONS,
    CATALOG_NAMESPACES,
    DOCSTRING_MODULES,
    EXCLUDED_PACKAGES,
    IN_SCOPE_PACKAGES,
    MATH_NON_SHAPES,
    SEE_ALSO_EXCEPTIONS,
)
from testing.docstring_style import (
    catalog_missing,
    catalog_required,
    catalog_unimportable,
    covered,
    docstring_roles,
    documented_members,
    forwards_to,
    intersphinx_names,
    is_deprecated_wrapper,
    is_documented,
    is_private_target,
    math_shape_roles,
    modules_declaring_all,
    own_docstring,
    reference_resolves,
    resolve_reference,
    rollout_objects,
    rst_pages,
    see_also_entries,
    sphinx_registry,
    status_target,
)

KORNIA_ROOT = Path(kornia.__file__).resolve().parent
REPO_ROOT = KORNIA_ROOT.parent
DOCS = REPO_ROOT / "docs" / "source"
REGISTRY = sphinx_registry(DOCS)
INTERSPHINX = intersphinx_names(DOCS)

CONVERTED = sorted(
    (
        (qualified, obj)
        for obj, qualified in rollout_objects(REGISTRY).values()
        if covered(obj.__module__, DOCSTRING_MODULES)
    ),
    key=lambda pair: pair[0],
)
UNDOCUMENTED = sorted(
    (
        qualified
        for obj, qualified in rollout_objects(REGISTRY, with_docstring=False).values()
        if covered(obj.__module__, DOCSTRING_MODULES)
    ),
)
MEMBERS = sorted(
    (qualified, member, doc)
    for qualified, (member, doc) in documented_members(REGISTRY, [obj for _, obj in CONVERTED]).items()
)

SHAPE_CHECK_FILES = sorted([*KORNIA_ROOT.rglob("*.py"), *rst_pages(DOCS)])


def _suggest(target: str) -> str:
    """Name the one registered full name that shares the last component of ``target``, if exactly one does."""
    last = target.removesuffix("()").rpartition(".")[2]
    matches = [name for name in REGISTRY if name.rpartition(".")[2] == last]
    return f" (registered as {matches[0]!r})" if len(matches) == 1 else ""


def _wrong_role(role: str, target: str) -> str:
    """Name the intersphinx types of ``target`` when it is there under a type that ``role`` does not link."""
    types = INTERSPHINX.get(target.removesuffix("()") if role in ("func", "meth") else target)
    return f" (an intersphinx {', '.join(sorted(types))}, which :{role}: does not link)" if types else ""


def test_rollout_selects_something() -> None:
    """The parametrized checks below are not vacuous: the rollout lists select objects and files."""
    assert CONVERTED, f"DOCSTRING_MODULES {DOCSTRING_MODULES} select no public object"
    assert SHAPE_CHECK_FILES, f"no source file or docs page found under {KORNIA_ROOT} and {DOCS}"
    assert CATALOG_NAMESPACES, "CATALOG_NAMESPACES is empty, so no module catalog is checked"
    assert REGISTRY, f"sphinx_registry({DOCS}) registered nothing"
    assert INTERSPHINX, f"intersphinx_names({DOCS}) found no inventory names"
    for prefix in DOCSTRING_MODULES:
        assert any(covered(obj.__module__, [prefix]) for _, obj in CONVERTED), (
            f"DOCSTRING_MODULES entry {prefix!r} selects no public object with a docstring"
        )


def test_every_package_is_assigned() -> None:
    present = {path.name for path in KORNIA_ROOT.iterdir() if path.is_dir() and (path / "__init__.py").exists()}
    present |= {path.stem for path in KORNIA_ROOT.glob("*.py") if not path.name.startswith("_")}
    assigned = set(IN_SCOPE_PACKAGES) | set(EXCLUDED_PACKAGES)
    assert present == assigned, (
        f"add {sorted(present - assigned)} to IN_SCOPE_PACKAGES or EXCLUDED_PACKAGES in testing/docstring_rollout.py; "
        f"remove {sorted(assigned - present)}, which no longer exist"
    )


def test_rollout_lists_are_real() -> None:
    lists = {
        "DOCSTRING_MODULES": DOCSTRING_MODULES,
        "CATALOG_NAMESPACES": CATALOG_NAMESPACES,
        "CATALOG_EXCEPTIONS": CATALOG_EXCEPTIONS,
    }
    for list_name, entries in lists.items():
        for entry in entries:
            parts = entry.split(".")
            package = parts[1] if parts[0] == "kornia" and len(parts) > 1 else None
            assert package in IN_SCOPE_PACKAGES, (
                f"{list_name} entry {entry!r} is not under kornia.<pkg> for an in-scope package"
            )
            importlib.import_module(entry)
    for entry in CATALOG_NAMESPACES:
        assert hasattr(importlib.import_module(entry), "__all__"), f"CATALOG_NAMESPACES entry {entry!r} has no __all__"
    for entry, reason in CATALOG_EXCEPTIONS.items():
        assert entry not in CATALOG_NAMESPACES, f"{entry!r} is both catalogued and excepted"
        assert reason.strip(), f"CATALOG_EXCEPTIONS entry {entry!r} needs a reason"
        assert catalog_required(entry, CATALOG_NAMESPACES), f"{entry!r} no longer needs a catalog exception"
    converted = {qualified for qualified, _ in CONVERTED}
    for key, reason in SEE_ALSO_EXCEPTIONS.items():
        assert key in converted, f"SEE_ALSO_EXCEPTIONS key {key!r} is not a converted object"
        assert reason.strip(), f"SEE_ALSO_EXCEPTIONS entry {key!r} needs a reason"


@pytest.mark.parametrize("qualified", UNDOCUMENTED, ids=UNDOCUMENTED)
def test_converted_object_has_docstring(qualified: str) -> None:
    pytest.fail(
        f"{qualified} is exported without a docstring, so the checks cannot see it; write one. A thin wrapper "
        "that only forwards to another object starts with 'Alias of :func:`target`.', a deprecated one with "
        "'Deprecated: use :func:`target`.'"
    )


@pytest.mark.parametrize(("qualified", "obj"), CONVERTED, ids=[qualified for qualified, _ in CONVERTED])
def test_converted_object_has_see_also(qualified: str, obj: object) -> None:
    if qualified in SEE_ALSO_EXCEPTIONS:
        pytest.skip(f"excepted: {SEE_ALSO_EXCEPTIONS[qualified]}")
    doc = own_docstring(obj)
    entries = see_also_entries(doc)
    target = status_target(doc)
    if target:
        # an "Alias of" or "Deprecated: use" title points to another public kornia object, only a deprecated object
        # says "Deprecated: use", and only one that forwards to its target says "Alias of", whether or not a See
        # Also follows
        resolved = resolve_reference(obj, target, REGISTRY)
        message = f"{qualified}: a status title points to another public kornia object, not to {target!r}"
        assert resolved is not None, message
        assert resolved is not obj, message
        assert not is_private_target(target), message
        assert not doc.lstrip().startswith("Deprecated: use") or is_deprecated_wrapper(obj), (
            f"{qualified} has a 'Deprecated: use' title but is not wrapped by kornia.core._compat.deprecated"
        )
        assert not doc.lstrip().startswith("Alias of") or forwards_to(obj, resolved), (
            f"{qualified} has an 'Alias of' title but does not only forward to {target!r}: an alias function returns "
            "the target called with its own arguments, unchanged and with the target's defaults, and an alias class "
            "subclasses it and adds nothing"
        )
        if entries is None:
            return  # the title points to the target, so a See Also would only repeat it
    assert entries, (
        f"{qualified} needs a 'See Also:' section with at least one bullet like "
        "'- :func:`name`: how it differs.' (or an entry in SEE_ALSO_EXCEPTIONS with a reason)"
    )
    problems = []
    for target, explanation in entries:
        if not target:
            problems.append(f"{explanation!r} does not start with a role such as :func:`name`, so it is no link")
            continue
        if not explanation:
            problems.append(f"{target!r} has no explanation after the colon")
        if is_private_target(target):
            problems.append(f"{target!r} is private")
        resolved = resolve_reference(obj, target, REGISTRY)
        if resolved is obj:
            problems.append(f"{target!r} links the object to itself")
        if resolved is None and target.removesuffix("()") in INTERSPHINX:
            problems.append(
                f"{target!r} is not a kornia object; See Also lists kornia objects, so mention torch and Python "
                "functions in the contract paragraph instead"
            )
    assert not problems, f"{qualified} See Also: " + "; ".join(problems)


def _unresolved_references(qualified: str, obj: object, doc: str | None, registered_as: str | None = None) -> str:
    """Describe the roles in ``doc``, the docstring of ``obj`` shown as ``qualified``, that Sphinx cannot link.

    With ``registered_as``, the roles resolve in the scopes of that registered entry only, as Sphinx resolves each
    rendered entry; without it, in those of every name the registry gives ``obj``.
    """
    unresolved = [
        f":{role}:`{target}`{_suggest(target)}{_wrong_role(role, target)}"
        for role, target in docstring_roles(doc)
        if not reference_resolves(obj, target, REGISTRY, INTERSPHINX, role, registered_as)
    ]
    if not unresolved:
        return ""
    hint = "write the full name the docs register"
    if not is_documented(obj, REGISTRY):
        hint = f"{qualified} is not documented on any docs/source page, so short names have no scope; {hint}"
    return f"{qualified} has references Sphinx cannot link ({hint}): " + ", ".join(unresolved)


@pytest.mark.parametrize(("qualified", "obj"), CONVERTED, ids=[qualified for qualified, _ in CONVERTED])
def test_converted_object_references_resolve(qualified: str, obj: object) -> None:
    assert not (message := _unresolved_references(qualified, obj, own_docstring(obj))), message


@pytest.mark.parametrize(("qualified", "member", "doc"), MEMBERS, ids=[qualified for qualified, _, _ in MEMBERS])
def test_converted_class_member_references_resolve(qualified: str, member: object, doc: str) -> None:
    """The methods, properties and attributes autodoc renders under a converted class link their references too.

    Each is checked under its own registered name, so a method inherited by several documented classes has to link
    its references on every class page that renders it.
    """
    assert not (message := _unresolved_references(qualified, member, doc, registered_as=qualified)), message


@pytest.mark.parametrize(
    "path", SHAPE_CHECK_FILES, ids=[path.relative_to(REPO_ROOT).as_posix() for path in SHAPE_CHECK_FILES]
)
def test_no_math_shape_roles(path: Path) -> None:
    relative = path.relative_to(REPO_ROOT).as_posix()
    values = MATH_NON_SHAPES.get(relative, {})
    found = [content for content in math_shape_roles(path.read_text(encoding="utf-8")) if content not in values]
    assert found == [], (
        f"{relative} writes shapes as :math: {found}; use literals like ``(B, 1, H, W)``, or list a tuple that is "
        "a value, not a shape, in MATH_NON_SHAPES with what it is"
    )


def test_math_non_shapes_are_current() -> None:
    """Every ``MATH_NON_SHAPES`` entry names a checked file that still writes that tuple as ``:math:``."""
    checked = {path.relative_to(REPO_ROOT).as_posix(): path for path in SHAPE_CHECK_FILES}
    for relative, values in MATH_NON_SHAPES.items():
        assert relative in checked, f"MATH_NON_SHAPES key {relative!r} is not a checked source file or docs page"
        found = set(math_shape_roles(checked[relative].read_text(encoding="utf-8")))
        for content, reason in values.items():
            assert content in found, f"MATH_NON_SHAPES entry {content!r} no longer occurs in {relative}; remove it"
            assert reason.strip(), f"MATH_NON_SHAPES entry {content!r} in {relative} needs a reason"


@pytest.mark.parametrize("namespace", CATALOG_NAMESPACES)
def test_catalog_names_every_export(namespace: str) -> None:
    module = importlib.import_module(namespace)
    doc = inspect.getdoc(module) or ""
    missing = catalog_missing(doc, sorted(module.__all__), module)
    assert missing == [], (
        f"the module docstring of {namespace} does not mention {missing}; list every export as a role such as "
        ":func:`name` or a literal such as ``name``, and spell a qualified name as a path to that export"
    )
    broken = catalog_unimportable(module, doc)
    assert not broken, f"the module docstring of {namespace} has references that do not import: {broken}"


def test_rollout_progress() -> None:
    """Print, per in-scope package, the converted objects and catalogued namespaces (read it with ``-s``)."""
    objects = [obj for obj, _ in rollout_objects(REGISTRY).values()]
    namespaces = modules_declaring_all()
    print("\npackage        converted objects   catalogued namespaces   excepted namespaces")
    for package in IN_SCOPE_PACKAGES:
        prefix = f"kornia.{package}"
        in_package = [obj for obj in objects if covered(obj.__module__, [prefix])]
        done = [obj for obj in in_package if covered(obj.__module__, DOCSTRING_MODULES)]
        excepted = [ns for ns in CATALOG_EXCEPTIONS if covered(ns, [prefix])]
        required = [
            ns
            for ns in namespaces
            if ns not in CATALOG_EXCEPTIONS and covered(ns, [prefix]) and catalog_required(ns, CATALOG_NAMESPACES)
        ]
        catalogued = [ns for ns in required if ns in CATALOG_NAMESPACES]
        print(
            f"{package:<14} {len(done):>4} / {len(in_package):<12} "
            f"{len(catalogued):>4} / {len(required):<18} {len(excepted)}"
        )