π Geometric Computer Vision Library for Spatial AI
Python artificial-intelligencecomputer-visiondeep-learninghacktoberfestimage-processingmachine-learningneural-networkpythonpytorchroboticsspatial-ai
# 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.
#
"""Tests for the shared docstring-style helpers in ``testing/docstring_style.py``."""
import functools
import inspect
from functools import cache
from pathlib import Path
import pytest
import kornia
from kornia.augmentation.auto.operations.ops import AutoContrast
from kornia.geometry.boxes import Boxes, Boxes3D
from kornia.geometry.depth import DepthWarper, depth_to_3d, depth_to_3d_v2
from testing import docstring_style
from testing.docstring_style import (
_Attribute,
catalog_missing,
catalog_required,
catalog_unimportable,
covered,
docstring_roles,
documented_members,
forwards_to,
intersphinx_names,
is_deprecated_wrapper,
is_documented,
is_private_target,
is_shape_tuple,
math_shape_roles,
own_docstring,
public_objects,
reference_resolves,
resolve_reference,
rollout_objects,
see_also_entries,
sphinx_registry,
status_target,
undocumented_public_objects,
)
DOCS = Path(__file__).resolve().parents[1] / "docs" / "source"
@cache
def _registry():
return sphinx_registry(DOCS)
def test_shape_predicate():
for s in ["(B, 3, H, W)", "(*, H, W)", "(B,)", "(B, N, 2)", "(B, H/2, W/2)", "(..., 3)", "(H_out, W_out)"]:
assert is_shape_tuple(s), s
for s in [
"(x, y)",
"(u, v)",
"(B, C_{in}, H, W)",
r"(H \times W)",
"()",
"(B, C, h, w)",
"(-0.436, 0.436)",
"(1, kH, kW)",
]:
assert not is_shape_tuple(s), s
def test_math_shape_roles():
assert math_shape_roles("a :math:`(B, 3, H, W)` b :math:`(x, y)` c ``(B, N)``") == ["(B, 3, H, W)"]
def test_docstring_roles():
doc = "Use :func:`~kornia.a.b` or :py:class:`C`, :meth:`forward`; not :cite:`X` or :math:`y`."
assert docstring_roles(doc) == [("func", "kornia.a.b"), ("class", "C"), ("meth", "forward")]
doc = "Read :attr:`data`, :py:exc:`ValueError`, :data:`sys.stdout`, :const:`LIMIT`, :obj:`x`; not :mod:`torch`."
assert docstring_roles(doc) == [
("attr", "data"),
("exc", "ValueError"),
("data", "sys.stdout"),
("const", "LIMIT"),
("obj", "x"),
]
def test_see_also_entries():
doc = (
"Do a thing.\n\nArgs:\n x: input.\n\nSee Also:\n"
" - :func:`depth_to_3d_v2`: the same points channels last.\n"
" - :func:`depth_to_3d_v2`, :func:`~kornia.geometry.camera.perspective.project_points`: the two halves\n"
" of the warp.\n\nExample:\n >>> 1\n"
)
assert see_also_entries(doc) == [
("depth_to_3d_v2", "the same points channels last."),
("depth_to_3d_v2", "the two halves of the warp."),
("kornia.geometry.camera.perspective.project_points", "the two halves of the warp."),
]
assert see_also_entries(
"Do.\n\nSee Also:\n - :func:`depth_to_3d_v2`: like :func:`depth_to_3d` but channels last.\n"
) == [("depth_to_3d_v2", "like :func:`depth_to_3d` but channels last.")]
assert see_also_entries("Do.\n\nSee Also:\n Prose only.\n") == []
assert see_also_entries("Do.\n\nSee Also:\n - :func:`a`: b.\n.. image:: foo.png\n") == [("a", "b.")]
assert see_also_entries("Do.\n\nArgs:\n x: y.\n") is None
assert see_also_entries("Do.\n\nSee Also:\n - :func:`a`\n") == [("a", "")]
# A bullet without a leading role renders without a link; it is an entry with an empty target, not skipped.
assert see_also_entries("Do.\n\nSee Also:\n - :func:`a`: b.\n - ``c``: d.\n - kornia.e: f.\n") == [
("a", "b."),
("", "``c``: d."),
("", "kornia.e: f."),
]
# Any Python-domain object role links, so it leads an entry; :mod: does not name an object.
doc = "Do.\n\nSee Also:\n - :attr:`~kornia.x.Y.z`: an attribute.\n - :exc:`E`: raised.\n - :mod:`m`: no.\n"
assert see_also_entries(doc) == [("kornia.x.Y.z", "an attribute."), ("E", "raised."), ("", ":mod:`m`: no.")]
def test_registry_uses_documented_paths():
reg = _registry()
assert "kornia.geometry.camera.perspective.unproject_points" in reg
assert "kornia.geometry.camera.unproject_points" not in reg
assert "kornia.geometry.homography.find_homography_dlt" in reg # automodule :members:
assert "kornia.geometry.depth.DepthWarper.compute_projection_matrix" in reg # autoclass :members:
def test_reference_resolution():
reg = _registry()
assert reference_resolves(depth_to_3d, "depth_to_3d_v2", reg)
assert reference_resolves(depth_to_3d, "kornia.geometry.camera.perspective.unproject_points", reg)
assert not reference_resolves(depth_to_3d, "kornia.geometry.camera.unproject_points", reg)
assert not reference_resolves(depth_to_3d, "kornia.geometry.depth.no_such_function", reg)
assert reference_resolves(DepthWarper, "compute_projection_matrix", reg)
# Sphinx drops a trailing ``()`` and tries a dotted target under the page's module too.
assert resolve_reference(depth_to_3d, "depth_to_3d_v2()", reg) is depth_to_3d_v2
assert resolve_reference(Boxes3D, "Boxes.to_tensor", reg) is Boxes.to_tensor
assert not reference_resolves(depth_to_3d, "kornia.geometry.camera.unproject_points()", reg)
assert not reference_resolves(Boxes3D, "geometry.boxes.Boxes.to_tensor", reg)
def test_resolve_reference_returns_the_target_object():
reg = _registry()
assert resolve_reference(depth_to_3d, "depth_to_3d_v2", reg) is depth_to_3d_v2
assert resolve_reference(depth_to_3d, "depth_to_3d", reg) is depth_to_3d
assert resolve_reference(depth_to_3d, "no_such_function", reg) is None
assert resolve_reference(depth_to_3d, "kornia.geometry.camera.unproject_points", reg) is None
def test_intersphinx_names():
names = intersphinx_names(DOCS)
assert names["torch.nn.functional.grid_sample"] == {"function"}
assert names["torch.Tensor"] == {"class"}
assert names["ValueError"] == {"exception"}
assert names["random"] == {"module"}
assert "torch.nn.functional.no_such_function" not in names
reg = _registry()
assert resolve_reference(depth_to_3d, "torch.nn.functional.grid_sample", reg) is None
assert reference_resolves(depth_to_3d, "torch.nn.functional.grid_sample", reg, names)
assert not reference_resolves(depth_to_3d, "torch.nn.functional.no_such_function", reg, names)
def test_intersphinx_links_a_role_only_to_its_object_types():
"""Intersphinx matches the role to the object type, unlike the local lookup (Sphinx ``objtypes_for_role``)."""
names, reg = intersphinx_names(DOCS), _registry()
cases = [
("func", "torch.svd", True),
("obj", "torch.svd", True),
("meth", "torch.svd", False),
("attr", "torch.svd", False),
("meth", "torch.Tensor.add", True),
("func", "torch.Tensor.add", False),
# Inventories from before Sphinx 2.1 store properties as methods, so intersphinx lets :attr: find a method.
("attr", "torch.Tensor.add", True),
("attr", "torch.Tensor.shape", True),
("meth", "torch.Tensor.shape", False),
("exc", "ValueError", True),
("class", "ValueError", True),
("func", "ValueError", False),
("class", "torch.Tensor", True),
("exc", "torch.Tensor", True),
("data", "sys.stdout", True),
("attr", "sys.stdout", False),
# :const: is in no object type's roles, so intersphinx never links it.
("const", "sys.stdout", False),
("const", "math.pi", False),
("obj", "random", True),
("func", "random", False),
]
for role, target, expected in cases:
assert reference_resolves(depth_to_3d, target, reg, names, role) is expected, (role, target)
def test_only_func_and_meth_drop_parentheses():
names, reg = intersphinx_names(DOCS), _registry()
assert resolve_reference(depth_to_3d, "depth_to_3d_v2()", reg, "func") is depth_to_3d_v2
assert resolve_reference(DepthWarper, "compute_projection_matrix()", reg, "meth") is not None
assert resolve_reference(depth_to_3d, "DepthWarper()", reg, "class") is None
assert resolve_reference(depth_to_3d, "DepthWarper", reg, "class") is DepthWarper
assert reference_resolves(depth_to_3d, "torch.svd()", reg, names, "func")
assert not reference_resolves(depth_to_3d, "torch.Tensor()", reg, names, "class")
def test_short_names_need_a_documented_object():
# Keep this object deliberately unregistered even as the real documentation grows.
reg = {name: obj for name, obj in _registry().items() if obj is not AutoContrast}
assert is_documented(depth_to_3d, reg)
assert not is_documented(AutoContrast, reg)
# With no page, and so no scope, only a full name resolves from its docstring.
assert resolve_reference(AutoContrast, "kornia.geometry.depth.depth_to_3d", reg) is depth_to_3d
assert resolve_reference(AutoContrast, "depth_to_3d", reg) is None
def _write_page(root: Path, relative: str, text: str) -> None:
page = root / relative
page.parent.mkdir(parents=True, exist_ok=True)
page.write_text(text, encoding="utf-8")
def test_autosummary_registers_only_with_toctree(tmp_path):
_write_page(tmp_path, "links.rst", ".. currentmodule:: kornia.color\n\n.. autosummary::\n\n yuv_to_rgb\n")
assert sphinx_registry(tmp_path) == {}
_write_page(
tmp_path,
"links.rst",
".. currentmodule:: kornia.color\n\n.. autosummary::\n :toctree: api\n\n yuv_to_rgb\n",
)
assert sphinx_registry(tmp_path) == {"kornia.color.yuv_to_rgb": kornia.color.yuv_to_rgb}
def test_registry_reads_pages_in_subdirectories(tmp_path):
_write_page(tmp_path, "models/page.rst", ".. autofunction:: kornia.color.yuv_to_rgb\n")
_write_page(tmp_path, "_build/page.rst", ".. autofunction:: kornia.color.rgb_to_yuv\n")
_write_page(tmp_path, "_templates/page.rst", ".. autofunction:: kornia.color.rgb_to_hsv\n")
assert sphinx_registry(tmp_path) == {"kornia.color.yuv_to_rgb": kornia.color.yuv_to_rgb}
def test_members_follow_autodoc_docstring_rule(tmp_path):
"""``:members:`` documents an inherited docstring; a method with none only under ``:undoc-members:``."""
page = ".. currentmodule:: kornia.augmentation\n\n.. autoclass:: {}\n :members:\n{}"
intensity = "kornia.augmentation.IntensityAugmentationBase2D"
mix = "kornia.augmentation.MixAugmentationBaseV2"
assert own_docstring(kornia.augmentation.IntensityAugmentationBase2D.apply_transform_mask) is None
_write_page(tmp_path, "page.rst", page.format("IntensityAugmentationBase2D", ""))
assert f"{intensity}.apply_transform_mask" in sphinx_registry(tmp_path)
assert own_docstring(kornia.augmentation.MixAugmentationBaseV2.apply_non_transform) is None
_write_page(tmp_path, "page.rst", page.format("MixAugmentationBaseV2", ""))
assert f"{mix}.apply_non_transform" not in sphinx_registry(tmp_path)
_write_page(tmp_path, "page.rst", page.format("MixAugmentationBaseV2", " :undoc-members:\n"))
assert f"{mix}.apply_non_transform" in sphinx_registry(tmp_path)
def test_registry_registers_documented_data_attributes():
"""Enum members and dataclass fields under ``:undoc-members:`` link, even when the value is ``None``."""
reg = _registry()
assert kornia.models.sam.SamConfig.checkpoint is None
for target in ("kornia.color.CFA.BG", "kornia.image.ImageSize.height", "kornia.models.sam.SamConfig.checkpoint"):
assert resolve_reference(depth_to_3d, target, reg) is not None, target
assert reference_resolves(depth_to_3d, target, reg, role="attr"), target
_ATTRIBUTE_SOURCES = {
"docstyle_attrs.py": '''
import enum
from dataclasses import dataclass
from typing import NamedTuple
class Commented:
"""A class."""
#: before
before = 1
after = 2 #: after
annotated: int
"""string after"""
plain = 3
hashed = 4 # an ordinary comment
#: two lines
#: of comment
two = 5
#: separated by a blank line
separated = 6
multi = (
1,
2,
) #: after a multi-line value
try:
in_try = 7 #: in try
except Exception:
in_except = 8 #: in except
_private = 9 #: private
def __init__(self):
self.instance = 10 #: instance
self.undocumented = 11
local = 12 #: a local
def nested():
self.nested = 13 #: in a nested function
self.after_nested = 15 #: after a nested function
def other(self):
self.elsewhere = 14 #: in another method
class Undoc:
"""Same kinds, under undoc-members."""
plain = 1
annotated_only: int
hashed = 2 # ordinary
def __init__(self):
self.instance = 3
@property
def prop(self):
return 1
class Point(NamedTuple):
"""A point."""
x: float
y: float
class Color(enum.Enum):
"""Colors."""
RED = 1
GREEN = 2 #: green
@dataclass
class Config:
"""A config."""
size: int = 1
name: str | None = None
''',
"docstyle_module.py": (
'"""Data with __all__."""\n\n#: documented\nLIMIT = 3\nOTHER = 4\n__all__ = ["LIMIT", "OTHER"]\n'
),
"docstyle_noall.py": (
'"""Data without __all__."""\n\nfrom math import pi #: imported here\n\n#: documented\nLIMIT = 3\nOTHER = 4\n'
),
"docstyle_undoc.py": (
'"""Data with __all__, under undoc-members."""\n\n__all__ = ["BARE", "PLAIN", "COMMENTED"]\nBARE: int\n'
"PLAIN = 1\n#: doc\nCOMMENTED = 2\n"
),
}
_ATTRIBUTE_PAGE = """
.. autoclass:: docstyle_attrs.Commented
:members:
.. autoclass:: docstyle_attrs.Undoc
:members:
:undoc-members:
.. autoclass:: docstyle_attrs.Point
:members:
.. autoclass:: docstyle_attrs.Color
:members:
.. autoclass:: docstyle_attrs.Config
:members:
:undoc-members:
.. automodule:: docstyle_module
:members:
.. automodule:: docstyle_noall
:members:
:undoc-members:
.. automodule:: docstyle_undoc
:members:
:undoc-members:
"""
def test_registry_matches_sphinx_on_documented_attributes(tmp_path, monkeypatch):
"""The registry holds the names a Sphinx 8.2.3 build of the same page puts into ``objects.inv``.
The expected set is that build's inventory, modules left out. To regenerate it, write these sources and the page
(as ``index.rst``, with a ``conf.py`` that adds ``sphinx.ext.autodoc`` and puts the sources on ``sys.path``), run
``uv run --no-project --with sphinx==8.2.3 python -m sphinx -b html src out``, then
``python -m sphinx.ext.intersphinx out/objects.inv``.
"""
for name, source in _ATTRIBUTE_SOURCES.items():
(tmp_path / name).write_text(source, encoding="utf-8")
monkeypatch.syspath_prepend(str(tmp_path))
_write_page(tmp_path / "docs", "index.rst", _ATTRIBUTE_PAGE)
registered = {name for name, obj in sphinx_registry(tmp_path / "docs").items() if not inspect.ismodule(obj)}
a = "docstyle_attrs"
assert registered == {
*(f"{a}.{name}" for name in ("Commented", "Undoc", "Point", "Color", "Config")),
*(f"{a}.Commented.{name}" for name in ("before", "after", "annotated", "two", "multi", "in_try")),
f"{a}.Commented.instance",
f"{a}.Commented.after_nested",
*(f"{a}.Undoc.{name}" for name in ("plain", "annotated_only", "hashed", "prop")),
f"{a}.Point.x",
f"{a}.Point.y",
f"{a}.Color.GREEN",
f"{a}.Config.size",
f"{a}.Config.name",
"docstyle_module.LIMIT",
"docstyle_noall.LIMIT",
"docstyle_undoc.BARE",
"docstyle_undoc.COMMENTED",
}
def test_covered_prefix():
assert covered("kornia.color.rgb", ["kornia.color"])
assert not covered("kornia.colorx", ["kornia.color"])
def test_catalog_missing():
depth, enhance = kornia.geometry.depth, kornia.enhance
names = ["depth_to_3d", "depth_to_3d_v2"]
assert catalog_missing("use :func:`depth_to_3d_v2` here", names, depth) == ["depth_to_3d"]
assert catalog_missing("use ``depth_to_3d_v2()`` here", names, depth) == ["depth_to_3d"]
assert catalog_missing("- ``depth_to_3d``: points.", ["depth_to_3d"], depth) == []
assert catalog_missing("- ``depth_to_3d()``: points.", ["depth_to_3d"], depth) == []
assert catalog_missing("- :func:`~kornia.geometry.depth.depth_to_3d`: points.", ["depth_to_3d"], depth) == []
assert catalog_missing("- :func:`kornia.geometry.depth.depth_to_3d`: points.", ["depth_to_3d"], depth) == []
# A plain word is not a mention, and neither is a longer name that ends with it.
assert catalog_missing("Use the morphological opening and closing.", ["opening", "closing"], kornia.morphology) == [
"opening",
"closing",
]
assert catalog_missing("use depth_to_3d here", ["depth_to_3d"], depth) == ["depth_to_3d"]
assert catalog_missing(":func:`my_depth_to_3d`", ["depth_to_3d"], depth) == ["depth_to_3d"]
# Single backticks are the default role, which renders as italics, and :math: is no reference: neither counts.
assert catalog_missing("use `depth_to_3d` here", ["depth_to_3d"], depth) == ["depth_to_3d"]
assert catalog_missing("the :math:`depth_to_3d` term", ["depth_to_3d"], depth) == ["depth_to_3d"]
assert catalog_missing("use :py:func:`depth_to_3d` here", ["depth_to_3d"], depth) == []
# A qualified target counts only as the exported object: torch's normalize is not kornia.enhance.normalize, which
# is reached through the package or its defining module even though a submodule shares its name.
for other in (":func:`torch.nn.functional.normalize`", "``torch.nn.functional.normalize``"):
assert catalog_missing(f"for L2, use {other}", ["normalize"], enhance) == ["normalize"]
for same in (
":func:`~kornia.enhance.normalize`",
"``kornia.enhance.normalize``",
":func:`kornia.enhance.normalize.normalize`",
):
assert catalog_missing(f"use {same}", ["normalize"], enhance) == []
def test_catalog_unimportable():
depth = kornia.geometry.depth
doc = (
":func:`depth_to_3d`, :func:`depth_to_3d()`, :func:`~kornia.geometry.depth.depth_to_3d_v2()` and "
":class:`kornia.geometry.depth.DepthWarper`"
)
assert catalog_unimportable(depth, doc) == []
assert catalog_unimportable(depth, ":func:`depth_to_4d()` and :func:`kornia.geometry.depth.nope`") == [
"depth_to_4d()",
"kornia.geometry.depth.nope",
]
def test_catalog_required():
assert catalog_required("kornia.geometry.depth", [])
# kornia.enhance re-exports everything kornia.enhance.normalize declares, as the same objects.
assert not catalog_required("kornia.enhance.normalize", ["kornia.enhance"])
assert catalog_required("kornia.enhance.normalize", [])
def test_own_docstring_and_public_objects():
class Base:
"""Base doc."""
class Child(Base):
pass
assert own_docstring(Base) == "Base doc."
assert own_docstring(Child) is None
assert id(depth_to_3d) in public_objects()
assert public_objects()[id(depth_to_3d)][1] == "kornia.geometry.depth.depth_to_3d"
def test_function_sharing_a_submodule_name_is_the_function():
reg = _registry()
assert reg["kornia.filters.sobel"] is kornia.filters.sobel
assert resolve_reference(kornia.filters.sobel, "sobel", reg) is kornia.filters.sobel
def test_explicit_members_list_registers_only_the_listed_names():
reg = _registry()
assert "kornia.feature.SOLD2.match" not in reg
assert "kornia.feature.SOLD2.forward" in reg
def test_automodule_members_register_class_methods():
reg = _registry()
assert "kornia.geometry.boxes.Boxes.to_tensor" in reg
def test_special_members_register_dunder_methods(tmp_path):
"""``:special-members:`` alone selects every documented ``__name__`` method, a list only the listed ones."""
reg = _registry()
assert reg["kornia.geometry.quaternion.Quaternion.__init__"] is kornia.geometry.quaternion.Quaternion.__init__
assert "kornia.geometry.quaternion.Quaternion.__add__" in reg
# No docstring, and none to inherit: a one-page Sphinx 8.2.3 build leaves it out too.
assert "kornia.geometry.quaternion.Quaternion.__mul__" not in reg
assert "kornia.geometry.pose.NamedPose.__mul__" in reg # :special-members: __init__, __mul__
assert "kornia.geometry.pose.NamedPose.__repr__" not in reg
quaternion = "kornia.geometry.quaternion.Quaternion"
page = ".. currentmodule:: kornia.geometry.quaternion\n\n.. autoclass:: Quaternion\n{}"
_write_page(tmp_path, "page.rst", page.format(" :members:\n"))
assert f"{quaternion}.__init__" not in sphinx_registry(tmp_path)
# Without :members:, all special members document nothing; a list documents the listed names.
_write_page(tmp_path, "page.rst", page.format(" :special-members:\n"))
assert sphinx_registry(tmp_path) == {quaternion: kornia.geometry.quaternion.Quaternion}
_write_page(tmp_path, "page.rst", page.format(" :special-members: __add__\n"))
assert set(sphinx_registry(tmp_path)) == {quaternion, f"{quaternion}.__add__"}
_write_page(tmp_path, "page.rst", page.format(" :members: w\n :special-members: __add__\n"))
assert set(sphinx_registry(tmp_path)) == {quaternion, f"{quaternion}.w", f"{quaternion}.__add__"}
# A module's special members apply to its classes.
_write_page(
tmp_path, "page.rst", ".. automodule:: kornia.geometry.quaternion\n :members:\n :special-members:\n"
)
assert f"{quaternion}.__add__" in sphinx_registry(tmp_path)
def test_nested_automethod_registers_under_its_class():
assert "kornia.geometry.camera.stereo.StereoCamera.__init__" in _registry()
def test_registry_rejects_options_it_does_not_model(tmp_path):
"""An option that changes what autodoc registers fails loudly instead of skewing the registry."""
for option in ("no-index", "exclude-members", "inherited-members", "private-members"):
_write_page(
tmp_path, "page.rst", f".. autoclass:: kornia.geometry.depth.DepthWarper\n :members:\n :{option}:\n"
)
with pytest.raises(ValueError, match=option):
sphinx_registry(tmp_path)
def test_py_prefixed_currentmodule_sets_the_scope(tmp_path):
_write_page(tmp_path, "page.rst", ".. py:currentmodule:: kornia.color\n\n.. autofunction:: yuv_to_rgb\n")
assert sphinx_registry(tmp_path) == {"kornia.color.yuv_to_rgb": kornia.color.yuv_to_rgb}
def test_private_target():
assert is_private_target("_helper")
assert is_private_target("kornia.geometry.depth._depth_grid_dtype")
assert is_private_target("kornia.x.Class.__mangled")
# A special method that ``:special-members:`` documents is public.
assert not is_private_target("kornia.geometry.pose.NamedPose.__mul__")
assert not is_private_target("depth_to_3d")
def test_own_docstring_ignores_whitespace_only():
def blank():
""" """
assert own_docstring(blank) is None
@pytest.mark.parametrize(
("doc", "target"),
[
("Alias of :func:`axis_angle_to_rotation_matrix`.", "axis_angle_to_rotation_matrix"),
("Alias of :class:`kornia.geometry.depth.DepthWarper`.", "kornia.geometry.depth.DepthWarper"),
(
"Alias of :func:`~kornia.geometry.conversions.rotation_matrix_to_axis_angle`.",
"kornia.geometry.conversions.rotation_matrix_to_axis_angle",
),
("Alias of :py:func:`foo`.\n\nMore text.", "foo"),
(
"Deprecated: use :func:`~kornia.geometry.conversions.axis_angle_to_quaternion`.",
"kornia.geometry.conversions.axis_angle_to_quaternion",
),
("Deprecated: use :class:`kornia.geometry.boxes.Boxes`.", "kornia.geometry.boxes.Boxes"),
("Deprecated: use :py:meth:`Foo.bar`.\n\nIt warns on every call.", "Foo.bar"),
],
)
def test_status_target_accepts_a_status_title(doc, target):
assert status_target(doc) == target
def test_is_deprecated_wrapper_recognises_the_decorator():
from kornia.core._compat import deprecated
def plain():
return 1
class Plain:
def __init__(self) -> None:
pass
wrapped = deprecated(replace_with="plain", version="0.1")(plain)
wrapped_class = deprecated(replace_with="Plain", version="0.1")(type("Old", (Plain,), {}))
assert is_deprecated_wrapper(wrapped)
assert is_deprecated_wrapper(wrapped_class)
assert not is_deprecated_wrapper(plain)
assert not is_deprecated_wrapper(Plain)
@pytest.mark.parametrize(
"doc",
[
"Alias of :func:`foo`",
"Alias of :func:`foo` with a twist.",
"Alias of :func:`foo` and :func:`bar`.",
"Alias for :func:`foo`.",
"Return the thing.\nAlias of :func:`foo`.",
"Alias of foo.",
"",
"Deprecated, use :func:`foo`.",
"Deprecated: use foo.",
"Deprecated: use :func:`foo`",
"Deprecated: use :func:`foo` instead.",
"Deprecated: use :func:`foo` or :func:`bar`.",
"Deprecated: Use :func:`foo`.",
"Deprecated since 0.7.0: use :func:`foo`.",
"Return the thing.\nDeprecated: use :func:`foo`.",
"Deprecated: use :math:`foo`.",
],
)
def test_status_target_rejects_other_titles(doc):
assert status_target(doc) is None
def test_undocumented_public_objects_complements_public_objects():
documented, undocumented = public_objects(), undocumented_public_objects()
assert not documented.keys() & undocumented.keys()
assert all(own_docstring(obj) is None for obj, _ in undocumented.values())
def test_public_and_undocumented_objects_split_the_export_walk(monkeypatch):
# kornia may export nothing undocumented, so the split is checked on a synthetic walk. ``__wrapped__`` calls the
# functions past their own ``functools.cache``, which the patched walk would otherwise never reach.
def undocumented():
pass
def documented():
"""Do the thing."""
walk = ((undocumented, "m.undocumented"), (documented, "m.documented"))
monkeypatch.setattr(docstring_style, "_exported_objects", lambda: walk)
assert [qualified for _, qualified in undocumented_public_objects.__wrapped__().values()] == ["m.undocumented"]
assert [qualified for _, qualified in public_objects.__wrapped__().values()] == ["m.documented"]
class _Converted:
"""A converted class."""
#: The size, see :class:`_Converted`.
size = 1
bare = 2
#: First line, see :class:`_Converted`.
#: Second line.
block = 3
trailing = 4 #: Trailing, see :attr:`size`.
literal = 5
"""A string after the assignment,
on two lines."""
def method(self):
"""Do it, like :meth:`other`."""
@property
def prop(self):
"""Read it."""
def silent(self):
pass
class _Unconverted:
"""Another class."""
def method(self):
"""Not wanted."""
def test_documented_members_returns_the_registered_members_of_the_classes():
registry = {
"m.Converted": _Converted,
"m.Converted.method": _Converted.method,
"m.Converted.prop": _Converted.prop,
"m.Converted.size": _Attribute(_Converted, "size"),
"m.Converted.block": _Attribute(_Converted, "block"),
"m.Converted.trailing": _Attribute(_Converted, "trailing"),
"m.Converted.literal": _Attribute(_Converted, "literal"),
"m.Converted.silent": _Converted.silent,
"m.Converted.bare": _Attribute(_Converted, "bare"),
"m.Unconverted": _Unconverted,
"m.Unconverted.method": _Unconverted.method,
"m.function": _alias_target,
}
members = documented_members(registry, [_Converted])
assert members == {
"m.Converted.method": (_Converted.method, "Do it, like :meth:`other`."),
"m.Converted.prop": (_Converted.prop, "Read it."),
"m.Converted.size": (registry["m.Converted.size"], "The size, see :class:`_Converted`."),
"m.Converted.block": (
registry["m.Converted.block"],
"First line, see :class:`_Converted`.\nSecond line.",
),
"m.Converted.trailing": (registry["m.Converted.trailing"], "Trailing, see :attr:`size`."),
"m.Converted.literal": (registry["m.Converted.literal"], "A string after the assignment,\non two lines."),
}
assert documented_members(registry, []) == {}
def test_documented_members_reads_a_member_under_every_class_that_registers_it():
registry = {"a.Converted": _Converted, "b.Converted": _Converted}
registry |= {"a.Converted.prop": _Converted.prop, "b.Converted.prop": _Converted.prop}
assert set(documented_members(registry, [_Converted])) == {"a.Converted.prop", "b.Converted.prop"}
class _ClassMethodBase:
@classmethod
def build(cls):
"""Build one, see :meth:`other`."""
class _ClassMethodOverride(_ClassMethodBase):
@classmethod
def build(cls):
return cls()
def test_documented_members_reads_the_inherited_docstring_of_a_class_method_override():
# The registry holds a class method as its ``__func__``, on which ``inspect.getdoc`` finds no inherited docstring.
# autodoc renders the base's, so its references must be checked as well.
build = vars(_ClassMethodOverride)["build"].__func__
registry = {"m.Override": _ClassMethodOverride, "m.Override.build": build}
assert documented_members(registry, [_ClassMethodOverride]) == {
"m.Override.build": (build, "Build one, see :meth:`other`.")
}
class _SharedBase:
def method(self):
"""Run it, then :meth:`other`, as :func:`helper` does."""
class _SharedA(_SharedBase):
def other(self):
"""The other one."""
class _SharedB(_SharedBase):
pass
def _helper():
"""Help."""
def test_member_registered_under_several_classes_resolves_in_each_registration_only():
# One method rendered on two class pages, as an inherited ``forward`` is: Sphinx resolves its references once per
# rendered entry, under that entry's class and module, so a short name registered only for ``a.A`` links there
# and stays plain text on the ``b.B`` page.
registry = {
"a.A": _SharedA,
"a.A.method": _SharedBase.method,
"a.A.other": _SharedA.other,
"a.helper": _helper,
"b.B": _SharedB,
"b.B.method": _SharedBase.method,
}
method = _SharedBase.method
for target, expected in (("other", _SharedA.other), ("helper", _helper)):
assert resolve_reference(method, target, registry, registered_as="a.A.method") is expected, target
assert reference_resolves(method, target, registry, registered_as="a.A.method"), target
assert resolve_reference(method, target, registry, registered_as="b.B.method") is None, target
assert not reference_resolves(method, target, registry, registered_as="b.B.method"), target
# Without a registered name the scopes of every registration count, as for a top-level object.
assert resolve_reference(method, target, registry) is expected, target
assert resolve_reference(method, "a.A.other", registry, registered_as="b.B.method") is _SharedA.other
with pytest.raises(ValueError, match="does not register"):
resolve_reference(method, "other", registry, registered_as="a.A.other")
def _alias_target(a, b=1, *args, c=2, **kwargs):
return a
def _forwarding_alias(a, b=1, *args, c=2, **kwargs):
"""Alias of :func:`_alias_target`."""
return _alias_target(a, b, *args, c=c, **kwargs)
def _keyword_alias(a, b=1):
"""Alias of :func:`_alias_target`."""
return _alias_target(a, b=b)
class _AliasTargetClass:
pass
class _AliasClass(_AliasTargetClass):
"""Alias of :class:`_AliasTargetClass`."""
class _SubclassWithBody(_AliasTargetClass):
"""Alias of :class:`_AliasTargetClass`."""
def extra(self):
return 1
class _TwoBases(_AliasTargetClass, Exception):
"""Alias of :class:`_AliasTargetClass`."""
def _swapped(a, b):
return _alias_target(b, a)
def _constant_argument(a):
return _alias_target(a, 2)
def _extra_statement(a):
a = a + 1
return _alias_target(a)
def _dropped_argument(a, b=1):
return _alias_target(a)
def _renamed_keyword(a, b=1):
return _alias_target(a, c=b)
def _other_target(a):
return _keyword_alias(a)
@functools.lru_cache
def _decorated(a):
return _alias_target(a)
def _renamed_positional(x, y=1):
return _alias_target(x, y)
def _required_where_target_defaults(a, b):
return _alias_target(a, b)
def _changed_default(a, b=5):
return _alias_target(a, b)
def _renamed_positional_changed_default(x, y=3):
return _alias_target(x, y)
def _defaulted_where_target_requires(a=0):
return _alias_target(a)
def _keyword_changed_default(a, c=9):
return _alias_target(a, c=c)
def _default_into_target_kwargs(a, d=1):
return _alias_target(a, d=d)
@pytest.mark.parametrize(
("obj", "target"),
[
(_forwarding_alias, _alias_target),
(_keyword_alias, _alias_target),
(_AliasClass, _AliasTargetClass),
# positional parameters reach the target by position, so their names may differ
(_renamed_positional, _alias_target),
# an alias may require what the target defaults: every call it accepts still behaves as the target
(_required_where_target_defaults, _alias_target),
],
)
def test_forwards_to_accepts_a_forwarding_alias(obj, target):
assert forwards_to(obj, target)
def test_forwards_to_resolves_a_target_from_the_closure():
def local_target(x):
return x
def local_alias(x):
"""Alias of the local target."""
return local_target(x)
assert forwards_to(local_alias, local_target)
@pytest.mark.parametrize(
("obj", "target"),
[
(_swapped, _alias_target),
(_constant_argument, _alias_target),
(_extra_statement, _alias_target),
(_dropped_argument, _alias_target),
(_renamed_keyword, _alias_target),
(_other_target, _alias_target),
(_decorated, _alias_target),
# a default that differs from the target's changes what a call relying on it returns
(_changed_default, _alias_target),
(_renamed_positional_changed_default, _alias_target),
(_keyword_changed_default, _alias_target),
(_defaulted_where_target_requires, _alias_target),
(_default_into_target_kwargs, _alias_target),
(_SubclassWithBody, _AliasTargetClass),
(_TwoBases, _AliasTargetClass),
(_AliasClass, object),
(len, _alias_target),
],
)
def test_forwards_to_rejects_anything_else(obj, target):
assert not forwards_to(obj, target)
def test_forwards_to_rejects_a_live_function_titled_alias_of_another():
# The mutant the status-title check used to accept: give a live converted function the title
# "Alias of :func:`~kornia.geometry.conversions.rotation_matrix_to_quaternion`." and it skipped its See Also,
# although it computes something else entirely.
from kornia.geometry.conversions import axis_angle_to_quaternion, rotation_matrix_to_quaternion
title = "Alias of :func:`~kornia.geometry.conversions.rotation_matrix_to_quaternion`."
assert status_target(title) == "kornia.geometry.conversions.rotation_matrix_to_quaternion"
assert not forwards_to(axis_angle_to_quaternion, rotation_matrix_to_quaternion)
class _OnlyDocumented:
"""A kornia class that a docs page registers and no ``__all__`` exports."""
def method(self):
"""A registered method, not a top-level object."""
def _undocumented_only():
pass
def test_rollout_objects_union_exported_and_documented_objects(monkeypatch):
# Only kornia-defined classes count, so give the synthetic class a kornia ``__module__``.
monkeypatch.setattr(_OnlyDocumented, "__module__", "kornia.synthetic", raising=False)
monkeypatch.setattr(_OnlyDocumented.method, "__module__", "kornia.synthetic")
monkeypatch.setattr(_undocumented_only, "__module__", "kornia.synthetic")
exported = ((depth_to_3d, "kornia.geometry.depth.depth_to_3d"),)
monkeypatch.setattr(docstring_style, "_exported_objects", lambda: exported)
registry = {
"kornia.synthetic": docstring_style,
"kornia.synthetic.OnlyDocumented": _OnlyDocumented,
"kornia.synthetic.OnlyDocumented.method": _OnlyDocumented.method,
"kornia.geometry.depth.depth_to_3d": depth_to_3d,
"kornia.synthetic.alias_of_depth_to_3d": depth_to_3d,
"kornia.synthetic.not_kornia": inspect.getdoc,
"kornia.synthetic._undocumented_only": _undocumented_only,
}
selected = rollout_objects(registry)
names = sorted(qualified for _, qualified in selected.values())
assert names == ["kornia.geometry.depth.depth_to_3d", "kornia.synthetic._OnlyDocumented"]
assert id(_OnlyDocumented.method) not in selected
assert [q for _, q in rollout_objects(registry, with_docstring=False).values()] == [
"kornia.synthetic._undocumented_only"
]
# One object registered under two names is one entry of the documented walk.
assert [q for _, q in docstring_style.documented_objects(registry)].count("kornia.geometry.depth.depth_to_3d") == 1