API¶

@pytest.fixture
def command_calls_function(
    mocker: MockerFixture,
) -> Callable[[FunctionType, FunctionType, Iterable[str]], bool]:
    """Return a callable that verifies a CLI command delegates to a function.

    The returned callable registers `cmd` on a freshly built CLI app, patches
    `function` where it is defined, invokes `cmd` through the CLI with
    `args`, and reports whether the patch was called exactly once. Whether
    the invocation itself succeeds is not checked.
    Adds a second dummy command to prevent the only one command from being treated
    as the default command.

    Args:
        mocker: pytest-mock fixture used to patch `function`.

    Returns:
        A callable `(cmd, function, args) -> bool` that returns `True` if
        `function` is called exactly once while `cmd` runs with `args`,
        `False` otherwise.
    """

    def check(
        cmd: FunctionType,
        function: FunctionType,
        args: Iterable[str],
    ) -> bool:
        """Run `cmd` with `args`; return whether `function` was called exactly once."""
        mock = mocker.patch(function.__module__ + "." + function.__name__)
        app = typer.Typer(name="some-app", no_args_is_help=True)
        app.command()(lambda: None)
        app.command()(cmd)
        CliRunner().invoke(app, [snake_to_kebab_case(cmd.__name__), *(args or [])])
        return mock.call_count == 1

    return check

@pytest.fixture
def command_works() -> Callable[[FunctionType], bool]:
    """Return a callable that verifies a CLI command is registered and reachable.

    The returned callable runs `cmd` as a subcommand of the project's CLI
    with `--help` and checks whether its kebab-case name appears in stdout.

    Returns:
        A callable `(cmd) -> bool` that returns `True` if `cmd`'s kebab-case
        name appears in the `--help` output, `False` otherwise.

    Raises:
        subprocess.CalledProcessError: If invoking `cmd` with `--help` exits
            with a non-zero status, for example because `cmd` is not
            registered as a subcommand of the project's CLI.
    """

    def check(cmd: FunctionType) -> bool:
        """Run `cmd` with `--help` and return whether its name appears in stdout."""
        args = Args(
            PackageManager.I.project_name(),
            snake_to_kebab_case(cmd.__name__),
            "--help",
        )
        completed_process = args.run()
        stdout = completed_process.stdout
        name = cmd.__name__.replace("_", "-")
        return name in stdout

    return check

@pytest.fixture
def config_file_factory[T: ConfigFile[dict[str, Any] | list[Any]]](
    tmp_path: Path,
) -> Callable[[type[T]], type[T]]:
    """Return a factory that wraps a `ConfigFile` subclass for isolated testing.

    Each call to the factory dynamically creates a new wrapping subclass, so
    it may be invoked with a different `ConfigFile` subclass any number of
    times within the same test.

    Args:
        tmp_path: Pytest's per-test temporary directory.

    Returns:
        A callable `(base_class) -> type[T]` that wraps `base_class` in a
        subclass whose file operations are redirected to `tmp_path`.
    """

    def _make_test_config(
        base_class: type[T],
    ) -> type[T]:
        """Wrap `base_class` with `tmp_path`-redirected file operations.

        Args:
            base_class: The `ConfigFile` subclass to wrap.

        Returns:
            A subclass of `base_class` with all file paths redirected to
            `tmp_path`.
        """

        class TestConfigFile(base_class):  # ty: ignore[unsupported-base]
            """Subclass of `base_class` with every file operation under `tmp_path`."""

            def _dump(self, configs: dict[str, Any] | list[Any]) -> None:
                """Write the config from within `tmp_path`, isolating real files."""
                with chdir(tmp_path):
                    super()._dump(configs)

            def _load(self) -> dict[str, Any] | list[Any]:
                """Load the config from within `tmp_path`, isolating real files."""
                with chdir(tmp_path):
                    return super()._load()

            def create_file(self) -> None:
                """Create the file from within `tmp_path`, isolating real files."""
                with chdir(tmp_path):
                    super().create_file()

            def path(self) -> Path:
                """Return the config file path, rooted under `tmp_path`.

                Returns:
                    The parent implementation's path unchanged if it already
                    resolves under `tmp_path` (as when called while the
                    working directory is `tmp_path`); otherwise that path
                    joined onto `tmp_path`.
                """
                path = super().path()
                if not (path.is_relative_to(tmp_path) or Path.cwd() == tmp_path):
                    path = tmp_path / path
                return path

        return TestConfigFile  # ty:ignore[invalid-return-type]

    return _make_test_config

