Every public type in typing.py is documented or intentionally undocumented.
()
| 38 | |
| 39 | |
| 40 | def test_typing_aliases_documented(): |
| 41 | """Every public type in typing.py is documented or intentionally undocumented.""" |
| 42 | typing_docs = Path(__file__).parents[3] / "doc/api/typing_api.rst" |
| 43 | if not typing_docs.exists(): |
| 44 | pytest.skip("Documentation sources not available") |
| 45 | |
| 46 | typing_py_path = Path(__file__).parents[1] / "typing.py" |
| 47 | assert typing_py_path.exists(), f"{typing_py_path} does not exist" |
| 48 | tree = ast.parse(typing_py_path.read_text(encoding="utf-8")) |
| 49 | |
| 50 | # Collect all public module-level assignment names (both annotated and plain). |
| 51 | defined_types = set() |
| 52 | for node in ast.iter_child_nodes(tree): |
| 53 | if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name): |
| 54 | name = node.target.id |
| 55 | elif isinstance(node, ast.Assign) and len(node.targets) == 1: |
| 56 | target = node.targets[0] |
| 57 | name = target.id if isinstance(target, ast.Name) else None |
| 58 | else: |
| 59 | continue |
| 60 | if name is not None and not name.startswith("_"): |
| 61 | defined_types.add(name) |
| 62 | |
| 63 | assert defined_types, "No type definitions found in typing.py" |
| 64 | |
| 65 | # Collect documented ``.. autodata::`` entries. |
| 66 | rst_content = typing_docs.read_text(encoding="utf-8") |
| 67 | documented = set( |
| 68 | re.findall( |
| 69 | r"^\.\.\s+autodata::\s+matplotlib\.typing\.(\w+)", |
| 70 | rst_content, |
| 71 | re.MULTILINE, |
| 72 | ) |
| 73 | ) |
| 74 | assert documented, "No autodata entries found in typing_api.rst" |
| 75 | |
| 76 | # Collect types listed under the comment |
| 77 | # ".. intentionally undocumented types (one type per row)". |
| 78 | # Each type must be indented and an empty line ends the section. |
| 79 | intentionally_undocumented = set() |
| 80 | marker = ".. intentionally undocumented types (one type per row)" |
| 81 | lines_following_marker = rst_content.split(marker, 1)[1].splitlines()[1:] |
| 82 | for line in lines_following_marker: |
| 83 | if not line or not line[0].isspace(): |
| 84 | break |
| 85 | intentionally_undocumented.add(line.strip()) |
| 86 | |
| 87 | accounted_for = documented | intentionally_undocumented |
| 88 | |
| 89 | missing = defined_types - accounted_for |
| 90 | assert not missing, ( |
| 91 | f"Types defined in typing.py but not in typing_api.rst " |
| 92 | f"(document them or add to 'intentionally undocumented types'): {missing}" |
| 93 | ) |
| 94 | |
| 95 | extra = accounted_for - defined_types |
| 96 | assert not extra, ( |
| 97 | f"Types listed in typing_api.rst but not defined in typing.py: {extra}" |