Modules

Fast and minimalistic library for marking methods and classes as deprecated.

pyminideprecator is a lightweight yet powerful decorator-based solution for managing code deprecation in Python libraries and applications. It provides a robust mechanism to mark deprecated code with automatic warnings that escalate to errors at specified version thresholds, supporting both semantic versioning and date-based versioning. The library is designed with thread safety and asynchronous execution in mind, making it suitable for all types of Python projects.

exception pyminideprecator.DeprecatedError

Bases: Exception

Exception raised when deprecated functions is accessed beyond its removal version.

This error indicates that the code has reached or exceeded the version where the deprecated functionality is scheduled for removal, and attempts to use it should be treated as errors rather than warnings.

message

Explanation of the deprecation error

class pyminideprecator.Version(version_str)

Bases: object

Represents a version for deprecation lifecycle management.

Supports both semantic versioning (1.2.3) and date-based versioning (2023.12.31). Provides comparison operations for version lifecycle decisions.

Parameters:

version_str (str) – Version string to parse

Raises:

ValueError – For invalid version formats

raw

Original version string

is_date

True if version is date-based

parts

Tuple of integers for semantic versions

date

Date object for date-based versions

__init__(version_str)

Initialize a version class.

Parameters:

version_str (str) – version as string.

Raises:

ValueError – invalid version format.

Return type:

None

pyminideprecator.deprecate(remove_version, message, since=None, instead=None, category=<class 'DeprecationWarning'>, stacklevel=2, error_version=None)

Decorator factory for marking deprecated functionality.

Primary interface for deprecating functions, methods, and classes. Creates a decorator that adds deprecation warnings and eventual error behavior.

Parameters:

• remove_version (str) – Version when functionality will be removed (required)

• message (str) – Description of deprecation (required)

• since (str | None) – Optional version when deprecation was introduced

• instead (str | None) – Optional recommended alternative

• category (type[Warning]) – Warning category (default: DeprecationWarning)

• stacklevel (int) – Warning stack level (default: 2)

• error_version (str | None) – Optional version when functionality starts raising errors (defaults to remove_version if not specified)

Returns:

A decorator that applies deprecation behavior to the target object

Return type:

Callable[[F | C], F | C]

Example

>>> @deprecate("2.0.0", "Use new_function instead")
>>> def old_function():
...     pass

pyminideprecator.get_current_version()

Retrieves the current application version for the context or global scope.

Returns:

The current Version object if set, otherwise None.

Return type:

Version | None

pyminideprecator.scoped_version(version)

Context manager for creating scoped version.

Parameters:

version (str) – The scoped version

pyminideprecator.set_current_version(version, set_global=False)

Sets the current application version in the current context.

This version is context-aware and thread-safe. It can be: - String representation (e.g., “1.2.3” or “2023.12.31”) - Version object instance - None to clear the current version

Parameters:

• version (str | Version | None) – The current version to set

• set_global (bool) – True is set version as global, False as the set version to context

Raises:

• ValueError – If string version has invalid format

• TypeError – If invalid version type is provided

Return type:

None