@pytest.fixture(scope="session")
def on_latest_python_version(on_python_version: Callable[[str], bool]) -> bool:
    """Return whether the running Python version matches the latest stable release.

    Args:
        on_python_version: Callable that checks whether a given version string
            exactly matches the running Python version.

    Returns:
        True if the current Python micro version matches the latest stable
        release.
    """
    latest_version = PyprojectConfigFile.I.latest_python_version("micro")
    return on_python_version(str(latest_version))

@pytest.fixture(scope="session")
def on_linux(on_platform: Callable[[str], bool]) -> bool:
    """Return whether the current system is Linux.

    Args:
        on_platform: Callable that checks whether a given platform name
            exactly matches the current system platform.

    Returns:
        True if the system is Linux.
    """
    return on_platform("Linux")

@pytest.fixture(scope="session")
def on_linux_and_latest_python_version(
    *,
    on_linux: bool,
    on_latest_python_version: bool,
) -> bool:
    """Return whether the current environment is Linux with the latest Python version.

    Args:
        on_linux: Whether the current system is Linux.
        on_latest_python_version: Whether the running Python version matches
            the latest stable release.

    Returns:
        True if both conditions are met.
    """
    return on_linux and on_latest_python_version

@pytest.fixture(scope="session")
def on_linux_and_latest_python_version_or_not_in_ci(
    *,
    on_linux_and_latest_python_version: bool,
) -> bool:
    """Return whether tests that require a canonical environment should run.

    Args:
        on_linux_and_latest_python_version: Whether the environment is Linux
            with the latest Python version.

    Returns:
        True if the environment is Linux with the latest Python version, or
        if not currently running inside GitHub Actions.
    """
    return (
        on_linux_and_latest_python_version
    ) or not RemoteVersionController.I.running_in_ci()

@pytest.fixture(scope="session")
def on_platform() -> Callable[[str], bool]:
    """Check whether the current system platform exactly matches a given name.

    Returns:
        A callable `(platform_name) -> bool` that returns `True` only when
        `platform_name` exactly equals `platform.system()` (e.g., `"Linux"`,
        `"Windows"`, `"Darwin"`).
    """

    def check(platform_name: str) -> bool:
        return platform.system() == platform_name

    return check

@pytest.fixture(scope="session")
def on_python_version() -> Callable[[str], bool]:
    """Check whether the current Python version exactly matches a given version string.

    Returns:
        A callable `(version) -> bool` that returns `True` only when `version`
        exactly equals `platform.python_version()` (e.g., `"3.13.2"`).
    """

    def check(version: str) -> bool:
        return platform.python_version() == version

    return check

def claim_file(tmp_path_factory: pytest.TempPathFactory, stem: str) -> bool:
    """Try to exclusively claim a `<stem>.claimed` marker file.

    Every pytest-xdist worker's own base temp dir is `<root>/<worker_id>`,
    so `<root>` is the same shared path in every worker regardless of how
    many exist or how tests get distributed among them. Creating the marker
    there via `Path.touch(exist_ok=False)` is atomic on every platform
    pytest supports, so exactly one caller across all workers ever wins the
    race.

    Args:
        tmp_path_factory: Used to locate the shared `<root>` dir.
        stem: Distinguishes this claim from any other's marker file.

    Returns:
        `True` for the one caller that wins the race, `False` for every
        other caller.
    """
    marker = tmp_path_factory.getbasetemp().parent / f"{stem}.claimed"
    try:
        marker.touch(exist_ok=False)
    except FileExistsError:
        return False
    return True

