MoleculerPy
MoleculerPy is a fast, modern and powerful microservices framework for Python. It helps you to build efficient, reliable & scalable services. MoleculerPy provides many features for building and managing your microservices.
Website: https://moleculerpy.services
Documentation: https://moleculerpy.services/docs
What's included
- Async/await native (built on asyncio)
- Request-reply concept
- Support event driven architecture with balancing
- Built-in service registry & dynamic service discovery
- Load balanced requests & events (round-robin, random, cpu-usage, latency, sharding)
- Many fault tolerance features (Circuit Breaker, Bulkhead, Retry, Timeout, Fallback)
- Plugin/middleware system (19 built-in middlewares)
- Support Streams for large data transfer
- Service mixins
- Built-in caching solution (Memory, Redis)
- Pluggable loggers (structlog)
- Pluggable transporters (NATS, Redis, Memory)
- Pluggable parameter validator
- Multiple services on a node/server
- Master-less architecture, all nodes are equal
- Built-in metrics feature with Prometheus exporter
- Built-in tracing feature with Console exporter
- Official REPL and Channels modules
Installation
pip install moleculerpy
With optional features:
# With Redis transporter
pip install moleculerpy[redis]
# With metrics & tracing
pip install moleculerpy[metrics,tracing]
# All features
pip install moleculerpy[all]
Create your first microservice
This example shows you how to create a small service with an add action which can add two numbers and how to call it.
import asyncio
from moleculerpy import ServiceBroker, Service, action, Context
# Define a service
class MathService(Service):
name = "math"
@action
async def add(self, ctx: Context):
return ctx.params["a"] + ctx.params["b"]
async def main():
# Create a broker
broker = ServiceBroker()
# Register the service
await broker.register(MathService())
# Start the broker
await broker.start()
# Call service
result = await broker.call("math.add", {"a": 5, "b": 3})
print(f"5 + 3 = {result}")
# Stop broker
await broker.stop()
asyncio.run(main())
Command Line Interface
MoleculerPy includes a CLI that allows you to easily start a broker and load services:
moleculerpy <service_directory> [options]
CLI Options
| Option | Description | Default |
|---|---|---|
service_directory |
Path to directory containing service files | - |
--broker-id, -b |
Broker ID | node-<current_dir_name> |
--transporter, -t |
Transporter URL | nats://localhost:4222 |
--log-level, -l |
Log level | INFO |
--log-format, -f |
Log format (PLAIN, JSON) | PLAIN |
--namespace, -n |
Service namespace | default |
Example
# Start with services from the 'services' directory
moleculerpy services
# Custom broker ID and transporter
moleculerpy services -b my-broker -t nats://nats-server:4222
# Verbose logging
moleculerpy services -l DEBUG
Official modules
We have official modules for MoleculerPy:
| Module | Description |
|---|---|
| moleculerpy-repl | Interactive CLI shell for debugging and managing services |
| moleculerpy-channels | Reliable pub/sub messaging with Redis, Kafka, NATS |
Middlewares
MoleculerPy provides a powerful middleware system to extend functionality. Middlewares can hook into various stages of request, event, and lifecycle processes.
from moleculerpy.middleware import Middleware
from moleculerpy.context import Context
class LoggingMiddleware(Middleware):
async def local_action(self, next_handler, action_endpoint):
async def wrapped_handler(ctx: Context):
print(f"Before action: {action_endpoint.name}")
result = await next_handler(ctx)
print(f"After action: {action_endpoint.name}")
return result
return wrapped_handler
# Register middleware
broker = ServiceBroker(middlewares=[LoggingMiddleware()])
Available Hooks
Wrapping Hooks
local_action(next_handler, action_endpoint)- Wraps local action handlersremote_action(next_handler, action_endpoint)- Wraps remote action callslocal_event(next_handler, event_endpoint)- Wraps local event handlers
Lifecycle Hooks
broker_created(broker)- Called after broker initializationbroker_started(broker)- Called after broker startupbroker_stopped(broker)- Called after broker shutdownservice_created(service)- Called after service registrationservice_started(service)- Called after service startup
Roadmap
Current status (v0.14.22)
- Core framework with full service lifecycle
- 7 Transporters: NATS, Redis/Valkey, Memory, MQTT, AMQP, Kafka, TCP+Gossip (P2P)
- 4 Serializers: JSON, MsgPack, CBOR (-29% vs JSON), ProtoBuf (-25% vs JSON)
- TCP Transporter — peer-to-peer without external broker, Gossip protocol for discovery
- Service versioning —
v1.users.get,v2.users.getcoexistence,$noVersionPrefix - Pluggable serializers (JSON, MsgPack) — MsgPack 2x faster on large payloads
- Balanced request/event handling via NATS queue groups (
disable_balancer=True) - 4/4 transit middleware hooks (publish, send, receive, message handler)
- 22 built-in middlewares
- 6 load balancing strategies (including Shard)
- Circuit breaker, bulkhead, retry patterns
- Pluggable metrics (Console, Prometheus) & tracing (Console, Event, Jaeger, Zipkin)
- Pluggable validators (BaseValidator + DefaultValidator)
- LRU memory cacher with eviction
- $node service (7 actions), broker.mcall(), ping, health check
- Streaming support
- Protocol v4 safety: version check, NodeID conflict detection
- REPL (18 commands) & Channels (Redis, NATS) modules
- API Gateway (moleculerpy-web v0.1.0)
Planned features
- TCP transporter TLS/shared_secret security
- CBOR + ProtoBuf serializers
- Database adapters (moleculerpy-db)
- GraphQL gateway
- gRPC support
Documentation
You can find the documentation at https://moleculerpy.services/docs.
Changelog
See CHANGELOG.md.
Contributing
We welcome you to join in the development of MoleculerPy. Please read our contribution guide.
Credits
This project is based on pylecular by Alvaro Inckot, licensed under MIT License.
Inspired by Moleculer.js - the original Node.js microservices framework.
License
MoleculerPy is available under the MIT license.
Contact
Copyright (c) 2026 MoleculerPy
Metadata
Release files for moleculerpy 0.14.22
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| moleculerpy-0.14.22.tar.gz | 1.3 MB | With provenance | Details for moleculerpy-0.14.22.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| moleculerpy-0.14.22-py3-none-any.whl | Python 3 | none | any | Details for moleculerpy-0.14.22-py3-none-any.whl |
Total release size: 1.6 MB
Release files / moleculerpy-0.14.22.tar.gz
| Download URL | moleculerpy-0.14.22.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
40d45d393d9ec0038a476f4d0e17f02ef60c492417974fff52edfa768de50d0e
|
|
BLAKE2b-256 checksum How to use checksums |
ed0587229562fe030920a6b7d697d0e3e96d1252d2a714cae11b050fb23c15b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 9, 2026.
Transparency logRelease files / moleculerpy-0.14.22-py3-none-any.whl
| Download URL | moleculerpy-0.14.22-py3-none-any.whl |
|---|---|
| Size | 307.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
26076ff81dd5d8e5b38a0159164c53b12440d6bf9b9c23a4fa891c53d8597fb4
|
|
BLAKE2b-256 checksum How to use checksums |
4417e18728a88966d15bb16e43913da6d2efbd714e629383e868f90bdc94bdba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 9, 2026.
Transparency logSecurity for moleculerpy 0.14.22
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for moleculerpy-0.14.22.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.