Metadata-Version: 2.3
Name: attr-tracers
Version: 1.1.0
Summary: Easily debug class attribute changes.
Project-URL: Documentation, https://github.com/unknown/tracers#readme
Project-URL: Issues, https://github.com/unknown/tracers/issues
Project-URL: Source, https://github.com/unknown/tracers
Author-email: bczsalba <bczsalba@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: sh40-zenith
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/bczsalba/tracer/master/assets/title.png"></img>
</p>

> Easily debug and trace attribute changes in your Python classes

```
pip install attr-tracers
```

[![PyPI version](https://raw.githubusercontent.com/bczsalba/tracer/master/assets/version.svg)](https://pypi.org/project/tracer)

Usage
-----

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

```python
from tracers import trace

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

<a href="https://raw.githubusercontent.com/bczsalba/tracer/master/assets/tracer.webp">
  <img src="https://raw.githubusercontent.com/bczsalba/tracer/master/assets/screenshot.png"></img>
</a>

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

```python
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:
```python3
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](https://github.com/bczsalba/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!
