"""Reuse flag definitions for sharing portal and settings across functions.

This module provides the ReuseFlag singleton class and its USE_FROM_OTHER
instance, which enable copying portal linkage and configuration settings
from one function wrapper to another during construction.
"""

from __future__ import annotations

from typing import Final

from mixinforge import SingletonMixin


class ReuseFlag(SingletonMixin):
    """Singleton flag indicating settings should be reused from another wrapper.

    When passed as the value for parameters like `portal` or
    `verbose_logging`, the constructor copies that setting from the source
    function if it is already a compatible wrapper. Use the USE_FROM_OTHER
    instance rather than instantiating this class directly.

    Raises:
        ValueError: If the source function is not an appropriate wrapper type.
    """


USE_FROM_OTHER: Final[ReuseFlag] = ReuseFlag()
"""Singleton flag to inherit settings from an existing function wrapper.

Pass this as the `portal` or `verbose_logging` argument when constructing a
function wrapper (for example, OrdinaryFn or LoggingFn) to copy that setting
from the source function. The source function must be an existing wrapper of a
compatible type, otherwise a ValueError is raised.

Example:
    >>> wrapped = LoggingFn(existing_logging_fn, portal=USE_FROM_OTHER)
    >>> wrapped.portal is existing_logging_fn.portal
    True
"""
