Skip to content

🐍 Geometric Computer Vision Library for Spatial AI

6.1 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.
#

"""No two public kornia functions or classes share a first docstring line.

``help()``, IDE hovers, the Sphinx autosummary tables and coding agents often read only the first docstring line.
When two different symbols share it -- ``match_nn``, ``match_snn`` and ``match_fginn`` once all said "Find nearest
neighbors in desc2 for each vector in desc1" -- that reader cannot tell which one it needs. Each first line therefore
names what sets its symbol apart from its siblings: the dimension, variant, criterion, input form or direction.

The one exception is a class and the function it wraps, whose names match once underscores are removed and case is
ignored (``AdjustHue`` / ``adjust_hue``, ``PyrDown`` / ``pyrdown``) and which live in the same top-level subpackage
(``kornia.enhance``): they do the same thing and may say so in the same words. A cross-package pair such as
``kornia.augmentation.Resize`` and ``kornia.geometry.transform.resize`` is not exempt.

The scan covers every name in the ``__all__`` of a non-private kornia module that is a function or a class defined
in kornia, deduplicated by object identity. Names that start with an underscore are out of scope, and so is a class
without a docstring of its own, which inherits one from its base. Lines are compared exactly after casefolding and
collapsing whitespace, so this catches copies, not near-duplicates: two lines that differ by a single word pass.
"""

import inspect
from functools import cache

import kornia

from testing.docstring_style import own_docstring, public_objects


def _first_line(doc: str) -> str:
    return next((line.strip() for line in inspect.cleandoc(doc).splitlines() if line.strip()), "")


def _qualified_name(obj: object) -> str:
    return f"{obj.__module__}.{obj.__qualname__}"


def _squash(name: str) -> str:
    return name.replace("_", "").casefold()


def _subpackage(obj: object) -> str:
    """Return the top-level kornia subpackage that defines ``obj``, such as ``kornia.enhance``."""
    return ".".join(obj.__module__.split(".")[:2])


def _is_wrapper_pair(objects: list) -> bool:
    """Whether ``objects`` is one class and one function of one subpackage whose names match without underscores."""
    if len(objects) != 2:
        return False
    classes = [obj for obj in objects if inspect.isclass(obj)]
    functions = [obj for obj in objects if inspect.isfunction(obj)]
    return (
        len(classes) == 1
        and len(functions) == 1
        and _squash(classes[0].__name__) == _squash(functions[0].__name__)
        and _subpackage(classes[0]) == _subpackage(functions[0])
    )


@cache
def _public_first_lines() -> dict[int, tuple[object, str]]:
    """Map ``id(obj)`` to ``(obj, first docstring line)`` for every public kornia function and class."""
    return {key: (obj, _first_line(own_docstring(obj))) for key, (obj, _) in public_objects().items()}


def test_the_scan_covers_the_public_api():
    # Guards against a vacuous pass: a discovery that silently stopped importing modules would find no duplicates.
    collected = _public_first_lines()
    assert len(collected) >= 800, len(collected)
    # Looked up through public names and matched by identity, so moving a definition to another file keeps this.
    for obj in (
        kornia.augmentation.ColorJitter,
        kornia.feature.match_snn,
        kornia.geometry.subpix.nms2d,
        kornia.losses.FocalLoss,
    ):
        assert id(obj) in collected, _qualified_name(obj)
    # A known wrapper pair is scanned and recognised; its two lines may, but need not, be identical.
    assert id(kornia.enhance.AdjustHue) in collected
    assert id(kornia.enhance.adjust_hue) in collected
    assert _is_wrapper_pair([kornia.enhance.AdjustHue, kornia.enhance.adjust_hue])


def test_the_wrapper_pair_rule():
    from kornia.enhance import adjust_hue, adjust_hue_raw
    from kornia.geometry.subpix import NonMaximaSuppression2d, nms2d
    from kornia.geometry.transform import PyrDown, pyrdown

    assert _is_wrapper_pair([PyrDown, pyrdown])
    assert not _is_wrapper_pair([NonMaximaSuppression2d, nms2d])
    assert not _is_wrapper_pair([adjust_hue, adjust_hue_raw])
    assert not _is_wrapper_pair([kornia.enhance.AdjustHue, adjust_hue, adjust_hue_raw])
    # Same name after squashing, but different subpackages.
    assert not _is_wrapper_pair([kornia.augmentation.Resize, kornia.geometry.transform.resize])


def test_first_docstring_lines_are_distinct():
    groups: dict[str, list] = {}
    for obj, line in _public_first_lines().values():
        # Case and spacing changes do not make two lines distinguishable to a reader.
        groups.setdefault(" ".join(line.casefold().split()), []).append((obj, line))

    offending = sorted(
        (sorted(_qualified_name(obj) for obj, _ in members), members[0][1])
        for members in groups.values()
        if len(members) > 1 and not _is_wrapper_pair([obj for obj, _ in members])
    )
    report = "\n".join(f"  {line!r}\n" + "\n".join(f"      {name}" for name in names) for names, line in offending)
    assert not offending, (
        f"{len(offending)} first docstring line(s) are shared by different public symbols, so help(), IDE hovers and "
        "the API tables cannot tell them apart. Give each symbol a first line that names what sets it apart from the "
        "others: dimension, variant, criterion, input form or direction. Only a class and the function it wraps, "
        "defined in the same subpackage with names that match without underscores (AdjustHue / adjust_hue), may "
        "share one.\n" + report
    )