@pytest.fixture(scope="session", autouse=True)
def init_pyrig_project(
    request: pytest.FixtureRequest,
    tmp_path_factory: pytest.TempPathFactory,
) -> tuple[bool, str]:
    """Verify that this project can be built and adopted by a fresh consumer project.

    Delegates the actual build, install, and verification flow to
    [run_init_pyrig_project][], once per test session, in an isolated
    temporary directory. Skipped when `--skip-init-pyrig-project` is
    passed.

    Under pytest-xdist, every worker process would otherwise repeat this
    expensive flow independently. [claim_file][] elects a single winner,
    across however many worker processes exist, to run it for real; outside
    of pytest-xdist there's only one process, so it always wins trivially.

    Args:
        request: Used to read the `--skip-init-pyrig-project` option.
        tmp_path_factory: Used to locate the shared dir to race for the
            claim in.

    Returns:
        A tuple of `(success, message)`, where `success` is always `True`
        since a failed check raises instead of returning. `message`
        explains why the run was skipped, or is empty when it ran and
        succeeded.

    Raises:
        pytest.fail.Exception: If the check does not succeed.

    Note:
        Being autouse and session-scoped, a failed check reports a setup
        error for every test in the session, not just one. Under
        pytest-xdist, that only holds for the winning worker's own tests,
        since it's the only one that actually runs the check — the other
        workers' tests are unaffected either way, but the run as a whole
        still fails since the winner's tests do.
    """
    if request.config.getoption(SKIP_INIT_PYRIG_PROJECT_FLAG):
        return True, f"Skipped via {SKIP_INIT_PYRIG_PROJECT_FLAG}"

    if not claim_file(tmp_path_factory, init_pyrig_project.__name__):
        return True, "Skipped: another worker already claimed this check"

    with (
        TemporaryDirectory() as tmp_dir,
        pytest.MonkeyPatch.context() as monkeypatch,
    ):
        success, msg = run_init_pyrig_project(Path(tmp_dir), monkeypatch)

    if not success:
        pytest.fail(f"Failed to initialize pyrig project: {msg}")
    return success, msg

def pytest_addoption(parser: pytest.Parser) -> None:
    """Register the `--skip-init-pyrig-project` command-line flag.

    The flag lets a run opt out of the expensive [init_pyrig_project][]
    fixture that every project depending on pyrig-fixtures otherwise runs
    once per test session, e.g. for a fast local feedback loop.

    A true single-dash short form (e.g. `-sipp`) isn't possible: pytest
    reserves lowercase single-dash options for its own core and rejects
    them from plugins, so `--sipp` is offered as the short alias instead.

    Args:
        parser: Pytest's parser to register the command-line option on.
    """
    parser.addoption(
        SKIP_INIT_PYRIG_PROJECT_FLAG,
        SKIP_INIT_PYRIG_PROJECT_SHORT_FLAG,
        action="store_true",
        default=False,
        help="Skip the slow `init_pyrig_project` end-to-end fixture.",
    )

