mixle.utils.aliasing module

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

Some distribution constructors keep legacy positional names while also accepting descriptive public keyword aliases. To keep existing code working while 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