Skip to content

Machc Project

machc

The goal of the architect is to create a shape for the system that recognizes policy as the most essential element of the system while making the details irrelevant to that policy. This allows decisions about those details to be delayed and deferred.

— ©Robert C. Martin

Overview

The Machc Project is a modular and scalable framework specifically designed for building robust software solutions in Python. Leveraging the principles described in "Clean Architecture: A Craftsman's Guide to Software Structure and Design"1 and "Clean Architectures in Python"2, Machc provides long-term maintainability, flexibility, and adaptability for various business needs while ensuring modularity and separation of concerns.

Machc provides essential tools and components for managing core functionalities, including reusable entities, interactors, and adapters that developers can further customize for Python-based applications. Machc includes reference implementations for applications and MachcOn projects, enabling developers to create customizable, container-ready solutions designed for versatility and scalability.

Project Structure

A module should be responsible to one, and only one, actor.

— ©Robert C. Martin

This project adopts Python as its core development language, enabling flexibility, modularity, and scalability in alignment with Machanism principles. However, due to Python’s limitations with packaging, the structure of the Machc project differs from its counterpart, Macha (Java), and the originally announced multi-module organization.

  1. Root Namespace Limitation:
    Python packaging, via PyPI (Python Package Index), does not natively support a root project naming scheme like @machb.core (as seen in npm.js for JavaScript). This means that Python does not have a direct equivalent for organizing and naming packages under a single root namespace (e.g. @machb).

  2. Namespace Packages as a Solution: To address this limitation, the Machc project leverages namespace packages, which allow:

    • Organization and distribution of packages under a shared namespace (e.g. machc.user).
    • Separate installation of internal modules while maintaining a cohesive namespace structure.

  3. Adjusted Structure: Due to the lack of native support for a unified root namespace, the project’s directory layout and naming conventions are slightly modified compared to Macha (Java). The Machc project is structured into the following components:

  1. Core: An aggregator of the core logic and reusable components. It includes entities, interactors, and adapters necessary for creating modular applications. (see: Core)
  2. Apps: This layer contains project-specific assemblies that adapt the reusable core modules for specific workflows. This is the space for examples, reference implementations, and integration testing. (see: Apps)
  3. MachaOn: The Machc MachaOn Project (MachcOn) serves as the final step in transforming modular Machc components into deployable applications. Aligned with Clean Architecture principles, it offers a scalable and adaptable framework for deploying Python-based applications across a variety of environments, including containers, serverful, and serverless infrastructures. (see: MachaOn)

Tech Stack

Don’t marry the framework!

— ©Robert C. Martin

Machc’s architecture focuses on framework independence for maximum flexibility. The core modules use generic technologies that work across deployment styles, remaining adaptable whether targeting monolithic, microservices, or serverless environments.

Tech Stack

  • Python 3.x
  • Tools aligned with Clean Architecture principles (e.g., flask, fastapi).

Outer Layer Components

For the application and infrastructure layers, developers can use any appropriate tools and frameworks:

  • Web Frameworks: Django, Flask, FastAPI.
  • Cloud Services: AWS Lambda, Azure Functions.
  • Frontend Technologies: React, Angular, or Vue.js.
  • Database Integrations: PostgreSQL, MongoDB, and more.

Architecture

Machc project follows Clean Architecture1 2. Clean Architecture emphasizes modularity, testability, and independence, dividing software into layers to make it easier to scale and maintain.

Core Concepts of Clean Architecture:

  1. Independent of Frameworks: Frameworks are treated as tools, preventing them from dictating the design of the system.
  2. Testable: Business rules can be tested independently of UI, databases, or external elements.
  3. Independent of UI: Swapping the UI with another (e.g., console, web, mobile) does not impact business rules.
  4. Independent of Databases: The ability to change databases without requiring unnecessary modifications to business logic.
  5. Independent of External Agencies: The inner logic is resilient to changes or constraints imposed by external systems.

Layered Architecture in Machc:

  1. Outermost Layer (Frameworks and Drivers): UI, database, and infrastructure-specific details reside here.
  2. Interface Adapters: Controllers and gateways convert external data formats into structures usable by the inner layers.
  3. Application Business Rules: Encapsulates use cases and orchestrates entity interactions.
  4. Enterprise Business Rules (Entities): The innermost layer defining reusable and high-level organizational rules and policies.

Test

The tests are part of the system, and they participate in the architecture just like every other part of the system does. In some ways, that participation is pretty normal. In other ways, it can be pretty unique.

— ©Robert C. Martin

