dissolve-python 0.3.0

"""
Basic utility functions demonstrating function deprecation patterns.
"""

try:
    from dissolve import replace_me
except ModuleNotFoundError:
    # Fallback implementation for when dissolve is not available
    import warnings

    def replace_me(since=None, remove_in=None, message=None):
        def decorator(func):
            def wrapper(*args, **kwargs):
                msg = f"{func.__name__} has been deprecated"
                if since:
                    msg += f" since {since}"
                if remove_in:
                    msg += f" and will be removed in {remove_in}"
                if message:
                    msg += f". {message}"
                else:
                    msg += ". Consider running 'dissolve migrate' to automatically update your code."
                warnings.warn(msg, DeprecationWarning, stacklevel=2)
                return func(*args, **kwargs)
            return wrapper
        return decorator


def add(a, b):
    """Add two numbers together (new API)."""
    return a + b


def multiply(a, b, factor=1):
    """Multiply two numbers with an optional factor (new API)."""
    return a * b * factor


def divide(dividend, divisor):
    """Divide two numbers (new API)."""
    if divisor == 0:
        raise ValueError("Cannot divide by zero")
    return dividend / divisor


def power(base, exponent=2):
    """Raise base to the power of exponent (new API)."""
    return base ** exponent


# === DEPRECATED FUNCTIONS ===

@replace_me(since="1.0.0", remove_in="3.0.0")
def old_add(a, b):
    """
    Add two numbers together.
    
    .. deprecated:: 1.0.0
        Use :func:`add` instead.
    """
    return add(a, b)


@replace_me(since="1.5.0", remove_in="3.0.0")
def old_multiply(x, y):
    """
    Multiply two numbers (legacy version).
    
    .. deprecated:: 1.5.0
        Use :func:`multiply` instead for better performance.
    """
    return multiply(x, y)


@replace_me(since="2.0.0")
def legacy_divide(numerator, denominator):
    """
    Legacy division function with old parameter names.
    
    .. deprecated:: 2.0.0
        Use :func:`divide` instead.
    """
    return divide(numerator, denominator)


@replace_me(since="1.8.0", remove_in="2.5.0")
def square(num):
    """
    Square a number (legacy version).
    
    .. deprecated:: 1.8.0
        Use :func:`power` instead.
    """
    return power(num, 2)


@replace_me(since="2.1.0")
def cube(num):
    """
    Cube a number (legacy version).
    
    .. deprecated:: 2.1.0
        Use :func:`power` instead.
    """
    return power(num, 3)


# Complex transformation example
@replace_me(since="1.2.0")
def old_format_string(template, *args, uppercase=False):
    """
    Format a string with positional arguments.
    
    .. deprecated:: 1.2.0
        Use :func:`format_string` instead with reordered parameters.
    """
    return format_string(uppercase, template, *args)


def format_string(uppercase, template, *args):
    """Format a string with optional uppercase conversion (new API)."""
    result = template.format(*args)
    return result.upper() if uppercase else result