mixle.utils.aliasing module

Backward-compatible keyword-argument aliasing for distribution and estimator constructors.

The distribution API is migrating toward descriptive public argument names (see notes/distribution_api_naming_accounting.md). To keep existing code working while the preferred spellings become canonical, constructors accept both the legacy name and the preferred name and reconcile them with coalesce_alias().

Usage:

def __init__(self, components, w=None, name=None, *, weights=None):
    w = coalesce_alias('w', w, 'weights', weights)

The preferred (alias) argument is keyword-only so it never shadows a positional argument, and the legacy argument keeps its position. Passing both raises TypeError; passing neither raises TypeError for required arguments.

coalesce_alias(canonical_name, canonical_value, alias_name, alias_value, *, required=True, default=None)[source]

Reconcile a canonical (legacy) argument with its preferred alias.

Parameters:

  • canonical_name (str) – Name of the legacy argument, used in error messages.

  • canonical_value (Any) – Value bound to the legacy argument.

  • alias_name (str) – Name of the preferred argument, used in error messages.

  • alias_value (Any) – Value bound to the preferred argument.

  • required (bool) – If True, raise when neither argument was supplied.

  • default (Any) – Sentinel marking “not supplied” for both arguments. Compared by identity, so the legacy argument’s declared default must match this value.

Returns:

The supplied value, preferring the alias when both resolve to non-default (which is only reachable when exactly one was supplied).

Raises:

TypeError – If both arguments are supplied, or if neither is supplied and required.

Return type:

Any

require(name, value, *, default=MISSING)[source]

Return value unless it is the not-supplied sentinel, in which case raise TypeError.

Used for required positional arguments that were given a sentinel default so an aliased earlier argument could become optional (which would otherwise force a non-default argument to follow a defaulted one).

Parameters:
Return type:

Any