Parameter Models¶

def __post_init__(self) -> None:
    """Process extra fields after initialization."""
    # Move any extra fields to _extra_fields
    for key, value in list(self.__dict__.items()):
        if key not in self.defined_field_names:
            setattr(self, key, value)

@validate_call
def update(
    self,
    *,
    extra: Literal["allow", "forbid", "ignore"] = "allow",
    ignore_null: bool = True,
    **kwargs: Any,
) -> None:
    """
    Update the attributes of the instance based on the provided parameters.

    Parameters
    ----------
    extra
        Determines how to handle extra fields in `kwargs`.
    ignore_null
        If True, removes `None` values from `kwargs`.
    **kwargs
        Field names and values to be updated.

    """
    # Create a copy of kwargs to avoid modifying it during iteration
    update_kwargs = kwargs.copy()

    if extra == "forbid":
        # Forbid extra fields
        unknown_keys = set(update_kwargs) - set(self.defined_field_names)
        if unknown_keys:
            msg = f"Unknown parameters: {unknown_keys}"
            raise ValueError(msg)
    elif extra == "ignore":
        # Ignore extra fields
        update_kwargs = {
            k: v for k, v in update_kwargs.items() if k in self.defined_field_names
        }

    # Remove None values if ignore_null is True
    if ignore_null:
        update_kwargs = {k: v for k, v in update_kwargs.items() if v is not None}

    # Update fields
    for key, value in update_kwargs.items():
        if key in self.defined_field_names or extra == "allow":
            setattr(self, key, value)

def get_defaults(self) -> dict[str, Any]:
    """
    Get the default values for all defined fields in the model.

    Returns
    -------
    :
        Dictionary mapping field names to their default values.
        Excludes the special `_extra_fields` field.

    """
    return {
        fld.name: fld.default for fld in fields(self) if fld.name != "_extra_fields"
    }

def get(self, key: str, default: Any = None) -> Any:
    """
    Get a parameter value with a default fallback.

    Parameters
    ----------
    key
        Name of the parameter
    default
        Default value if parameter doesn't exist

    Returns
    -------
    :
        Parameter value or default

    """
    if key in self.current_field_names:
        return getattr(self, key)
    return default

def __getitem__(self, key: str) -> Any:
    """
    Get a parameter value using dictionary-style access.

    Parameters
    ----------
    key
        Name of the parameter

    Returns
    -------
    :
        Parameter value

    Raises
    ------
    KeyError
        If the parameter doesn't exist

    """
    if key in self.current_field_names:
        return getattr(self, key)
    msg = f"Parameter '{key}' does not exist."
    raise KeyError(msg)

def as_dict(self, drop: list[str] | None = None) -> dict[str, Any]:
    """
    Get all parameters as a dictionary.

    Returns
    -------
    :
        Dictionary of parameter values

    """
    dictionary = self.__dict__.copy()
    if drop is not None:
        for key in drop:
            dictionary.pop(key, None)
    return dictionary

def copy(self) -> ParamModel:
    """
    Create a deep copy of the parameter model instance.

    Returns
    -------
    :
        A deep copy of the current instance with all nested objects copied.

    """
    return copy.deepcopy(self)

def model_copy(self) -> ParamModel:
    """
    Create a copy of the parameter model instance.

    !!! warning "Deprecated"
        This method is deprecated. Use :meth:`copy` instead.
        Kept only for backwards compatibility with Pydantic.

    Returns
    -------
    :
        A deep copy of the current instance.

    """
    warnings.warn(
        "model_copy is deprecated. Use copy instead."
        "Kept only for backwards compatibility with Pydantic.",
        DeprecationWarning,
        stacklevel=2,
    )
    return self.copy()

def get_changed_params(self) -> dict[str, Any]:
    """
    Get parameters that have been changed from their defaults.

    This method compares the current parameter values against the default values
    and returns a dictionary containing only the parameters that differ from
    their defaults.

    Returns
    -------
    :
        Dictionary of changed parameters and their current values.

    """
    default_values = self.get_defaults()
    current_values = self.as_dict()

    # Use dictionary comprehension to identify and collect changed parameters
    # Return the current values (not default values) for the changed parameters
    return {
        param_name: current_values[param_name]
        for param_name, default_value in default_values.items()
        if current_values[param_name] != default_value
    }

