Welcome to MasterPiece documentation!

Masterpiece - A Piece of Work

Masterpiece™ (Development Status 1 - Planning )

Try to be Nice

Welcome to the Masterpiece™ - Quite a Piece of Work!

For changes in this release, read CHANGELOG file, please.

Introduction

Masterpiece™ is a Python framework designed for creating modular, scalable, plugin-aware, multi-threaded, and object-oriented applications with a hierarchical structure. This hierarchical model is useful because in this universe the real world is inherently hierarchical; every object, from dishing machines to nuclear power plants, can be broken down into subparts. For other universes, you might find a framework that suits you better.

If you appreciate these design concepts, look no further. You’ve come to the right place!

Project Status and Current State

Here’s what is currently available:

  • Package Infrastructure: The basic Python package setup is in place, configured with ‘pyproject.toml’.

  • Early Drafts: Initial, yet fully working, versions of the essential core classes implemented.

  • Example application ‘examples/myhome.py’, which prints out its instance structure when run.

  • A separate plugin project named ‘masterpiece_plugin’ plugs in a ‘Hello World’ greeting to ‘myhome.py’, demonstrating a minimal yet fully functional plugin.

  • Absolutely bug-free (just kidding :)) — no known bugs remain, as far as I can tell.

In its current state, you might call the project a “Mission™” rather than a “Masterpiece™”, but we’re on our way from ‘Mission™’ to ‘Masterpiece™’!

Multi-threading

Multi-threading Python’s might make some devs raise an eyebrow, but I trust the community will sort that Global Interpreter Lock (GIL) out.

Goals

Have fun with learning the Python ecosystem! The ultimate enjoyment and a sprinkling of practicality will be achieved by cranking the Fun-O-Meter™ up to 11. Coding should feel like a rollercoaster ride—minus the screaming and the long lines.

  • First-Time Excellence: We aim to build a framework that’s reliable, correct, and efficient from the start. And fun—because, what’s a framework without a little joy?

  • Robustness: A minimal yet robust API providing developers with total control over everything.

  • Productivity: Totally reusable code to get maximum functionality with a minimum amount of code (read: money).

Packages

Masterpiece introduces two Python packages:

  1. Masterpiece (core framework): This is the core framework for building plugin-aware, multi-threaded applications. It includes a simple example application to get you started.

  2. Masterpiece Plugin (plugin example): This is a basic plugin example that demonstrates how to create third-party plugins for applications built using Masterpiece. It’s as simple as saying “Hello, World!”, literally.

Note: This project contains only the core framework. The plugin is provided as a separate project masterpiece_plugin.

Example Usage

Step 1: Install Masterpiece and run the example application

To install the core framework:

pip install masterpiece

Then, navigate to the example folder and run the application:

python examples/myapp.py

The application will print out its instance hierarchy. This is a minimal starting point for developing your own multi-threaded, plugin-based, scalable applications.

Example output:

home
    ├─ grid
    ├─ downstairs
    │   └─ kitchen
    │       ├─ oven
    │       └─ fridge
    └─ garage
        └─ EV charger

Step 2: Install the Masterpiece Plugin

To extend the application with the masterpiece_plugin:

pip install masterpiece_plugin

Run the application again:

python examples/myapp.py

You’ll now see a new object in the instance hierarchy, along with a friendly “Hello, World!” object.

Example output:

home
    ├─ grid
    ├─ downstairs
    │   └─ kitchen
    │       ├─ oven
    │       └─ fridge
    ├─ garage
    │   └─ EV charger
    └─ Hello World - A Plugin

The application also demonstrates the usage of startup arguments.

examples/myapp.py --init --solar 10
  • The --init argument tells the application to create configuration files for all classes in the application.

  • The --solar argument creates an instance of a solar power plant with a specified peak power of 10 kW.

By default, the configuration files are created in the config folder under your home directory. You can edit these files to modify the class attributes across the application.

To load a different configuration, use the --config [configname] argument. For example, --config simulation will use the configuration files stored in the ~/.myapp/simulation/ folder.

The HelloWorldPlugin class is a basic starting point for adding new features to your application.

Contributing

Contributions are welcome!

Please check out the Issue Board for tracking progress and tasks.

About the Project

