Base

def clear_caches():
    """Clear cached parameter values from all providers"""
    DEFAULT_PROVIDERS.clear()

def get_transform_method(value: str, transform: TransformOptions = None) -> Callable[..., Any]:
    """
    Determine the transform method

    Examples
    -------
        >>> get_transform_method("key","any_other_value")
        'any_other_value'
        >>> get_transform_method("key.json","auto")
        'json'
        >>> get_transform_method("key.binary","auto")
        'binary'
        >>> get_transform_method("key","auto")
        None
        >>> get_transform_method("key",None)
        None

    Parameters
    ---------
    value: str
        Only used when the transform is "auto".
    transform: str, optional
        Original transform method, only "auto" will try to detect the transform method by the key

    Returns
    ------
    Callable:
        Transform function could be json.loads, base64.b64decode, or a lambda that echo the str value
    """
    transform_method = TRANSFORM_METHOD_MAPPING.get(transform)

    if transform == "auto":
        key_suffix = value.rsplit(".", maxsplit=1)[-1]
        transform_method = TRANSFORM_METHOD_MAPPING.get(key_suffix, TRANSFORM_METHOD_MAPPING[None])

    return cast(Callable, transform_method)  # https://github.com/python/mypy/issues/10740

def resolve_parameters_max_age(choice: int | None) -> int:
    """
    Resolve the caching max age against the ``POWERTOOLS_PARAMETERS_MAX_AGE`` environment variable.

    An explicit ``choice`` always wins. Otherwise the environment variable is used, and an
    empty or non-integer value is ignored with a :class:`PowertoolsUserWarning` rather than
    crashing every lookup: a configuration typo must not break parameter and secret reads
    (ADR 0006: warn now, harden in a future major).

    Parameters
    ----------
    choice : int | None
        Explicit max age passed by the caller, taking precedence over the environment.

    Returns
    -------
    int
        The resolved max age in seconds.
    """
    if choice is not None:
        return choice

    env = os.getenv(constants.PARAMETERS_MAX_AGE_ENV, DEFAULT_MAX_AGE_SECS)
    try:
        return int(env)
    except ValueError:
        warnings.warn(
            f"Ignoring invalid {constants.PARAMETERS_MAX_AGE_ENV} value {env!r}; "
            f"falling back to the default of {DEFAULT_MAX_AGE_SECS} seconds.",
            category=PowertoolsUserWarning,
            stacklevel=3,
        )
        return int(DEFAULT_MAX_AGE_SECS)

def transform_value(
    value: str | bytes | dict[str, Any],
    transform: TransformOptions,
    raise_on_transform_error: bool = True,
    key: str = "",
) -> str | bytes | dict[str, Any] | None:
    """
    Transform a value using one of the available options.

    Parameters
    ---------
    value: str
        Parameter value to transform
    transform: str
        Type of transform, supported values are "json", "binary", and "auto" based on suffix (.json, .binary)
    key: str
        Parameter key when transform is auto to infer its transform method
    raise_on_transform_error: bool, optional
        Raises an exception if any transform fails, otherwise this will
        return a None value for each transform that failed

    Raises
    ------
    TransformParameterError:
        When the parameter value could not be transformed
    """
    # Maintenance: For v3, we should consider returning the original value for soft transform failures.

    err_msg = "Unable to transform value using '{transform}' transform: {exc}"

    if isinstance(value, dict):
        # NOTE: We must handle partial failures when receiving multiple values
        # where one of the keys might fail during transform, e.g. `{"a": "valid", "b": "{"}`
        # expected: `{"a": "valid", "b": None}`

        transformed_values: dict[str, Any] = {}
        for dict_key, dict_value in value.items():
            transform_method = get_transform_method(value=dict_key, transform=transform)
            try:
                transformed_values[dict_key] = transform_method(dict_value)
            except Exception as exc:
                if raise_on_transform_error:
                    raise TransformParameterError(err_msg.format(transform=transform, exc=exc)) from exc
                transformed_values[dict_key] = None
        return transformed_values

    # Auto transforms inspect the parameter name; explicit transforms ignore it.
    transform_method = get_transform_method(value=key, transform=transform)

    try:
        # Identity transforms must preserve raw bytes. Decode failures belong to
        # the same error policy as JSON/base64 failures.
        if isinstance(value, bytes) and transform_method is not TRANSFORM_METHOD_MAPPING[None]:
            value = value.decode("utf-8")
        return transform_method(value)
    except Exception as exc:
        if raise_on_transform_error:
            raise TransformParameterError(err_msg.format(transform=transform, exc=exc)) from exc
        return None