Framework M
The complete metadata-driven business application framework for Python 3.12+.
Official Website: frameworkm.dev
📦 Metapackage: This is the primary Framework M package. Installing it gives you everything required to build applications. For individual components, see the Related Packages section.
Overview
Framework M is inspired by Frappe Framework but built with modern Python practices:
- Hexagonal Architecture: Clean separation via Ports & Adapters
- Async-First: Native asyncio with Litestar and SQLAlchemy
- Type-Safe: 100% type hints, mypy strict compatible
- Stateless: JWT/Token auth, no server-side sessions
- Metadata-Driven: Define DocTypes as Pydantic models
Installation
pip install framework-m
Or with uv:
uv add framework-m
Quick Start
1. Define a DocType
from framework_m import DocType, Field
class Todo(DocType):
"""A simple task document."""
title: str = Field(description="Task title")
description: str | None = Field(default=None, description="Task details")
is_completed: bool = Field(default=False, description="Completion status")
priority: int = Field(default=1, ge=1, le=5, description="Priority (1-5)")
2. Use the CLI
# Show version
m --version
# Show framework info
m info
# Start production server
m prod
# Start development server
m dev
Architecture & Features
Framework M follows a strict Ports & Adapters (Hexagonal) architecture. The core domain logic is isolated from infrastructure concerns.
- Primary Adapters: HTTP API (Litestar), CLI, WebSockets, Job Workers.
- Core Domain: DocTypes, Controllers, and Business Logic.
- Ports (Interfaces): Defined protocols for Repositories, Events, Storage, etc.
- Secondary Adapters: Implementations for PostgreSQL, Redis, S3, etc.
Key Capabilities:
- Automatic CRUD operations (
RepositoryProtocol) - Event-driven architecture (
EventBusProtocol) - Row-level security & permissions (
PermissionProtocol) - Background jobs (
JobQueueProtocol) - File storage abstraction (
StorageProtocol)
Technology Stack
- Web Framework: Litestar 2.0+
- ORM: SQLAlchemy 2.0 (Async)
- Validation: Pydantic V2
- Task Queue: Taskiq + NATS JetStream
- DI Container: dependency-injector
- Database: PostgreSQL (default), SQLite (testing)
- Cache: Redis
- Events: NATS JetStream
Development
# Clone and setup
git clone https://gitlab.com/castlecraft/framework-m.git
cd framework-m
# Install dependencies
uv sync --all-packages --all-extras --all-groups
# Run tests
uv run pytest
# Type checking
uv run mypy src/framework_m --strict
# Linting
uv run ruff check .
uv run ruff format .
Documentation
Related Packages
Framework M is split into modular packages:
| Package | Description |
|---|---|
framework-m |
This package - Metapackage with CLI, kernel, and re-exports |
framework-m-core |
Core protocols and dependency injection |
framework-m-standard |
Default adapters (SQLAlchemy, Redis, Litestar) |
framework-m-studio |
Visual DocType builder UI |
License
Apache 2.0 License - see LICENSE for details.
Acknowledgments
Inspired by Frappe Framework, reimagined with:
- Modern Python (3.12+, async/await, type hints)
- Clean architecture (Hexagonal/Ports & Adapters)
- No global state (Dependency Injection)
- Code-first schemas (Pydantic, not database JSON)
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file framework_m-0.14.4.tar.gz.
File metadata
- Download URL: framework_m-0.14.4.tar.gz
- Upload date:
- Size: 56.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
361ba7dd1411dbafc88c9415a8366a5279dd96c54704b90afb2bf82adc2a2ab0
|
|
| MD5 |
f7d5bc0de1f2b3e91e442055aa2ad26e
|
|
| BLAKE2b-256 |
1134a040c26081c2015b5d6edc0b0533fa17650414d320068d75d83d8766d4db
|
File details
Details for the file framework_m-0.14.4-py3-none-any.whl.
File metadata
- Download URL: framework_m-0.14.4-py3-none-any.whl
- Upload date:
- Size: 10.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
73e742d5dd408188840d3426a7d68273e08a5269e79b2e9d4c690b187b502eb2
|
|
| MD5 |
97bae1cf7d20c2ad84461b0fa9fa0e76
|
|
| BLAKE2b-256 |
b6a0fa9570f5428fbbef688e65885c577d3d48f5930395dca2f1e2ef1d9966d9
|
