Custom implementation of the dataclass module from the standard Python library as a base class for other dataclasses.
The documentation is available here.
A while back I was working on a project (now lost in a dusty corner of my GitHub profile) that required me to create a lot of data structures (variables used only to hold complex data) and I quickly realised that using dictionaries (or named dictionaries) was slowly becoming messy because:
- dictionaries are mutable
- dictionary keys are strings and there's no easy way to set a default value for a key
- there's no way to ensure that a dictionary is well-formed
- complex attributes that are needed once or twice cannot be generated on the fly and must be stored in the dictionary
After a quick Google-fu session, I found out the existence of the dataclass decorator, swiftly provided by the dataclasses. This decorator allows you to create a class that is used only to hold data, and it provides a lot of useful features, such as:
- default values for attributes
- pre-determined methods (such as
__init__,__repr__, etc.)
However, it does not handle easily features like:
- complex attributes (i.e. attributes that are dataclasses themselves)
- nested dataclasses (i.e. a dataclass that has another dataclass as an attribute)
- serialization and deserialization
- hashing and equality
- type checking
- inheritance
All these were important for the project (which once again will be finished, one day) and so I decided to create a custom class that would handle all these features.
I chose to create a class (and not a decorator) because I wanted to be able to inherit from it and to be able to use it as a base class for other dataclasses, thus solving the aforementioned problems.
- default values for attributes
- type checking (can be deactivated)
- nested dataclasses (i.e. a dataclass that has another dataclass as an attribute)
- frozen dataclasses
- a dataclass cannot be modified after its creation (if the parameter
frozenis set toTrue, as per default) - otherwise, a dataclass can be manually frozen using the
freezemethod
- a dataclass cannot be modified after its creation (if the parameter
- equality comparison (via the
__eq__method) - hashing (via the
__hash__method) - full support inheritance
- full support for methods overriding and custom properties
The package is available on PyPI and can be installed using pip:
pip install -u customdataclassExamples can be found in the examples folder, both in a text file EXAMPLES.md and in a set of Python scripts.
Unit tests can be found in the tests folder.
Currently, the code coverage for unit tests is close to 100%.
To run the tests, simply run the following command from the root folder of the project:
python3 -m unittest discover -v -s ./tests -p "test*.pyIf you're using VScode, you can also use the Run Tests command from the Python Test Explorer for Visual Studio Code extension.
To compute the coverage, simply run the following commands from the root folder of the project:
coverage run -m unittest discover -s ./tests -p "test*.py"coverage report -mto see the report in the terminalcoverage htmlto see format the report in HTML and see it in the browser
Documentation can be found in the docs folder of the repo and on this page.
To build the documentation, simply run the following command from the src folder of the project:
pdoc --html -o ../docs customdataclass.py --forcePull requests, bug reports and feature requests are more than welcome!
Thank you for your interest in this silly little project of mine!
This project is licensed under the MIT License - see the LICENSE.md file for details