oct.testing.discovery Namespace Reference

Classes
class	SinglePackage
class	DiscoveryResult

Functions
DiscoveryResult	discover (Path cwd, *, bool workspace=False, str|None package=None)
DiscoveryResult	_workspace_result (Path workspace_root, str|None package)
SinglePackage	walk_for_package (Path cwd)
str	_package_id_for (Path root, Path config_file)

Variables
str	MODE_WORKSPACE = "workspace"
str	MODE_SINGLE_PACKAGE = "single_package"
int	WALK_LEVELS = 4
tuple	_CONFIG_FILE_NAMES = ("pyproject.toml", "pytest.ini")
tuple	CWD_RESOLUTION_MESSAGE

Detailed Description

Purpose
-------
The spec-10 §9 discovery-precedence layer for the ``oct test`` v1.0
seed (Plan 189): workspace / ``--package P`` / bare selection over the
workspace manifest, plus the ADR-T-12 single-package fallback walk
(cwd upward for ``pyproject.toml``/``pytest.ini``, four-parent-level
cap, basename inference with the ``[tool.oct.test].package_id``
cross-check override).

Responsibilities
----------------
- :func:`discover` - the §9 precedence table, row for row. Flags are
  plain keyword arguments (this is a LIBRARY: no CLI, no flag
  parsing, no ``sys.exit``); every exit-4 table branch raises
  :class:`oct.testing.errors.OctTestError` with its §12.4 code.
- :func:`walk_for_package` - the ADR-T-12 walk with the ADR's pinned
  diagnostic message, verbatim.
- OUT of scope (future slices): pytest collection and the §4
  collection-check routing (``COLLECTION_ERROR`` /
  ``NO_TESTS_COLLECTED``), runners, schedulers, reports.

Diagnostics
-----------
Domain: OCT-TESTING
Levels:
    L2: lifecycle (discovery start / resolution failures)
    L3: semantic details (resolved mode, selection, walk result)
    L4: deep tracing

Contracts
---------
- Discovery is READ-ONLY: nothing is created or mutated.
- Mutual exclusion (``workspace`` + ``package``) is checked before
  any filesystem access - a fully valid workspace does not rescue
  the call (§9 row 7, "Either").
- The ``--package`` fallback (no manifest found) does NOT walk: the
  package roots at cwd and ``P`` must equal the cwd basename (§9
  row 6); the ADR-T-12 walk belongs to the bare row only.
- A corrupt ``pyproject.toml`` at a discovered root degrades to
  basename inference - the file's existence marks the package root;
  only the optional override read is tolerant.

Dependencies
------------
- oct.core.workspace (read-only: find_workspace_root)
- oct.core.diagnostics (_dbg)
- oct.testing.errors (the §12.4 taxonomy as data)
- oct.testing.manifest (the §9 manifest test view)

Function Documentation

_package_id_for()

str oct.testing.discovery._package_id_for ( Path root, Path config_file )

protected

Infer the package id for *root* (ADR-T-12 clauses 4-5).

Definition at line 305 of file discovery.py.

Here is the caller graph for this function:

_workspace_result()

DiscoveryResult oct.testing.discovery._workspace_result ( Path workspace_root, str | None package )

protected

Build the workspace-mode result (§9 rows 1, 3, 5).

Definition at line 235 of file discovery.py.

Here is the caller graph for this function:

discover()

DiscoveryResult oct.testing.discovery.discover	(	Path	cwd,
		*	,
		bool	workspace = False,
		str | None	package = None )

Resolve the §9 discovery precedence from *cwd*.

Parameters
----------
cwd
    Directory the (future) invocation runs from; the upward
    manifest search and the ADR-T-12 walk both start here.
workspace
    Library mirror of the ``--workspace`` flag.
package
    Library mirror of the ``--package P`` flag.

Returns
-------
:class:`DiscoveryResult`

Raises
------
OctTestError
    Every exit-4 branch of the §9 table:
    ``WORKSPACE_AND_PACKAGE_BOTH_PASSED`` (row 7, checked before
    any IO), ``WORKSPACE_FILE_NOT_FOUND`` (row 4),
    ``PACKAGE_UNKNOWN`` (rows 5 and 6),
    ``CWD_RESOLUTION_FAILED`` (row 2), and the manifest ``9101``/
    ``9102`` codes when a found workspace file is invalid
    (rows 1/3/5).

Definition at line 152 of file discovery.py.

Here is the call graph for this function:

walk_for_package()

SinglePackage oct.testing.discovery.walk_for_package

(

Path

cwd

)

ADR-T-12: walk upward from *cwd* for a package config file.

Checks *cwd* plus up to :data:`WALK_LEVELS` ancestors for
``pyproject.toml`` or ``pytest.ini`` (preference order within a
directory); the nearest hit wins. The package id is the config
directory's basename unless the discovered ``pyproject.toml``
carries a ``[tool.oct.test].package_id`` override (clause 5).

Raises
------
OctTestError
    ``CWD_RESOLUTION_FAILED`` with the ADR's pinned message when
    the walk exhausts its levels.

Definition at line 267 of file discovery.py.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

_CONFIG_FILE_NAMES

tuple oct.testing.discovery._CONFIG_FILE_NAMES = ("pyproject.toml", "pytest.ini")

protected

Definition at line 90 of file discovery.py.

CWD_RESOLUTION_MESSAGE

tuple oct.testing.discovery.CWD_RESOLUTION_MESSAGE

Initial value:

=  (
    "oct test: no pyproject.toml or pytest.ini found within 4 parent "
    "levels of cwd. Run from inside a workspace or package, or pass "
    "--package NAME to disambiguate."
)

Definition at line 94 of file discovery.py.

MODE_SINGLE_PACKAGE

str oct.testing.discovery.MODE_SINGLE_PACKAGE = "single_package"

Definition at line 82 of file discovery.py.

MODE_WORKSPACE

str oct.testing.discovery.MODE_WORKSPACE = "workspace"

Definition at line 79 of file discovery.py.

WALK_LEVELS

int oct.testing.discovery.WALK_LEVELS = 4

Definition at line 85 of file discovery.py.