bczsalba / tracers

Easily debug and trace attribute changes in your python classes.

Easily debug and trace attribute changes in your Python classes

pip install attr-tracers

Usage

To use this module, simply import trace from it, and decorate your chosen class:

from tracers import trace

@trace("test")
class MyClass:
   def __init__(self) -> None:
       self.test = 0
   
   ...

You can set custom setter and getter methods for your trace, practically allowing you to subcribe to read/write events of an attribute.

from typing import Any
from tracers import trace

def handle_get(obj: object) -> Any:
    """Get variable"""
    
    # Note the namespace-based reference to `attr`
    print(f"Trying to get {attr} from {obj}")
    return getattr(obj, "_" + attr)
    
def handle_set(obj: object, new: Any) -> None:
    """Set variable"""
    
    print(f"Setting {attr} for {obj} from {getattr(obj, attr)} -> {new}")
    setattr(obj, "_" + attr, new)
    
attr = "test"

@trace(attr, getter=handle_get, setter=handle_set)
class MyClass:
   def __init__(self) -> None:
       self.test = 0

You can also optionally output traces into a file non-interactively using the output argument.

Please note that these methods do NOT get a reference to attr. This is a quirk of properties, but you can work around it using namespace-based referencing, like above.

Inner workings

This module under the hood is just an easy way to assign properties to a class.

When decorated with trace("attr"), a class has its attribute attr replaced with a property. The default setter and getter of this property access the "_attr" attribute, as the property takes up "attr".

Essentially, what it becomes is this:

class MyClass:
    @property
    def attr(self) -> Any:
        return self._attr
        
    @attr.setter
    def attr(self, new: str) -> None:
        # Display current trace
        # Take input, quit or dismiss if chosen
        
        self._attr = new

Why use this over manually defining properties?

While defining the properties manually is doable, this module comes in really handy for debugging.

Imagine having a pretty complex hierarchy of class-inheritance and objects all relating to eachother (like it happens in pytermgui). It often happens that there is a certain attribute that isn't quite behaving how it is supposed to. While you could define these properties yourself, being able to import trace and plop it on top of a class is really efficient for debugging.

It also looks much nicer!