# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/04_docs.ipynb.

# %% auto 0
__all__ = ['fmeta', 'fact', 'iseq', 'get', 'bump', 'flist', 'convert', 'umeta', 'unit', 'to', 'fmtunit']

# %% ../nbs/04_docs.ipynb 3
#| export

# %% ../nbs/04_docs.ipynb 6
fmeta = '''Metaclass for SI unit factors.

    `fmeta` acts as a metaclass for SI unit factors. It sets class variables based on
    the superclass and allows each subclass to have its own definitions. It also handles
    the registration of each factor class.

    Class Attributes
    ----------------
    name : ClassVar[str]
        The name of the factor.
    abrv : ClassVar[str]
        The abbreviation of the factor.
    symb : ClassVar[str]
        The symbol of the factor.
    expo : ClassVar[int]
        The exponent of the factor.
    sign : ClassVar[sint]
        The sign of the exponent (Positive, Negative, or Zero).
    ekey : ClassVar[int]
        Calculated as sign * expo.

    Methods
    -------
    clsdef(cls, attr: str, default: Any = None, **kwargs)
        Get the `attr` from `kwargs`, the class, or the `default`, whichever is found first.
    '''
fact = '''Class for representing SI unit factors.

    `fact` is a class for representing SI unit factors like kilo, mega, giga, etc.
    It is defined by its name, abbreviation, symbol, and exponent. It provides methods
    to convert values between factors, list all existing factors, and more.

    Class Attributes
    ----------------
    name : ClassVar[str]
        The name of the factor.
    abrv : ClassVar[str]
        The abbreviation of the factor.
    symb : ClassVar[str]
        The symbol of the factor.
    expo : ClassVar[int]
        The exponent of the factor.
    sign : ClassVar[sint]
        The sign of the exponent (Positive, Negative, or Zero).
    ekey : ClassVar[int]
        Calculated as sign * expo.

    Instance Attributes
    -------------------
    base : Optional[int]
        The base for the exponent, defaults to 10.
    echr : ExpoChr
        Character used for indicating exponentiation.
    showsign : bool
        Whether to show the sign in the representation.
    showbase : bool
        Whether to show the base in the representation.
    showefmt : bool
        Whether to show the exponent in the representation.

    Methods
    -------
    clsdef(attr: str, default: Any = None, **kwargs)
        Get the `attr` from `kwargs`, the class, or the `default`, whichever is found first.
    
    iseq(v)
        Checks if the factor is equivalent to the value `v`.

    get(v)
        Retrieves the factor corresponding to the value `v`.

    bump(fcls: 'fact', bump: int = 0)
        Bumps the exponent of the factor by `bump`.

    list(attr: str = 'abrv')
        Lists all registered factors based on the attribute `attr`.

    convert(val: Number, to: 'fact')
        Converts a value to a different factor.

    register(f: 'fact')
        Registers a factor class.

    ispos()
        Checks if the factor is positive.
    isneg()
        Checks if the factor is negative.

    Properties
    ----------
    fstr
        Returns the exponential format of the factor, e.g., F3N.

    bstr
        Returns the base format of the factor, e.g., `10^-3`.

    efmt
        Returns the exponential format of the factor, e.g., 10-3.

    ispos()
        Checks if the factor is positive.

    isneg()
        Checks if the factor is negative.
    '''
iseq = '''Check if the class or its attributes match a given value.

        Parameters
        ----------
        v : Any
            The value to be checked.

        Returns
        -------
        bool
            True if the value matches the class or any of its attributes (`name`, `abrv`, `symb`, `ekey`), otherwise False.
        '''
get = '''Retrieve a factor class that matches a given value.

        Parameters
        ----------
        v : Any
            The value to be checked.

        Returns
        -------
        Optional['fact']
            Returns the factor class if found, otherwise None.
        '''    
bump = '''Bump the exponent of the factor by a given amount.

        Parameters
        ----------
        fcls : 'fact'
            The factor class to bump.
        bump : int, optional
            The amount to bump the exponent by, defaults to 0.

        Returns
        -------
        'fact'
            The new factor class with the bumped exponent.

        Examples
        --------
        >>> tuple((i, fact.moveunit(one, i).name) for i in range(-13, 14, 1))
        '''
flist = '''List all registered factors based on a given attribute.

        Parameters
        ----------
        attr : str, optional
            The attribute to list, defaults to 'abrv'.

        Returns
        -------
        list
            A list of all registered factors based on the attribute.
        '''
