Parameter Decorators

Common errors

• TypeError: expected str, bytes or os.PathLike object, not int (or similar for unsupported types)

  cause The `str_to_path` decorator attempts to convert the input argument into a `pathlib.Path` object. If the argument provided is not a string, bytes, or an object convertible to `Path` (e.g., an integer or an arbitrary custom object), the conversion will fail internally within the decorator.
  fix Ensure that the argument passed to the decorated function is compatible with `pathlib.Path`'s constructor. Typically, this means passing a string representing the path.

• AttributeError: 'function' object has no attribute 'my_method' (when decorating a method but calling from class) or 'MyClass' object has no attribute 'str_to_path'

  cause This usually indicates a misunderstanding of how decorators are applied to methods vs. standalone functions, or attempting to call a method on the class itself rather than an instance. Decorators modify the function/method in place. Also, sometimes users incorrectly try to import the decorator as a method of the class or module it is applied to.
  fix Ensure the decorator `@str_to_path` is correctly placed directly above the method definition within the class. Always call decorated methods on an *instance* of the class (e.g., `my_instance.my_method('path')`), not the class itself unless it's a `classmethod` or `staticmethod` and the decorator is designed for that.

Warnings

• gotcha Decorators that modify parameter types (like `parameter-decorators`) can lead to a mismatch between the function's static type hints and its actual runtime acceptance. While the runtime behavior is correct, static analysis tools (e.g., MyPy) might flag type errors or provide misleading autocomplete suggestions if they don't understand the decorator's effect.
  Fix: Be mindful of this discrepancy during development. If strict type checking is critical, consider adding type ignores or using runtime type checks within the decorated function, or document the decorator's effect clearly.
• gotcha When stacking multiple decorators, their order of application can significantly impact behavior. Decorators are applied from bottom to top. If multiple decorators interact with or modify function arguments, their sequence can lead to unexpected results.
  Fix: Carefully consider the order of decorators, especially if they both convert parameters and perform other actions (e.g., logging, validation). Test thoroughly with different decorator stacks.

Install

• pip install parameter-decorators Install latest stable version

Imports

• str_to_path

  from parameter_decorators import str_to_path

  Used to convert string arguments to pathlib.Path objects.
• path_to_str

  from parameter_decorators import path_to_str

  Used to convert pathlib.Path arguments to string paths. This would typically be used for return values or if a function expects Path but needs to output str.

Quickstart

This example demonstrates how to use the `str_to_path` decorator. The `process_file` method is type-hinted to expect a `Path` object, but thanks to the decorator, it seamlessly accepts a string path, which is then converted before the method's execution. It also shows that you can still pass `Path` objects directly.

from parameter_decorators import str_to_path
from pathlib import Path

class MyProcessor:
    @str_to_path
    def process_file(self, path: Path):
        """Expects a Path object, but decorator allows string input."""
        print(f"Processing: {path.name} (Type: {type(path)})")
        # Simulate file operation
        if path.exists():
            print(f"File '{path}' exists.")
        else:
            print(f"File '{path}' does not exist, creating dummy.")
            path.touch()

# Example usage:
processor = MyProcessor()
processor.process_file("my_document.txt")
processor.process_file(Path("another_file.log")) # Can still pass Path directly