Deprecated

from deprecated import deprecated

from deprecated.sphinx import deprecated, versionadded, versionchanged

from deprecated.classic import deprecated, ClassicAdapter
from deprecated.sphinx import SphinxAdapter

from warnings import DeprecationWarning, FutureWarning, PendingDeprecationWarning

from deprecated import deprecated

@deprecated
def some_old_function(x, y):
    return x + y

@deprecated
class SomeOldClass:
    pass

class SomeClass:
    @deprecated
    def some_old_method(self, x, y):
        return x + y

from deprecated import deprecated

@deprecated(reason="use another function", version='1.2.0')
def some_old_function(x, y):
    return x + y

@deprecated(reason="This method is deprecated", version='1.3.0')
def some_old_method(self, x, y):
    return x + y

from deprecated.sphinx import deprecated, versionadded, versionchanged

@versionadded(version='1.0', reason="This function is new")
def new_function():
    '''This function was added in version 1.0'''

@versionchanged(version='1.1', reason="This function behavior changed")
def modified_function():
    '''This function was modified in version 1.1'''

@deprecated(version='1.2', reason="This function will be removed soon")
def old_function():
    '''This function is deprecated as of version 1.2'''

def deprecated(*args, **kwargs):
    """
    Decorator to mark functions, methods, or classes as deprecated.
    
    Parameters:
    - reason (str, optional): Reason message for deprecation
    - version (str, optional): Version when deprecated  
    - action (str, optional): Warning filter action ("default", "error", "ignore", "always", "module", "once")
    - category (Type[Warning], optional): Warning category class (default: DeprecationWarning)
    - adapter_cls (Type, optional): Custom adapter class (default: ClassicAdapter)
    - extra_stacklevel (int, optional): Additional stack levels for warnings (default: 0)
    
    Returns:
    Decorated function, method, or class
    """

class ClassicAdapter:
    def __init__(self, reason="", version="", action=None, category=DeprecationWarning, extra_stacklevel=0):
        """
        Construct a wrapper adapter.
        
        Parameters:
        - reason (str): Reason message for deprecation
        - version (str): Version when deprecated
        - action (str): Warning filter action
        - category (Type[Warning]): Warning category class
        - extra_stacklevel (int): Additional stack levels for warnings
        """
        
    def get_deprecated_msg(self, wrapped, instance):
        """
        Get the deprecation warning message for the user.
        
        Parameters:
        - wrapped: Wrapped class or function
        - instance: The object to which the wrapped function was bound
        
        Returns:
        str: The warning message
        """
        
    def __call__(self, wrapped):
        """
        Decorate your class or function.
        
        Parameters:
        - wrapped: Wrapped class or function
        
        Returns:
        The decorated class or function
        """

def versionadded(reason="", version="", line_length=70):
    """
    Insert a "versionadded" directive in docstring.
    
    Parameters:
    - reason (str): Reason message documenting the addition
    - version (str): Version when added (required)
    - line_length (int): Max line length for directive text (default: 70)
    
    Returns:
    SphinxAdapter: Decorator adapter that modifies docstring when applied
    """

def versionchanged(reason="", version="", line_length=70):
    """
    Insert a "versionchanged" directive in docstring.
    
    Parameters:
    - reason (str): Reason message documenting the modification
    - version (str): Version when changed (required)
    - line_length (int): Max line length for directive text (default: 70)
    
    Returns:
    SphinxAdapter: Decorator adapter that modifies docstring when applied
    """

def deprecated(reason="", version="", line_length=70, **kwargs):
    """
    Insert a "deprecated" directive in docstring and emit deprecation warning.
    
    Parameters:
    - reason (str): Reason message documenting the deprecation
    - version (str): Version when deprecated (required for Sphinx directives)
    - line_length (int): Max line length for directive text (default: 70)
    - **kwargs: Additional keyword arguments:
        - action (str): Warning filter action
        - category (Type[Warning]): Warning category
        - extra_stacklevel (int): Additional stack levels
        - directive (str): Override directive type (default: "deprecated")
        - adapter_cls (Type): Override adapter class (default: SphinxAdapter)
    
    Returns:
    Callable: Decorator function that applies SphinxAdapter with deprecation warning
    
    Raises:
    - ValueError: If version parameter is not provided (required for Sphinx directives)
    """