convert = '''Convert a number to a different factor.

        Parameters
        ----------
        val : Number
            The value to convert.
        to : 'fact'
            The factor class to convert to.

        Returns
        -------
        float
            The converted value.

        Raises
        ------
        FactorError
            If the target factor is not found.
        '''

# %% ../nbs/04_docs.ipynb 8
umeta = '''A metaclass for setting SI unit properties on the unit class.

    The `umeta` metaclass attaches SI unit properties to classes at the time of their creation. 
    It pulls the attributes from the `fact` class and sets them as properties on the class it 
    initializes.

    Attributes
    ----------
    units : set['fact']
        Set of SI unit factors, populated from `fact.facts`.

    Methods
    -------
    __new__(cls, name, bases, cls_dict)
        Create a new instance of the metaclass, setting the unit attributes.

    Examples
    --------
    >>> class unit(float, metaclass=umeta):
    ...     pass
    >>> unit.units
    (one, decka, hecto, ..., quetta, deci, ..., quecto)
    '''

unit = '''Class for representing SI units, inheriting from float and using `umeta` as the metaclass.

    The `unit` class defines the properties and methods for handling units in the SI system. 
    It allows for conversion between different units and representations.

    Class Attributes
    ----------------
    name : ClassVar[str]
        The name of the unit.
    debug : ClassVar[bool]
        Debugging flag to control representation.

    Instance Attributes
    -------------------
    core : Optional[float]
        The actual float value stored.
    base : Optional[int]
        The base for the exponent, defaults to 10.
    fcls : Optional[fact]
        The factor class being used, defaults to `one`.
    numb : Optional[float]
        The number used for conversion.
    ndig : Optional[int]
        Number of digits to display.
    shownumb : Optional[bool]
        Whether to show the number in representation.
    abrvunit : Optional[bool]
        Whether to abbreviate the unit.
    factrepr : Optional[FactRepr]
        How to represent the factor ('abrv', 'name', 'symb').

    Methods
    -------
    getcfunc(fcls: fact)
        Returns a class method for converting the unit to the given factor class.
    factor()
        Actually applies the factor to the base.
    to(key, inplace: bool = False)
        Converts the unit to a different factor.
    '''


to = '''Converts the unit to a different factor.

        This method changes the unit of the number to the unit specified by the `key`.
        The conversion is either done in-place or a new object is returned based on the
        `inplace` parameter.

        Parameters
        ----------
        key : Any
            The key used to look up the factor class. It could be an abbreviation, name, 
            symbol, or the factor class itself.
        inplace : bool, optional
            If True, the conversion is done in-place and the object itself is modified.
            Otherwise, a new object with the converted value is returned. Default is False.

        Returns
        -------
        unit
            A new `unit` object with the converted value if `inplace` is False, otherwise 
            modifies the object itself and returns it.

        Raises
        ------
        FactorError
            If the provided `key` is not found in the available factors.

        Examples
        --------
        >>> u = unit(1000, base=10, fcls=kilo)
        >>> u.to(mega)
        unit(1)
        >>> u.to(mega, inplace=True)
        unit(1)
        '''

fmtunit = '''Formats a given number to its representation in units with factors.

    Parameters
    ----------
    org : float
        The number as converted to the desired factor.
    flt : Optional[float], default=None
        The original number prior to factor conversion.
    unt : Optional[unit], default=None
        An instance of a unit class representing the base unit.
    fct : Optional[fact], default=None
        The factor class for the desired unit representation.
    shownumb : Optional[bool], default=True
        Whether to show the original number (`flt`) or the scaled number (`org`).
    abrvunit : Optional[bool], default=False
        Whether to show the abbreviation or the full name of the unit.
    factrepr : Optional[str], default='abrv'
        Representation of factor class to use, options include 'name', 'abrv', and 'symb'.
    ndig : Optional[int], default=3
        Number of significant digits to represent the number.
    unitname : Optional[str], default=None
        Override for the unit's name.
    factname : Optional[str], default=None
        Override for the factor's name or representation.

    Returns
    -------
    str
        Formatted string representation of the number in units with factors.

    Examples
    --------
    >>> fmtunit(1000.0, flt=1, unt=second, fct=kilo, factrepr='name')
    '1 Kilosecond'
    >>> fmtunit(1000.0, flt=1, unt=second, fct=kilo, factrepr='abrv')
    '1 Ksecond'
    >>> fmtunit(1000.0, flt=1, unt=second, fct=kilo, factrepr='symb')
    '1 KS'
    '''