def get_multiple(self, keys: list[str]) -> dict[str, Any]:
    """
    Get multiple parameters as a dictionary.

    Parameters
    ----------
    keys
        List of parameter names

    Returns
    -------
    :
        Dictionary of parameter values

    """
    return {key: self[key] for key in keys if key in self.current_field_names}

def pop(self, key: str) -> Any:
    """
    Remove a parameter and return its value.

    For fields defined in the model, the value is reset to its default.

    Parameters
    ----------
    key
        Name of the parameter

    Returns
    -------
    :
        Value of the removed parameter

    Raises
    ------
    KeyError
        If the parameter doesn't exist

    """
    if key in self.defaults:
        value = getattr(self, key)
        setattr(self, key, self.defaults[key])  # Reset to default/None
        return value
    if key in self.current_field_names:
        value = self.get(key)
        delattr(self, key)
        return value
    msg = f"Parameter '{key}' does not exist."
    raise KeyError(msg)

def drop(self, keys: str | Iterable[str], *, ignore_missing: bool = True) -> None:
    """
    Remove a parameter without returning its value.

    Parameters
    ----------
    keys
        Name of the parameter or list of parameters
    ignore_missing
        If True, ignore missing keys. If False, raise KeyError for missing keys.

    """
    if isinstance(keys, str):
        keys = [keys]

    for key in keys:
        try:
            delattr(self, key)
        except (KeyError, AttributeError) as e:
            if not ignore_missing:
                if isinstance(e, AttributeError):
                    msg = f"Parameter '{key}' does not exist."
                    raise KeyError(msg) from e
                raise

def crosscheck_palette_hue(self) -> None:
    """
    Check if the palette is valid for the given hue.

    This method ensures that palette is only used when hue is provided.
    """
    self.palette = self.palette if self.hue is not None else None

def as_seaborn_kwargs(self, drop: list[str] | None = None) -> dict[str, Any]:
    """
    Convert parameters to kwargs compatible with seaborn functions.

    Returns
    -------
    :
        Dictionary of parameter values suitable for seaborn plotting functions.

    """
    return self.as_dict(drop=drop)

def as_seaborn_kwargs(self, drop: list[str] | None = None) -> dict[str, Any]:
    """
    Convert parameters to kwargs compatible with seaborn functions.

    Returns
    -------
    :
        Dictionary of parameter values suitable for seaborn plotting functions.

    """
    # None to drop yet
    if drop is None:
        drop = []
    # Add common parameters to drop list
    drop.extend(["incl_outline"])
    return super().as_seaborn_kwargs(drop=drop)

def to_outline(self, *, alpha: float = 1, fill: bool = False) -> DensityParams:
    """
    Convert to outline parameters.

    Parameters
    ----------
    alpha
        Alpha value for the outline.
    fill
        Whether to fill the outline.

    Returns
    -------
    :
        New instance with outline parameters.

    """
    # Create a copy of the parameters
    params_dict = self.as_dict()

    # Update parameters for outline
    params_dict.update(alpha=alpha, fill=fill, legend=False)

    # Create a new instance with the updated parameters
    return DensityParams(**params_dict)

def as_seaborn_kwargs(self, drop: list[str] | None = None) -> dict[str, Any]:
    """
    Convert parameters to kwargs compatible with seaborn functions.

    Returns
    -------
    :
        Dictionary of parameter values suitable for seaborn plotting functions.

    """
    droplist = ["n", "show_score", "axis_text_kw"]
    if isinstance(drop, list):
        droplist.extend(drop)
    return self.as_dict(drop=droplist)

def as_plt_subplots_args(self) -> dict[str, Any]:
    """
    Pass matplotlib subplot arguments to a plt.subplots call.

    Returns
    -------
    :
        Dictionary of subplot parameters.

    """
    kwargs = self.as_dict()
    for key in [
        "subplot_by",
        "n_subplots_by",
        "auto_allocate_axes",
        "adjust_figsize",
    ]:
        kwargs.pop(key, None)
    return kwargs