If you want to get serious about automated tests for your software there is one key concept you should know about: the test pyramid. Mike Cohn came up with this concept in his book Succeeding with Agile. It's a great visual metaphor telling you to think about different layers of testing. It also tells you how much testing to do on each layer.

Unit Test

Unit testing is a cornerstone of the Machc project’s commitment to reliability, maintainability, and modularity. By focusing on testing individual components in isolation, developers can ensure the correctness of core business logic and foundational layers, all while catching defects earlier in the development lifecycle.

Machc uses pytest, a powerful and versatile testing framework, to simplify the process of writing and executing unit tests. With intuitive syntax, plugin support, and detailed reports, pytest enables developers to deliver high-quality, thoroughly tested Python modules.

For complete information and advanced usage tips, refer to the pytest documentation3.

Anteater

Anteater is a manual, interactive testing tool designed as an External Accessor. Its purpose is to provide all possible methods for obtaining information and updating the state of a controlled system, similar to the tools developers use. These methods can include standard interfaces, legal workarounds, or developer backdoors.

How to Use Anteater in a Python Project

To use Anteater in a Python project, follow these steps with the standalone application version:

  1. Install Anteater: Follow the installation guide here: "Short Cut".
  2. Download Required Plugins: Obtain the necessary plugins for your project from the Anteater Plugins page.
  3. Run Anteater: Launch the Anteater standalone application by executing the ae.bat (Windows) or ae.sh ( Linux/Mac) file. For more details, refer to: Multi-Module Run.

For additional details, please visit: http://ganteater.com.

PyPI Repository

People who want to reuse software components cannot, and will not, do so unless those components are tracked through a release process and are given release numbers.

— ©Robert C. Martin

The Machc project adheres to a modular library structure for use in customer projects. This modularity ensures that components are reusable, scalable, and loosely coupled, minimizing dependencies and allowing for isolated modification and integration.

The PyPI repository is the official environment for publishing and distributing Python libraries. It serves as the primary source for hosting Machc libraries, ensuring they are accessible to developers worldwide. PyPI provides seamless integration and guarantees functionality and compatibility for production-ready libraries. Machc libraries are now available on PyPI, making it easy for developers to install, experiment, and incorporate them into their projects with confidence.

Using test.pypi.org as a Snapshot Repository

In addition to distributing production-ready libraries through pypi.org, the Machc project employs test.pypi.org as a snapshot repository to streamline development workflows and facilitate early-stage testing without impacting stable releases.

Versioning Scheme

  • X.X.X: Standard version format (e.g., 1.0.0, 2.3.1) strictly used for production-ready releases deployed to pypi.org. These versions represent libraries that have been verified and are stable for inclusion in live environments.
  • X.X.X.X: Snapshot version format (e.g., 1.0.0.1, 1.2.3.4) used for experimental or pre-release builds deployed to test.pypi.org. These versions are ideal for testing new features, fixes, or experimental changes before an official release.

Benefits of Using test.pypi.org

  1. Early Testing:
    Developers can publish snapshot releases of Machc libraries to test.pypi.org, enabling internal teams or early adopters to test enhancements and provide feedback.

  2. Separation of Environments:
    By using test.pypi.org for snapshots, production repositories remain clean and unaffected by experimental versions, maintaining their integrity for live systems.

  3. Snapshot Flexibility:
    The additional versioning level in X.X.X.X provides granular control for iterative testing without polluting the primary version history.

Publishing to test.pypi.org

The following command demonstrates publishing a library to test.pypi.org for snapshot versions:

python -m twine upload --repository testpypi dist/*

Installing from test.pypi.org

To install a snapshot version from test.pypi.org, use the following command with the --index-url flag:

pip install --index-url https://test.pypi.org/simple/ machc-library==1.0.0.1

This ensures that you fetch the snapshot version from test.pypi.org instead of the stable release from pypi.org.

Workflow Example

  • A snapshot version (1.0.0.1) is deployed to test.pypi.org after integrating a new feature in a library (e.g., machc-core).
  • Teams test and validate functionality using this pre-release version.
  • Once validated, the library is released as a stable version (1.0.0) on pypi.org.

Leveraging test.pypi.org for snapshots establishes a robust workflow by decoupling testing and production environments, enabling safer iteration and ensuring the stability of Machc libraries deployed to the global Python community.

References

  1. Clean Architecture: A Craftsman's Guide to Software Structure and Design ↩↩

  2. Clean Architectures in Python ↩↩

  3. Full pytest documentation ↩

  4. PyPI Guides ↩

https://www.free-Counters.org