Legacy API Wrapper

Warnings

• gotcha The primary purpose of `legacy_api_wrap` is to *emit warnings* (defaulting to `FutureWarning`) when old argument names are used. It does not silence these warnings by default, and users may need to explicitly configure Python's `warnings` module or a custom `warning_category` (since v1.4) to alter this behavior.
  Fix: Be aware of `FutureWarning`s emitted during migration. To change their behavior, use `warnings.filterwarnings()` or pass a custom `warning_category` to the decorator, e.g., `@legacy_api_wrap(..., warning_category=DeprecationWarning)`.
• gotcha When using the decorator, ensure that the `kwargs` mapping correctly translates *all* necessary old arguments to their new counterparts. If an old argument is passed that is not mapped and is required by the new function, it will result in a `TypeError` from the underlying function, similar to calling it directly without the required argument.
  Fix: Thoroughly test the wrapped function with old API calls, ensuring all expected arguments are mapped within the `@legacy_api_wrap(...)` decorator configuration.
• gotcha If a function wrapped with `legacy_api_wrap` is called with both an old argument name and its corresponding new argument name (e.g., `old_arg='val1', new_arg='val2'`), the value passed to the *new* argument name will take precedence. This can lead to subtle bugs if callers accidentally provide conflicting arguments.
  Fix: Document this behavior for users of the wrapped function and ensure migration guides clarify that only new argument names should be used once fully migrated. Avoid passing both old and new names simultaneously.

Install

• pip install legacy-api-wrap Install stable version

Imports

• legacy_api_wrap

  from legacy_api_wrap import legacy_api_wrap

Quickstart

This example demonstrates defining a function with a new API signature and wrapping it with `legacy_api_wrap` to allow calls using old argument names. It also shows how the decorator emits `FutureWarning`s when old arguments are used.

from legacy_api_wrap import legacy_api_wrap
import warnings

# Define the new function with updated argument names
@legacy_api_wrap(old_arg_name='new_arg_name', another_old='yet_another')
def my_new_function(new_arg_name: str, yet_another: int = 10):
    """This function uses the new API signature."""
    print(f"New function called! new_arg_name='{new_arg_name}', yet_another={yet_another}")

print("Calling with old API arguments (expecting a FutureWarning):")
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always") # Ensure warnings are always captured
    my_new_function(old_arg_name="Hello Legacy", another_old=5)
    assert len(w) > 0
    assert issubclass(w[-1].category, FutureWarning)
    print(f"Warning caught: {w[-1].message}")

print("\nCalling with new API arguments:")
my_new_function(new_arg_name="Hello Modern", yet_another=20)