# MyUtils Project

## Overview

The **MyUtils** project is a Python library providing utilities to enhance Python objects, enabling features like
dynamic property access and observability of attributes. The library is designed to modify and extend the behavior of
objects in an easy-to-use and modular way, making it more developer-friendly.

---

## Modules

### 1. **Observable**

The `Observable` module provides functionality to track changes to object attributes and notify observers when a change
occurs.

#### Key Features:

- Transform ordinary objects into observable objects using `make_observable`.
- Attach one or more callbacks to specific attributes using `bind`.
- Callbacks receive both the old and new values of the attribute.
- Supports multiple observers on the same attribute and independent observers on different instances.

#### Key Classes/Functions:

- `make_observable(object)`:
  Makes an object observable by internally managing attribute listeners.
- `bind(object, attribute, callback)`:
  Adds a callback function to an observable object's attribute. The callback is triggered when the attribute value
  changes.
- Exception: `NotObservableError` is raised if you attempt to bind a callback to a non-observable object.

#### Example Usage:

Here is an example using the `Observable` module:

```python
from myutils.observable import make_observable, bind


class Demo:
  def __init__(self):
    self.number = 1


demo = Demo()
make_observable(demo)

# Bind a callback to 'number'
bind(demo, 'number', lambda old, new: print(f"Changed from {old} to {new}"))

# Updating an attribute triggers the callback
demo.number = 42  # Output: Changed from 1 to 42
```

---

### 2. **Expando**

The `Expando` module provides a dynamic wrapper for dictionaries, enabling access to dictionary values as object-style
properties.

#### Key Features:

- Access nested dictionary keys using dot notation (`.`).
- Dynamically add new properties.
- Handle `None` values seamlessly without breaking functionality.
- Gather lists of values from arrays in nested data structures.

#### Key Classes/Functions:

- **`Expando`**:
  A class-based wrapper for dictionaries allowing dynamic access and property management.

#### Example Usage:

Here is an example using the `Expando` module:

```python
from myutils.Expando import Expando

data = {
    "key1": 10,
    "key2": {"subkey": "value"}
}

exp = Expando(data)

# Access properties dynamically
print(exp.key1)  # Output: 10
print(exp.key2.subkey)  # Output: value

# Dynamically add a new key
exp.new_key = "new_value"
print(exp.new_key)  # Output: new_value
```

---

## Project Structure

To understand the file organization, here's the structure of the project:

```python
"""
MyUtils
├── src
│   └── myutils
│       └── __init__.py         # Main package initialization
├── tests
│   ├── __init__.py             # Test package initialization
│   ├── test_observable.py      # Tests for Observable module
│   └── test_expando.py         # Tests for Expando module
├── .gitignore                  # Git ignore file
├── main.py                     # Application entry point
├── requirements.txt            # Project dependencies
└── README.md                   # Project description (this file)
"""
```

---

## Contributing

If you'd like to contribute:

1. Fork the repository.
2. Create a feature branch (`git checkout -b feature/your-feature`).
3. Commit your changes (`git commit -m "Add some feature"`).
4. Push to the branch (`git push origin feature/your-feature`).
5. Open a Pull Request.

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## Maintainers

For any inquiries or support, feel free to contact the maintainer:

- **Name**: [Your Name Here]
- **Email**: [your-email@example.com]
- **GitHub**: [Your GitHub Profile](https://github.com/your-profile)

---

## Acknowledgments

Special thanks to the Python and open-source community for their tools, inspiration, and support.

## Release History

* 0.1.0 : Initial release
* 0.2.0 : Observable results can be collected using `collect_return_values`