{"id":2984,"library":"legacy-api-wrap","title":"Legacy API Wrapper","description":"legacy-api-wrap (version 1.5) provides a decorator for Python functions to seamlessly bridge old and new API interfaces. It allows developers to deprecate old argument names while still supporting them, typically by emitting warnings when old names are used. The library is actively maintained with feature-driven releases, ensuring compatibility and developer-friendly transitions.","status":"active","version":"1.5","language":"en","source_language":"en","source_url":"https://github.com/flying-sheep/legacy-api-wrap","tags":["API wrapper","legacy","compatibility","deprecation","arguments","refactoring"],"install":[{"cmd":"pip install legacy-api-wrap","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"legacy_api_wrap","correct":"from legacy_api_wrap import legacy_api_wrap"}],"quickstart":{"code":"from legacy_api_wrap import legacy_api_wrap\nimport warnings\n\n# Define the new function with updated argument names\n@legacy_api_wrap(old_arg_name='new_arg_name', another_old='yet_another')\ndef my_new_function(new_arg_name: str, yet_another: int = 10):\n    \"\"\"This function uses the new API signature.\"\"\"\n    print(f\"New function called! new_arg_name='{new_arg_name}', yet_another={yet_another}\")\n\nprint(\"Calling with old API arguments (expecting a FutureWarning):\")\nwith warnings.catch_warnings(record=True) as w:\n    warnings.simplefilter(\"always\") # Ensure warnings are always captured\n    my_new_function(old_arg_name=\"Hello Legacy\", another_old=5)\n    assert len(w) > 0\n    assert issubclass(w[-1].category, FutureWarning)\n    print(f\"Warning caught: {w[-1].message}\")\n\nprint(\"\\nCalling with new API arguments:\")\nmy_new_function(new_arg_name=\"Hello Modern\", yet_another=20)","lang":"python","description":"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."},"warnings":[{"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)`.","message":"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.","severity":"gotcha","affected_versions":"v1.0+"},{"fix":"Thoroughly test the wrapped function with old API calls, ensuring all expected arguments are mapped within the `@legacy_api_wrap(...)` decorator configuration.","message":"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.","severity":"gotcha","affected_versions":"v1.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"v1.0+"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}