Coverage for tests/test_api.py: 91.47%
97 statements
« prev ^ index » next coverage.py v7.10.6, created at 2025-09-05 17:55 +0200
« prev ^ index » next coverage.py v7.10.6, created at 2025-09-05 17:55 +0200
1"""Tests for our own API exposition."""
3from __future__ import annotations
5from collections import defaultdict
6from pathlib import Path
7from typing import TYPE_CHECKING
9import griffe
10import pytest
11from mkdocstrings import Inventory
13import griffe_pydantic
15if TYPE_CHECKING:
16 from collections.abc import Iterator
19@pytest.fixture(name="loader", scope="module")
20def _fixture_loader() -> griffe.GriffeLoader:
21 loader = griffe.GriffeLoader()
22 loader.load("griffe_pydantic")
23 loader.resolve_aliases()
24 return loader
27@pytest.fixture(name="internal_api", scope="module")
28def _fixture_internal_api(loader: griffe.GriffeLoader) -> griffe.Module:
29 return loader.modules_collection["griffe_pydantic._internal"]
32@pytest.fixture(name="public_api", scope="module")
33def _fixture_public_api(loader: griffe.GriffeLoader) -> griffe.Module:
34 return loader.modules_collection["griffe_pydantic"]
37def _yield_public_objects(
38 obj: griffe.Module | griffe.Class,
39 *,
40 modules: bool = False,
41 modulelevel: bool = True,
42 inherited: bool = False,
43 special: bool = False,
44) -> Iterator[griffe.Object | griffe.Alias]:
45 for member in obj.all_members.values() if inherited else obj.members.values():
46 try:
47 if member.is_module:
48 if member.is_alias or not member.is_public:
49 continue
50 if modules: 50 ↛ 51line 50 didn't jump to line 51 because the condition on line 50 was never true
51 yield member
52 yield from _yield_public_objects(
53 member, # type: ignore[arg-type]
54 modules=modules,
55 modulelevel=modulelevel,
56 inherited=inherited,
57 special=special,
58 )
59 elif member.is_public and (special or not member.is_special):
60 yield member
61 else:
62 continue
63 if member.is_class and not modulelevel:
64 yield from _yield_public_objects(
65 member, # type: ignore[arg-type]
66 modules=modules,
67 modulelevel=False,
68 inherited=inherited,
69 special=special,
70 )
71 except (griffe.AliasResolutionError, griffe.CyclicAliasError):
72 continue
75@pytest.fixture(name="modulelevel_internal_objects", scope="module")
76def _fixture_modulelevel_internal_objects(internal_api: griffe.Module) -> list[griffe.Object | griffe.Alias]:
77 return list(_yield_public_objects(internal_api, modulelevel=True))
80@pytest.fixture(name="internal_objects", scope="module")
81def _fixture_internal_objects(internal_api: griffe.Module) -> list[griffe.Object | griffe.Alias]:
82 return list(_yield_public_objects(internal_api, modulelevel=False, special=True))
85@pytest.fixture(name="public_objects", scope="module")
86def _fixture_public_objects(public_api: griffe.Module) -> list[griffe.Object | griffe.Alias]:
87 return list(_yield_public_objects(public_api, modulelevel=False, inherited=True, special=True))
90@pytest.fixture(name="inventory", scope="module")
91def _fixture_inventory() -> Inventory:
92 inventory_file = Path(__file__).parent.parent / "site" / "objects.inv"
93 if not inventory_file.exists(): 93 ↛ 94line 93 didn't jump to line 94 because the condition on line 93 was never true
94 pytest.skip("The objects inventory is not available.") # ty: ignore[call-non-callable]
95 with inventory_file.open("rb") as file:
96 return Inventory.parse_sphinx(file)
99def test_exposed_objects(modulelevel_internal_objects: list[griffe.Object | griffe.Alias]) -> None:
100 """All public objects in the internal API are exposed under `griffe_pydantic`."""
101 not_exposed = [
102 obj.path
103 for obj in modulelevel_internal_objects
104 if obj.name not in griffe_pydantic.__all__ or not hasattr(griffe_pydantic, obj.name)
105 ]
106 assert not not_exposed, "Objects not exposed:\n" + "\n".join(sorted(not_exposed))
109def test_unique_names(modulelevel_internal_objects: list[griffe.Object | griffe.Alias]) -> None:
110 """All internal objects have unique names."""
111 names_to_paths = defaultdict(list)
112 for obj in modulelevel_internal_objects:
113 names_to_paths[obj.name].append(obj.path)
114 non_unique = [paths for paths in names_to_paths.values() if len(paths) > 1]
115 assert not non_unique, "Non-unique names:\n" + "\n".join(str(paths) for paths in non_unique)
118def test_single_locations(public_api: griffe.Module) -> None:
119 """All objects have a single public location."""
121 def _public_path(obj: griffe.Object | griffe.Alias) -> bool:
122 return obj.is_public and (obj.parent is None or _public_path(obj.parent))
124 multiple_locations = {}
125 for obj_name in griffe_pydantic.__all__:
126 obj = public_api[obj_name]
127 if obj.aliases and ( 127 ↛ 130line 127 didn't jump to line 130 because the condition on line 127 was never true
128 public_aliases := [path for path, alias in obj.aliases.items() if path != obj.path and _public_path(alias)]
129 ):
130 multiple_locations[obj.path] = public_aliases
131 assert not multiple_locations, "Multiple public locations:\n" + "\n".join(
132 f"{path}: {aliases}" for path, aliases in multiple_locations.items()
133 )
136def test_api_matches_inventory(inventory: Inventory, public_objects: list[griffe.Object | griffe.Alias]) -> None:
137 """All public objects are added to the inventory."""
138 ignore_names = {"__getattr__", "__init__", "__repr__", "__str__", "__post_init__"}
139 not_in_inventory = [
140 f"{obj.relative_filepath}:{obj.lineno}: {obj.path}"
141 for obj in public_objects
142 if obj.name not in ignore_names and obj.path not in inventory
143 ]
144 msg = "Objects not in the inventory (try running `make run mkdocs build`):\n{paths}"
145 assert not not_in_inventory, msg.format(paths="\n".join(sorted(not_in_inventory)))
148def test_inventory_matches_api(
149 inventory: Inventory,
150 public_objects: list[griffe.Object | griffe.Alias],
151 loader: griffe.GriffeLoader,
152) -> None:
153 """The inventory doesn't contain any additional Python object."""
154 # YORE: Bump 2: Remove block.
155 ignore = ("model_ext", "model_noext")
156 ignore_paths = {
157 "griffe_pydantic.common",
158 "griffe_pydantic.extension",
159 "griffe_pydantic.dynamic",
160 "griffe_pydantic.static",
161 }
163 not_in_api = []
164 public_api_paths = {obj.path for obj in public_objects}
165 public_api_paths.add("griffe_pydantic")
166 for item in inventory.values():
167 # YORE: Bump 2: Remove block.
168 if item.name.startswith(ignore) or item.name in ignore_paths:
169 continue
171 if ( 171 ↛ 166line 171 didn't jump to line 166 because the condition on line 171 was always true
172 item.domain == "py"
173 and "(" not in item.name
174 and (item.name == "griffe_pydantic" or item.name.startswith("griffe_pydantic."))
175 ):
176 obj = loader.modules_collection[item.name]
177 if obj.path not in public_api_paths and not any(path in public_api_paths for path in obj.aliases): 177 ↛ 178line 177 didn't jump to line 178 because the condition on line 177 was never true
178 not_in_api.append(item.name)
179 msg = "Inventory objects not in public API (try running `make run mkdocs build`):\n{paths}"
180 assert not not_in_api, msg.format(paths="\n".join(sorted(not_in_api)))
183def test_no_module_docstrings_in_internal_api(internal_api: griffe.Module) -> None:
184 """No module docstrings should be written in our internal API.
186 The reasoning is that docstrings are addressed to users of the public API,
187 but internal modules are not exposed to users, so they should not have docstrings.
188 """
190 def _modules(obj: griffe.Module) -> Iterator[griffe.Module]:
191 for member in obj.modules.values():
192 yield member
193 yield from _modules(member)
195 for obj in _modules(internal_api):
196 assert not obj.docstring