Skip to main content

MoleculerPy

CI PyPI version Python versions codecov License

🌐 Language / Язык: English | Русский

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 handlers
  • remote_action(next_handler, action_endpoint) - Wraps remote action calls
  • local_event(next_handler, event_endpoint) - Wraps local event handlers

Lifecycle Hooks

  • broker_created(broker) - Called after broker initialization
  • broker_started(broker) - Called after broker startup
  • broker_stopped(broker) - Called after broker shutdown
  • service_created(service) - Called after service registration
  • service_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.get coexistence, $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

@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)

Source distribution for moleculerpy 0.14.22
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)

Table of built distributions (wheels) for moleculerpy 0.14.22
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page