def run_init_pyrig_project(  # noqa: PLR0915
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> tuple[bool, str]:
    """Build this project and verify a fresh consumer project can adopt it.

    Packages the current project as a wheel and scaffolds a brand-new
    project under `tmp_path`, adding the wheel plus every other
    currently-installed plugin that depends on pyrig-runtime as dev
    dependencies. Runs `pyrig init` in the new project, then checks that
    its own test suite fails as expected, that its CLI and `version`
    command produce the expected output, that the expected package
    directory was generated, and that every `ConfigFile` subclass
    produced its file. Finally runs `pyrigger --help` as a last sanity
    check.

    Kept as a standalone function, separate from [init_pyrig_project][],
    so tests can call it directly with mocked subprocess results to
    exercise each failure branch independently.

    Args:
        tmp_path: Scratch directory to scaffold the wheel-build copy of
            this project and the new consumer project under; must not
            already contain directories with their names.
        monkeypatch: Used to remove the current virtual environment from
            the environment for the duration of the run, so subprocess
            commands create and use their own fresh environment instead
            of reusing the caller's.

    Returns:
        A tuple of `(success, message)`. `success` is `True` only if
        every check above passes; `message` describes the first check
        that failed, or is empty when `success` is `True`.

    Raises:
        subprocess.CalledProcessError: If any underlying command fails,
            other than the new project's own test suite exiting as
            expected.
    """
    src_project_name = "src-project"

    pyrig_project_tmp_path = tmp_path / PackageManager.I.project_name()
    shutil.copytree(
        Path(),
        pyrig_project_tmp_path,
    )
    with chdir(pyrig_project_tmp_path):
        # remove a potential dist dir from a previous build
        dist_dir = pyrig_project_tmp_path / "dist"
        with suppress(FileNotFoundError):
            shutil.rmtree(dist_dir)
        # build the package
        args = PackageManager.I.build_args()
        args.run()

    dist_files = list((pyrig_project_tmp_path / "dist").glob("*.whl"))
    wheel_path = dist_files[-1].resolve().as_posix()

    src_project_dir = tmp_path / src_project_name
    src_project_dir.mkdir()

    # Get the current Python version in major.minor format
    python_version = str(PyprojectConfigFile.I.first_supported_python_version())

    with chdir(src_project_dir):
        # Strip VIRTUAL_ENV and the outer venv's bin dir from PATH so
        # subprocesses create a new virtual environment instead of reusing
        # the current one, and commands like `pyrig` from the dev environment
        # aren't found when testing that they're absent.
        venv = os.environ.get("VIRTUAL_ENV")
        monkeypatch.delenv("VIRTUAL_ENV", raising=False)
        if venv:
            path_entries = os.environ.get("PATH", "").split(os.pathsep)
            monkeypatch.setenv(
                "PATH",
                os.pathsep.join(
                    p for p in path_entries if not p.lower().startswith(venv.lower())
                ),
            )

        # Initialize git repo in the test project directory
        VersionController.I.init_args().run()
        VersionController.I.config_args(
            "--local",
            "user.email",
            "test@example.com",
        ).run()
        VersionController.I.config_args("--local", "user.name", "Test User").run()

        args = PackageManager.I.args("init", "--python", python_version)
        args.run()

        # Add pyrig wheel as a dev dependency and plugins
        plugins = tuple(
            snake_to_kebab_case(dep.__name__)
            for dep in dependent_packages(pyrig_runtime)
            # wheel path is the package name, so don't add it as a dependency twice
            if dep.__name__ != PackageManager.I.package_name()
        )

        # add plugins
        PackageManager.I.add_group_dev_args(wheel_path, *plugins).run()

        # uv add converts absolute paths to relative paths, which breaks when
        # the project is copied to a different location. We need to replace the
        # relative path with an absolute path.
        pyproject_toml = src_project_dir / "pyproject.toml"
        pyproject_content = pyproject_toml.read_text(encoding="utf-8")
        # Replace relative path with absolute path in tool.uv.sources
        # e.g., { path = "../pyrig/dist/..." }
        # -> { path = "/tmp/.../pyrig/dist/..." }
        pyproject_content = re.sub(
            r'pyrig = \{ path = "[^"]*" \}',
            f'pyrig = {{ path = "{wheel_path}" }}',
            pyproject_content,
        )
        pyproject_toml.write_text(pyproject_content, encoding="utf-8")

        # Sync to update the lock file with the new absolute path
        args = PackageManager.I.install_dependencies_args()
        args.run()

        # Verify pyrig was installed correctly
        # also checks if the init process works
        PackageManager.I.run_args(*Pyrigger.I.cmd_args(cmd=init)).run()

        # with cov
        args = PackageManager.I.run_args(*ProjectTester.I.test_args())
        res = args.run(check=False)
        if res.returncode != pytest.ExitCode.TESTS_FAILED:
            return False, f"Expected tests to fail, got return code {res.returncode}"

        # assert the packages own cli is available
        args = PackageManager.I.run_args(src_project_name, "--help")
        res = args.run()
        stdout = res.stdout
        expected = src_project_name
        if expected not in stdout.lower():
            return (
                False,
                "Expected the projects CLI to work and find the project name in stdout",
            )

        # assert calling version works
        args = PackageManager.I.run_args(src_project_name, version.__name__)
        res = args.run()
        stdout = res.stdout
        expected = f"{src_project_name} 0.1.0"
        if expected not in stdout:
            return (
                False,
                f"Expected the projects version command to output '{expected}'",
            )

        package_dir = src_project_dir / "src" / kebab_to_snake_case(src_project_name)
        if not package_dir.exists():
            return (
                False,
                f"Expected package directory {package_dir} to exist after init",
            )

        for cf in ConfigFile.concrete_leaves():
            if not cf().path().exists():
                return (
                    False,
                    f"Expected config file {cf().path()} to exist after init",
                )

        PackageManager.I.run_args(*Pyrigger.I.args("--help")).run()

    return True, ""

@pytest.fixture
def create_module() -> Callable[[Path], ModuleType]:
    """Return a callable that creates and imports an empty Python module.

    Returns:
        A callable that creates an empty module file and imports it,
        initializing any missing parent directories as a package hierarchy
        first.
    """

    def create(path: Path) -> ModuleType:
        """Create an empty module file at `path` and import it.

        Args:
            path: Path to the module file, relative to the current working
                directory. Missing parent directories are created and given
                `__init__.py` files up to the current working directory.
                The imported module's dotted name is derived from this path.

        Returns:
            The imported module, empty of any definitions.
        """
        make_package_dir(path.parent, root=Path(), content="")
        path.touch()
        return import_module_with_file_fallback(path, name=path_as_module_name(path))

    return create

@pytest.fixture
def create_package() -> Callable[[Path], ModuleType]:
    """Return a callable that creates and imports an empty Python package.

    Returns:
        A callable that creates a directory tree as an empty package
        hierarchy and imports the deepest package.
    """

    def create(path: Path) -> ModuleType:
        """Create an empty package directory at `path` and import it.

        Args:
            path: Path to the package directory, relative to the current
                working directory. `path` and every ancestor directory up to
                the current working directory are created and given
                `__init__.py` files. The imported package's dotted name is
                derived from this path.

        Returns:
            The imported package, empty of any definitions.
        """
        make_package_dir(path, root=Path(), content="")
        return import_module_with_file_fallback(path, name=path_as_module_name(path))

    return create

@pytest.fixture
def create_source_package(
    tmp_source_root_path: Path,
    create_package: Callable[[Path], ModuleType],
) -> Callable[[Path], ModuleType]:
    """Return a callable that creates and imports a package under the source root.

    Args:
        tmp_source_root_path: Temporary source root directory that paths
            passed to the returned callable are resolved against.
        create_package: Fixture that creates and imports a package.

    Returns:
        A callable that creates an empty package under the temporary source
        root and imports it.
    """

    def create(path: Path) -> ModuleType:
        """Create an empty package at `path` under the source root and import it.

        Args:
            path: Path to the package directory, relative to the temporary
                source root directory.

        Returns:
            The imported package, empty of any definitions.
        """
        with chdir(tmp_source_root_path):
            return create_package(path)

    return create

@pytest.fixture
def tmp_package_root_path(
    tmp_project_root_path: Path,
    tmp_source_root_path: Path,
    create_source_package: Callable[[Path], ModuleType],
) -> tuple[Path, ModuleType]:
    """Provide the temporary package root, already created and imported as a package.

    Args:
        tmp_project_root_path: Temporary project root directory.
        tmp_source_root_path: Temporary source root directory.
        create_source_package: Callable that creates and imports a package at
            a path relative to the temporary source root.

    Returns:
        Tuple of `(path, package)`: the package root directory nested inside
        the temporary source root, and its imported package module.
    """
    path = tmp_project_root_path / PackageManager.I.package_root()

    package = create_source_package(path.relative_to(tmp_source_root_path))
    return path, package

@pytest.fixture
def tmp_project_root_path(tmp_path: Path) -> Path:
    """Provide a temporary project root directory named after the current project.

    Args:
        tmp_path: Pytest's per-test temporary directory.

    Returns:
        Path to the temporary project root directory, already created on disk.
    """
    path = tmp_path / PackageManager.I.project_name()
    path.mkdir()
    return path

@pytest.fixture
def tmp_source_root_path(tmp_project_root_path: Path) -> Path:
    """Provide a temporary source root directory nested inside the project root.

    Args:
        tmp_project_root_path: Temporary project root directory.

    Returns:
        Path to the temporary source root directory, already created on disk.
    """
    path = tmp_project_root_path / PackageManager.I.source_root()
    path.mkdir()
    return path