Metadata-Version: 2.4
Name: msb_arch
Version: 0.3.2
Summary: Mega-Super-Base (MSB) architecture for flexible and extensible Python applications
Project-URL: Homepage, https://github.com/Torward1024/MSB
Project-URL: Documentation, https://github.com/Torward1024/MSB/docs
Project-URL: Repository, https://github.com/Torward1024/MSB
Project-URL: Issues, https://github.com/Torward1024/MSB/issues
Author-email: Alexey Rudnitskiy <almax1024@gmail.com>
License: MSB Software License
        
        The Mega-Super-Base (MSB) software is provided under the following terms:
        
        1. Non-Commercial and Research Use:
           You are free to use, copy, modify, and distribute this software for non-commercial purposes, including academic research, personal projects, and open-source software, provided that:
           - You include this license and copyright notice in all copies or substantial portions of the software.
           - You provide appropriate credit to the original author.
        
        2. Commercial Use:
           Commercial use of this software, including integration into commercial products or services, requires a separate commercial license. For commercial licensing, contact the author at almax1024@gmail.com.
        
        3. No Warranty:
           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 non-infringement.
        
        4. Copyright:
           Copyright (c) 2025 Alexey Rudnitskiy. All rights reserved.
        
        For inquiries regarding commercial licensing, contact almax1024@gmail.com.
License-File: LICENSE
Keywords: architecture,extensible,msb
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# MSB Architecture

[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MSB%20Software%20License-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.3.2-orange.svg)](https://github.com/Torward1024/MSB)

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

```bash
pip install msb_arch
```

## Quick Start

```python
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/serializable.py), [`src/msb_arch/base/baseentity.py`](src/msb_arch/base/baseentity.py), [`src/msb_arch/base/basecontainer.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/super.py), [`src/msb_arch/super/project.py`](src/msb_arch/super/project.py) - operation handlers and project management.
- **Mega**: [`src/msb_arch/mega/manipulator.py`](src/msb_arch/mega/manipulator.py) - central orchestrator for operations.
- **Utils**: [`src/msb_arch/utils/logging_setup.py`](src/msb_arch/utils/logging_setup.py), [`src/msb_arch/utils/validation.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`](docs/api.md).

## Examples

Practical usage examples are available in [`docs/examples.md`](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:

```bash
pip install -e .
```

Then run the tests:

```bash
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`](CHANGELOG.md). Known issues that
have not been addressed yet are tracked in [`docs/ROADMAP.md`](docs/ROADMAP.md).

## License

MSB is licensed under the [MSB Software License](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](mailto:almax1024@gmail.com) for details.

## Contacts

- **Author**: Alexey Rudnitskiy
- **Email**: [almax1024@gmail.com](mailto:almax1024@gmail.com)
- **Repository**: [https://github.com/Torward1024/MSB](https://github.com/Torward1024/MSB)
- **Version**: 0.3.2