The framework allows any payload to be integrated into this hierarchy, supporting configuration, serialization, the factory method pattern, a plugin API, and many other features commonly required when developing applications. Generic tree traversal functionality allows any interaction to be applied to the tree, from serialization to any application specific functionality.

Just like life on Earth, all components of this framework trace their lineage back to a single ancestor: the ‘masterpiece’ core. Evolution, but in code!

The name ‘Masterpiece’ was chosen to reflect a commitment to fine-grained modular design, with a touch of humor.

Developer Documentation

As a C/C++ boomer, Doxygen was naturally my tool of choice. However, I ditched it in favor of Python’s native tool, Sphinx. The migration wasn’t exactly pure joy — developed severe mental illness - but it’s all good now. The documentation is improving, though it will still require a few more hours (okay, days) of effort to become truly usable.

For full documentation and usage details, see the full documentation at Documentation Index. (the docs look like crap, sorry — I’m still unraveling Sphinx’s mysteries).

Special Thanks

Big thanks to the generous support of [Mahi.fi](https://mahi.fi) for helping bring this framework to life.

MIT License

Copyright (c) 2024, Juha Meskanen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

Contributing

Thank You!

Thank you in advance for your forthcoming contributions, whether they are bug fixes, documentation improvements, entirely new features, or simply feedback. Your efforts will be highly appreciated and will help turn this project from its current mission state into an actual masterpiece.

Design Patterns

Please read the developer documentation and understand the few design patterns before contributing. This will help ensure that your contributions align with the project’s design and goals. .. todo:: (okay, the documentation is currently lacking many essential chapters, add.)

Code Formatting

To help maintain consistent code formatting across different developers, we use ‘black’ python formatter, by Microsoft.

Strange, the formatter doesn’t seem to do that much, it doesn’t organize imports, doesn’t adjust docstring lenghts .. todo:: most likely I don’t know how to use it properly, read the docs.

Using Emacs and Makefile

Despite my attempts to fall in love with Eclipse, VSCode and other IDEs, I still find Emacs and Makefile the best tools for many of my workflows. So there is a Makefile in the root folder. For those old dogs who are like me

make help

Unit tests

Todo

write unit tests

CHANGELOG

[0.0.7] - (current)

  • Factory Method Pattern: instantiation methods unified into one.

  • Piece: abstract base class, acting as the elementary class from which all the other classes are derived from.

  • YamlFormat: new serialization format implemented, in addition to existing JsonFormat (a separate plugin project)

  • Logging improved: - to support both class and instance methods. Foo.log_error(…) and foo.error(…)

[0.0.6] - 26.10.2024

  • Code and Data Decoupling: Hardcoded print() methods have been removed from core classes and re-implemented using the new do() method.

  • ArgMaestro: A class for fully automated class attribute initialization through startup arguments. Allows any public class attribute to be initialized using the –classname_attributename [value] convention. The name is admittedly ridiculous and will likely be changed.

  • Unit Test Coverage Improved: Unit tests have been enhanced to a level where they provide meaningful test coverage.

  • Logging Typos Fixed: All strings have been proofread and typos corrected.

[0.0.5] - 20.10.2024

  • New startup argument –init: If given, all classes in the application will create configuration files for their class attributes, if those files don’t already exist. These configuration files allow users to define custom values for all public class attributes.

  • Rotating Logs: The FileHandler has been replaced with TimedRotatingFileHandler, initialized with parameters when=’midnight’, interval=1, and backupCount=7 to rotate the log file daily and keep 7 backup files. This change resolves the issue of log files growing indefinitely, which could eventually lead to the system running out of disk space.

  • Documentation refactored: All .rst files have been moved from Sphinx’s docs/source directory to the project root folder for GitLab compatibility.

  • Time functions: The methods ‘epoc2utc()’, ‘timestamp()’, ‘epoc2utc()’ and a few others removed. These were not actually methods of the Masterpiece class since they did not require any instance attributes. More importantly, this change aims to keep the Masterpiece framework focused on its core functionality.

[0.0.4] - October 18, 2024

  • MasterPiece: undefined class attribute ‘_class_id’, added.

  • MetaMasterPiece Refactored: Replaced with a more lightweight __init_subclass__() solution, with special thanks to Mahi for his contribution.

  • Plugin Class Abstracted: The plugin class is now subclassed from ABC to formally implement an abstract base class.

  • Pylint Warnings Resolved: Fixed issues such as long lines, which have been split for better readability.

  • Docstrings Improved: Added more comprehensive documentation with a professional tone for several methods.

[0.0.3] - October 12, 2024

  • From C++ boomer to Python professional: Directory structure simplified:

    • src folder removed

    • masterpiece/base folder renamed to masterpiece/core

    • plugins folder moved outside the project, will be implemented as a separate project (one project - one repository principle)

    • Minor additions and improvements to Docstrings.

[0.0.2] - October 10, 2024

  • GitLab Ready: Revised documentation tone slightly to reflect a more professional and serious nature. Removed excessive humor that may have detracted from the perceived professionalism of the toolkit.

-[0.0.1] - August 4, 2024

Pip release with Python pip package uploaded.

New Features and Improvements

  • Trademark Cool (not?) slogan: Masterpiece - Quite a piece of work

  • Plugin API: Enhanced the plugin API with two classes: ‘Plugin’ and ‘PlugMaster’ with compatibility with Python versions 3.8 and later. The most recent version tested is 3.12.

  • Meta-Class Automation: Per-class bureaucracy automated using Python’s meta-class concept.

  • Folder Structure: Redesigned for future expansion. There is now separate root folders for core and plugin modules.

  • Base Class: Added new base class for MasterPiece applications in base/application.py.

  • Example Application: Added examples/myhome.py to demonstrate the general structure of MasterPiece aapplications.

  • Startup Argument Parsing: Added API for parsing startup arguments.

  • Serialization API: Fully featured serialization with backward compatibility support implemented.

  • Documentation: Added comprehensive docstrings to numerous classes, aiming for fully documented professional Python code.

  • Type Annotations: Added type annotations to numerous previously non-typed method arguments, moving towards a fully typed Python code.

  • Sphinx conf.py: Created default Sphinx ‘conf.py’ file in masterpiece/sphinx folder.

  • Bug fixes and improvements:

    • Added encoding=”utf-8” to open() calls

    • Added exclude __pycache__ to MANIFEST.in, to avoid including the folders with the setup.

[0.0.0] - May 31, 2024

Initial, private release (minimal set of classes unified from the RTE and JUHAM Python applications)

  • Base Class Draft: Initial version of the MasterPiece and Composite classes.

  • Python Packaging: Python package infrastructure setup using pyproject.toml, installable via pip.

  • Documentation:

    • Added LICENSE, README, and other standard files in .rst format.

    • Developer documentation autogenerated with Sphinx toolset. Support for Doxygen dropped.

  • Project Name: Named the project ‘MasterPiece™’, with a note that ‘M’ currently stands for mission rather than masterpiece.

  • Miscellaneous: Some unconventional use of the Python programming language.

TODOs for MasterPiece

This will be an exceptionally well structured priorized list of TODOs:

  • Docstrings contain many TODO:s which Sphinx should pick up and include with this file. Does not, fix please.

  • The docs/conf.py file contains both masterpiece framework-specific and plugin-specific information (e.g., copyright and author). Copying the entire conf.py to every project built on masterpiece is a bad habit. Implement a base configuration class from which plugin developers can derive their own conf.py files, containing only plugin-specific info (DRY principle).

The following items have been extraced from the source code:

Todo

write unit tests

(The original entry is located in ../CONTRIBUTING.rst, line 44.)

Classes

Inheritance diagram of masterpiece.masterpiece, masterpiece.composite.Composite, masterpiece.application.Application, masterpiece.plugin.Plugin, masterpiece.plugmaster.PlugMaster, masterpiece.argmaestro.ArgMaestro, masterpiece.log.Log, masterpiece.treevisualizer.TreeVisualizer

Instances

Instances of these classes can be grouped into hierarchical structure to model real world apparatuses.

Instance Diagram

(Just a test to play with mermaid)

classDiagram class MainCompositeObject { MasterPiece1: MasterPiece SubCompositeObject: SubCompositeObject } class SubCompositeObject { SubMasterPiece1: MasterPiece SubMasterPiece2: MasterPiece } MainCompositeObject --> MasterPiece1 : contains MainCompositeObject --> SubCompositeObject : contains SubCompositeObject --> SubMasterPiece1 : contains SubCompositeObject --> SubMasterPiece2 : contains

Index