class SphinxAdapter(ClassicAdapter):
    def __init__(self, directive, reason="", version="", action=None, category=DeprecationWarning, extra_stacklevel=0, line_length=70):
        """
        Construct a Sphinx wrapper adapter.
        
        Parameters:
        - directive (str): Sphinx directive ("versionadded", "versionchanged", "deprecated")
        - reason (str): Reason message
        - version (str): Version (required - cannot be empty for Sphinx directives)
        - action (str): Warning filter action
        - category (Type[Warning]): Warning category (must be imported from warnings)
        - extra_stacklevel (int): Additional stack levels
        - line_length (int): Max line length for directive text (default: 70)
        
        Raises:
        - ValueError: If version parameter is empty or not provided
        """
        
    def get_deprecated_msg(self, wrapped, instance):
        """
        Get deprecation warning message with Sphinx cross-referencing syntax stripped.
        
        This method first calls the parent ClassicAdapter.get_deprecated_msg() to get
        the base warning message, then uses regex to strip Sphinx cross-reference
        syntax (like :role:`foo` and :domain:role:`foo`) for cleaner warnings.
        
        Parameters:
        - wrapped: Wrapped class or function
        - instance: The object to which the wrapped function was bound
        
        Returns:
        str: The warning message with Sphinx cross-reference syntax removed
        """
        
    def __call__(self, wrapped):
        """
        Add Sphinx directive to docstring and decorate class or function.
        
        Parameters:
        - wrapped: Wrapped class or function
        
        Returns:
        The decorated class or function with modified docstring
        """

import inspect
from deprecated.classic import ClassicAdapter, deprecated

class MyClassicAdapter(ClassicAdapter):
    def get_deprecated_msg(self, wrapped, instance):
        if instance is None:
            if inspect.isclass(wrapped):
                fmt = "The class {name} is deprecated."
            else:
                fmt = "The function {name} is deprecated."
        else:
            if inspect.isclass(instance):
                fmt = "The class method {name} is deprecated."
            else:
                fmt = "The method {name} is deprecated."
        if self.reason:
            fmt += " ({reason})"
        if self.version:
            fmt += " -- Deprecated since version {version}."
        return fmt.format(name=wrapped.__name__, 
                         reason=self.reason or "", 
                         version=self.version or "")

@deprecated(reason="use another function", adapter_cls=MyClassicAdapter)
def some_old_function(x, y):
    return x + y

from deprecated import deprecated

# Raise error instead of warning
@deprecated(action="error")
def critical_old_function():
    pass

# Ignore deprecation warnings
@deprecated(action="ignore")
def silent_old_function():
    pass

# Show warning once per module
@deprecated(action="once")
def one_time_warning_function():
    pass

from deprecated import deprecated
from warnings import DeprecationWarning, FutureWarning, PendingDeprecationWarning

class MyDeprecationWarning(DeprecationWarning):
    pass

@deprecated(category=MyDeprecationWarning)
def function_with_custom_warning():
    pass

# Can also use built-in warning types
@deprecated(category=FutureWarning)
def function_with_future_warning():
    pass

@deprecated(category=PendingDeprecationWarning)
def function_with_pending_warning():
    pass

from deprecated import deprecated

def wrapper_function():
    @deprecated(extra_stacklevel=1)
    def inner_function():
        pass
    return inner_function

# The warning will point to the caller of wrapper_function
# instead of the call to inner_function

# Warning filter actions
ActionType = Literal["default", "error", "ignore", "always", "module", "once"]

# Sphinx directive types  
DirectiveType = Literal["versionadded", "versionchanged", "deprecated"]

# Base adapter interface
class AdapterProtocol:
    def __init__(self, reason: str = "", version: str = "", action: ActionType = None, 
                 category: Type[Warning] = DeprecationWarning, extra_stacklevel: int = 0): ...
    def get_deprecated_msg(self, wrapped: Callable, instance: Any) -> str: ...
    def __call__(self, wrapped: Callable) -> Callable: ...