Stability helpers

Schema and interface versions, deprecation helpers and the snapshot of the public surface; the policy itself is on the stability page.

handoverlab.stability

Versions of the public surface, deprecations and the surface snapshot.

From 1.0 on, HandoverLab follows Semantic Versioning for its public surface (see docs/stability.md):

  • configuration files (experiments and studies) and result files carry the schema version SCHEMA_VERSION under the top-level key schema; a file without the key is read as schema 1, a file with a newer schema is refused with a message that names it;
  • the rule interface (handoverlab.rules.base) has the version RULE_API_VERSION;
  • metric names (handoverlab.engine.METRICS) are stable; a renamed metric keeps its old name as an alias in METRIC_ALIASES for at least one minor release, and the old name warns.

Anything to be removed is first deprecated with deprecated, which issues a HandoverLabDeprecationWarning naming the version that deprecated it, the version that removes it and the replacement.

public_surface lists the names, hooks, fields, metrics and configuration keys that make up the surface; a test compares it with the snapshot in tests/data/public_api.json. After an intended change, write a new snapshot with python -m handoverlab.stability --write tests/data/public_api.json and record the change in CHANGELOG.md.

HandoverLabDeprecationWarning

Bases: FutureWarning

A deprecated part of the public surface was used.

It derives from FutureWarning, so that it is shown by default to users of scripts and the command line, not only to test runners.

deprecated(what: str, *, since: str, removed_in: str, instead: Optional[str] = None, stacklevel: int = 2) -> None

Warn that what is deprecated since version since and goes in removed_in.

deprecated_alias(func: Callable, old_name: str, *, since: str, removed_in: str) -> Callable

A function under the old name old_name that warns and calls func.

metric_name(name: str) -> str

Current name of the metric name; an old name warns, an unknown one raises KeyError.

check_schema(value: Any, what: str) -> int

Schema version of a file from its schema value (None: schema 1).

Raises ConfigError for a value that is not a positive integer or that is newer than SCHEMA_VERSION.

count_names() -> List[str]

Names of the event counts a run returns next to the metrics (n_...).

public_surface() -> Dict[str, Any]

Names, rule hooks, record fields, metrics and configuration keys of the public surface.