MSB Architecture

Mega-Super-Base (MSB) - a flexible and extensible architecture for Python applications, providing a modular system for managing entities, containers, operations, and projects with built-in type safety, serialization, and logging.

Features

• Typed Entity Management: Automatic attribute validation and serialization.
• Containers for Collections: Support for queries and bulk operations on entities.
• Flexible Operation System: Through Super-classes with method resolution.
• Projects as High-Level Containers: High-level data organization.
• Universal Serialization: Support for nested objects and cyclic references.
• Integrated Logging and Validation: Logging through a dedicated msb_arch logger that stays silent until the application configures it, plus data validation.
• No External Dependencies: Requires only Python >= 3.12.

Installation

pip install msb_arch

Quick Start

from msb_arch.base.baseentity import BaseEntity
from msb_arch.super.project import Project

class MyEntity(BaseEntity):
    value: int

class MyProject(Project):
    _item_type = MyEntity

    def create_item(self, item_code: str = "ITEM_DEFAULT", isactive: bool = True) -> None:
        item = MyEntity(name=item_code, isactive=isactive, value=42)
        self.add_item(item)

project = MyProject(name="MyProject")
project.create_item("item1")
print(project.get_item("item1").to_dict())
# Output: {'name': 'item1', 'isactive': True, 'type': 'MyEntity', 'value': 42}

restored = MyProject.from_dict(project.to_dict())
print(restored.get_item("item1").value)
# Output: 42

Architecture

The project is divided into 4 modules:

• Base: src/msb_arch/base/serializable.py, src/msb_arch/base/baseentity.py, src/msb_arch/base/basecontainer.py - shared machinery plus the entity and container surfaces.
• Super: src/msb_arch/super/super.py, src/msb_arch/super/project.py - operation handlers and project management.
• Mega: src/msb_arch/mega/manipulator.py - central orchestrator for operations.
• Utils: src/msb_arch/utils/logging_setup.py, src/msb_arch/utils/validation.py - utilities for logging and validation.

Main classes:

• Serializable: Shared base holding validation, serialization, caching and ownership.
• BaseEntity: An object addressed by its attributes.
• BaseContainer[T]: A named collection, sibling of BaseEntity rather than a subclass.
• Super: Abstract class for operation handlers with method resolution.
• Project: Class for managing projects as entity containers.
• Manipulator: Central class for operation registration and request processing.

API

Complete API reference is available in docs/api.md.

Examples

Practical usage examples are available in docs/examples.md.

Testing

The project includes a complete set of unit, integration, and performance tests using pytest. Tests are located in the tests/ directory and cover all modules with high coverage rates.

The tests import msb_arch rather than the source tree, so they run against whatever is installed. Install the package first:

pip install -e .

Then run the tests:

pytest tests/

CI builds the wheel and installs it before running the same suite, so the distribution that ships is the one that was tested.

Changelog

Release history and upgrade notes are in CHANGELOG.md. Known issues that have not been addressed yet are tracked in docs/ROADMAP.md.

License

MSB is licensed under the MSB Software License for non-commercial and research use, allowing free use, modification, and distribution for non-commercial purposes with attribution.

For commercial use, a separate royalty-bearing license is required. Please contact almax1024@gmail.com for details.

Contacts

• Author: Alexey Rudnitskiy
• Email: almax1024@gmail.com
• Repository: https://github.com/Torward1024/MSB
• Version: 0.3.0