MyUtils/README.md

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:

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:

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:

"""
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 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

---

Acknowledgments

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