test_find_packages.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_docs/test_find_packages.py
 
"""
Purpose
-------
Validate the OI-426 recursive package discovery in
``oct.docs.oct_docs._find_packages``.
 
Responsibilities
----------------
- Confirm depth-1 and depth-2 cases continue to work (backward compat).
- Confirm depth-3+ cases now resolve (new capability).
- Confirm walker stops at the first ``__init__.py`` (autodoc handles descent).
- Confirm ``LINTER_EXCLUDE_DIRS`` / ``WILDCARD_EXCLUDE_DIRS`` are respected.
- Confirm the ``_MAX_PACKAGE_DEPTH`` safety cap prevents runaway walks.
- Confirm the explicit ``autodoc_modules`` override path is unchanged.
 
Diagnostics
-----------
Domain: DOCS-TESTS
L2: test lifecycle
L3: assertion details
L4: deep tracing
 
Contracts
---------
Inputs:  tmp_path pytest fixture
Outputs: pass/fail assertions
"""
 
from pathlib import Path
 
import pytest
 
from oct.docs.oct_docs import _find_packages, _MAX_PACKAGE_DEPTH
 
 
def _mkpkg(path: Path) -> None:
    path.mkdir(parents=True, exist_ok=True)
    (path / "__init__.py").write_text("", encoding="utf-8")
 
 
def test_find_packages_depth_1(tmp_path: Path) -> None:
    """Backward compat: a top-level package is discovered."""
    _mkpkg(tmp_path / "pkg")
 
    result = _find_packages(tmp_path, {})
 
    assert result == [("pkg", tmp_path / "pkg")]
 
 
def test_find_packages_depth_2_nested_project(tmp_path: Path) -> None:
    """Backward compat: ``oct/oct/__init__.py`` resolves to the inner dir."""
    inner = tmp_path / "oct" / "oct"
    _mkpkg(inner)
 
    result = _find_packages(tmp_path, {})
 
    assert result == [("oct", inner)]
 
 
def test_find_packages_depth_3_src_layout(tmp_path: Path) -> None:
    """New capability: ``src/mypkg/__init__.py`` is now discovered."""
    inner = tmp_path / "src" / "mypkg"
    _mkpkg(inner)
 
    result = _find_packages(tmp_path, {})
 
    assert result == [("mypkg", inner)]
 
 
def test_find_packages_stops_at_package(tmp_path: Path) -> None:
    """Subpackages under a discovered package must not be listed."""
    _mkpkg(tmp_path / "pkg")
    _mkpkg(tmp_path / "pkg" / "sub")
 
    result = _find_packages(tmp_path, {})
 
    assert result == [("pkg", tmp_path / "pkg")]
 
 
def test_find_packages_respects_exclusions(tmp_path: Path) -> None:
    """Hidden / excluded directories are skipped."""
    _mkpkg(tmp_path / ".git" / "fake")
    _mkpkg(tmp_path / "real")
 
    result = _find_packages(tmp_path, {})
 
    assert result == [("real", tmp_path / "real")]
 
 
def test_find_packages_max_depth_safety(tmp_path: Path) -> None:
    """A 15-deep empty tree returns [] and does not raise."""
    deep = tmp_path
    for i in range(15):
        deep = deep / f"level{i}"
    deep.mkdir(parents=True)
 
    result = _find_packages(tmp_path, {})
 
    assert result == []
    assert _MAX_PACKAGE_DEPTH == 10
 
 
def test_find_packages_autodoc_modules_override(tmp_path: Path) -> None:
    """Explicit ``autodoc_modules`` config bypasses the walker."""
    _mkpkg(tmp_path / "hidden")
    _mkpkg(tmp_path / "chosen")
 
    result = _find_packages(
        tmp_path, {"autodoc_modules": ["chosen"]},
    )
 
    assert result == [("chosen", tmp_path / "chosen")]
 
 
def test_find_packages_multiple_siblings(tmp_path: Path) -> None:
    """Multiple top-level packages are all discovered."""
    _mkpkg(tmp_path / "a")
    _mkpkg(tmp_path / "b")
    _mkpkg(tmp_path / "c")
 
    result = _find_packages(tmp_path, {})
    names = sorted(name for name, _ in result)
 
    assert names == ["a", "b", "c"]