backcall

Common errors

• TypeError: If the callback expects more arguments, a TypeError is thrown when it is registered.

  cause The `backcall` library's `adapt` method is designed to make a callback function compatible with a prototype that accepts more arguments than the callback, by discarding the extra arguments. However, it explicitly throws a `TypeError` if the provided callback function itself expects *more* arguments than the prototype function it's being adapted to.
  fix Ensure that the callback function being adapted takes fewer or the same number of arguments as the `callback_prototype`. If the callback requires additional arguments, they must be optional (with default values) in the prototype, or the callback's signature needs to be adjusted. ```python from backcall import callback_prototype @callback_prototype def my_prototype(arg1, arg2=None): # Prototype can take arg1 and optional arg2 pass def my_callback_correct(arg1): print(f"Callback received: {arg1}") def my_callback_wrong(arg1, arg2, arg3): # This callback expects too many arguments print(f"Callback received: {arg1}, {arg2}, {arg3}") # Correct usage adapted_callback = my_prototype.adapt(my_callback_correct) adapted_callback("hello", 123) # arg2 is discarded by adapter # Incorrect usage (will raise TypeError) # adapted_callback_error = my_prototype.adapt(my_callback_wrong) # adapted_callback_error("a", "b", "c") ```

• ModuleNotFoundError: No module named 'backcall'

  cause The `backcall` package is not installed in the Python environment being used, or the Python interpreter cannot locate the installed package.
  fix Install the `backcall` library using pip. If it's already installed, ensure you are running your script with the Python interpreter where `backcall` was installed, or that your IDE is configured to use the correct environment. ```bash pip install backcall ```

• ImportError: cannot import name 'callback_prototype' from 'backcall'

  cause This error occurs when trying to import `callback_prototype` (or another specific name like `with_decorators`) from the `backcall` package, but the name is either misspelled, or the Python version/installation is corrupted in a way that prevents proper module introspection.
  fix Verify the spelling of `callback_prototype` and ensure it's exactly as defined in the library. If the spelling is correct, try reinstalling `backcall` to resolve potential corruption issues, or check for Python environment conflicts. ```python # Ensure correct import statement from backcall import callback_prototype # If reinstalling is needed # pip uninstall backcall # pip install backcall ```

Warnings

• gotcha Callback functions provided to `prototype.adapt()` cannot have *more* arguments than defined in the `callback_prototype`, even if those extra arguments have default values. Doing so will result in a `TypeError` when the callback is registered.
  Fix: Ensure that any callback function you pass to `prototype.adapt()` has a signature that is a subset of or exactly matches the prototype's signature. Remove any extra parameters from the callback that are not present in the prototype.
• gotcha Callback functions must have introspectable signatures. This means functions defined in compiled code (e.g., C extensions) cannot be directly used as callbacks unless they are wrapped in a Python function.
  Fix: If using a compiled function, wrap it in a standard Python `def` function to expose an introspectable signature to `backcall`.
• gotcha The project appears to be in a maintenance state, with the last release in June 2020 and minimal recent activity on its GitHub repository. While widely used, be aware that active development and new features are unlikely.
  Fix: Factor in the project's maintenance status when planning long-term dependencies or if requiring new features/bug fixes. Consider vendoring the code if deep customization or active support becomes critical.
• breaking When adapting a callback function using `prototype.adapt()` that has fewer parameters than the prototype (especially if the prototype includes optional parameters with default values that are not in the callback's signature), calling the adapted function without explicitly providing values for those prototype-only parameters will result in a `KeyError` at call time. This occurs because the `backcall` adapter attempts to remove these prototype-specific parameters from its internal argument dictionary even if they were never supplied in the adapted function call.
  Fix: Ensure the callback function's signature *exactly* matches the prototype's signature, or explicitly provide values for all parameters defined in the prototype when calling the adapted function, even for those with default values in the prototype that are not present in the callback's signature. Alternatively, consider adjusting the prototype's signature to align more closely with the callback's needs.

Install

• pip install backcall Install with pip

Imports

• callback_prototype

  from backcall import callback_prototype

Quickstart

To use `backcall`, define a 'callback prototype' function using the `@callback_prototype` decorator. This prototype's signature specifies all parameters that your API might pass. Then, use the `prototype.adapt(callback)` method to inspect and potentially wrap user-provided callback functions. If a callback takes fewer arguments than the prototype, `adapt` creates a wrapper that discards the extra arguments. If a callback takes *more* arguments than the prototype, `adapt` will raise a `TypeError`.

from backcall import callback_prototype

@callback_prototype
def my_prototype_handler(sender, message, detail=None):
    # This function defines the expected signature for callbacks.
    # Positional parameters without defaults, keyword-only with defaults (Python 3).
    pass

def register_event_handler(callback_func):
    # The adapt method inspects the callback and wraps it if necessary
    # to discard extra arguments not in the prototype.
    adapted_callback = my_prototype_handler.adapt(callback_func)
    print(f"Registered adapted callback: {adapted_callback.__name__}")
    return adapted_callback

# Example callbacks
def simple_callback(sender, message):
    print(f"Simple: {sender} says '{message}'")

def detailed_callback(sender, message, detail):
    print(f"Detailed: {sender} says '{message}' with detail: {detail}")

def super_detailed_callback(sender, message, detail, extra_arg='default'):
    print(f"Super Detailed: {sender} says '{message}' with detail: {detail} and extra: {extra_arg}")

# Registering and calling
print("--- Registering simple_callback ---")
adapted_simple = register_event_handler(simple_callback)
adapted_simple('System', 'Hello world!')

print("--- Registering detailed_callback ---")
adapted_detailed = register_event_handler(detailed_callback)
adapted_detailed('System', 'Another message', 'Important info')

# This would normally raise TypeError if passed to .adapt directly, 
# but backcall will raise it because the callback has *more* arguments than prototype.
print("\n--- Attempting to register super_detailed_callback (expecting TypeError) ---")
try:
    register_event_handler(super_detailed_callback)
except TypeError as e:
    print(f"Caught expected error: {e}")