149 lines
4.1 KiB
Markdown
149 lines
4.1 KiB
Markdown
# 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. |