Initial commit

README.md

@@ -0,0 +1,149 @@
+# 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
+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.