https://github.com/timkpaine/bigbrother

An evil, awful, terrible, no-good library for watching objects for mutation. Do not use this library.
https://github.com/timkpaine/bigbrother

observability observer observer-pattern pydantic python python3 reactive

Last synced: 1 day ago
JSON representation

An evil, awful, terrible, no-good library for watching objects for mutation. Do not use this library.

• Host: GitHub
• URL: https://github.com/timkpaine/bigbrother
• Owner: timkpaine
• License: apache-2.0
• Created: 2023-04-05T17:04:53.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-12-01T05:23:17.000Z (about 1 month ago)
• Last Synced: 2024-12-29T14:51:41.838Z (4 days ago)
• Topics: observability, observer, observer-pattern, pydantic, python, python3, reactive
• Language: Python
• Homepage:
• Size: 58.6 KB
• Stars: 10
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: .github/CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
# bigbrother

An evil, awful, terrible, no-good library for watching objects for mutation. Do not use this library.

[![Build Status](https://github.com/timkpaine/bigbrother/workflows/Build%20Status/badge.svg?branch=main)](https://github.com/timkpaine/bigbrother/actions?query=workflow%3A%22Build+Status%22)

[![Coverage](https://codecov.io/gh/timkpaine/bigbrother/branch/main/graph/badge.svg)](https://codecov.io/gh/timkpaine/bigbrother)

[![License](https://img.shields.io/github/license/timkpaine/bigbrother)](https://github.com/timkpaine/bigbrother)

[![PyPI](https://img.shields.io/pypi/v/bigbrother.svg)](https://pypi.python.org/pypi/bigbrother)

## Overview

`bigbrother` is a mutation observer library. You can use it to watch your objects for changes. When your object changes, `bigbrother` will trigger your choice of callback. 

```python

x = {1: "a", 2: "b", 3: "c"}

def track_changes(obj, method, ref, call_args, call_kwargs):

    print(f"method: {method}, args: {args}, kwargs: {kwargs}")

x = watch(x, track_changes)

x[1] = "x"

# prints: method: setitem, args: (1, 'x'), kwargs: {}

```

`bigbrother` can also embed itself recursively in your object by passing in argument `deepstate=True`.

## Callback

```python

def callback(obj, method, ref, call_args, call_kwargs):

    '''Callback called when object is mutated

    Args:

        obj (Any): The object being mutated via `method`

        method (str): The method called on the object (dunders removed)

        ref (Any): Reference object. If callback installed recursively, `ref` will be the entrypoint

        call_args (Tuple[Any]): Positional arguments that `method` was called with on `obj`

        call_kwargs (Dict[Any, Any]): Keyword arguments that `method` was called with on `obj`

    '''

```

## Supported types

### Builtins

Most builtin types are read-only and cannot have their method structure mutated, so we observe via replacement with thin wrappers. 

- `list` via `_ObservedList`

    - `append`

    - `clear`

    - `extend`

    - `insert`

    - `pop`

    - `remove`

    - `sort`

    - `__setattr__`

    - `__setitem__`

- `dict` via `_ObservedDict`

    - `clear`

    - `pop`

    - `popitem`

    - `update`

    - `__setattr__`

    - `__setitem__`

- `set` via `_ObservedSet`

    - `add`

    - `clear`

    - `difference_update`

    - `discard`

    - `intersection_update`

    - `pop`

    - `remove`

    - `symmetric_difference_update`

    - `update`

    - `__setattr__`

### Libraries

- `pydantic.BaseModel`