Skip to content

Why Nameko?

Nameko is a framework for writing microservices in Python.

Microservices need to accept different types of messages, speak multiple protocols, and interface with different datastores. Ideally, they’d be able to do this with clear separation between the business logic and the machinery required to handle all those different protocols and interfaces.

Nameko aims to provide a structure and a best practice for creating microservices that are easy to understand, fast to develop, and very testable.

On top of that it includes utilities that make common use-cases easier to implement, like HTTP endpoints, asynchronous message handling, and more.

Example

A picture paints a thousand words, so here’s a simple example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from nameko.events import EventDispatcher, event_handler
from nameko.web.handlers import http


class ServiceA:
    """ Event dispatching service. """
    name = "service_a"

    dispatch = EventDispatcher()

    @http("PUT", "/dispatch")
    def dispatching_method(self, request):
        # business logic lives here
        self.dispatch("event_type", request.body)


class ServiceB:
    """ Event listening service. """
    name = "service_b"

    @event_handler("service_a", "event_type")
    def handle_event(self, payload):
        # business logic lives here
        print("service b received:", payload)

This snippet defines two services, ServiceA and ServiceB. When called with an HTTP PUT request, ServiceA dispatches an event that is handled asynchronously by ServiceB.

  • The machinery for handling the web request is all encapsulated into the @http entrypoint on line 11.
  • The machinery for dispatching the event (an AMQP message) is all encapsulated into the DispatchEvent dependency provider on line 9.
  • The machinery for receiving the event is all encapsulated into the @handle_event entrypoint on line 21.

The business logic for these services, if there was any, would live on lines 13 and 23. Crucically, the business logic doesn’t need to give any consideration to how this machinery works and is only concerned with the interface presented to it. This separation of concerns makes testing the business logic much simpler.

Extensions

Nameko facilitates the use of different protocols, datastores and other dependencies with the concept of Extensions.

Extensions are pieces of code or libraries that can be plugged into a Nameko service to provide an interface or access to a downstream dependency like a database or other service. There are two main types of Extension:

  • Entrypoints expose a service so it can be called, for example with an HTTP request
  • Dependency Providers let a service call a downstream service, like a database or another service.

The “built-in” Extensions

Nameko ships with a few Extensions built-in, so that it’s useful out of the box. These are the extensions that are used by the examples in these docs, but they’re the tip of the iceberg in terms of real-world Nameko usage.

The built-in extensions are:

  • An HTTP 1.1 entrypoint based on Werkzeug
  • An AMQP-based RPC implementation
  • An Event and Pub-Sub implementation for asynchonrous messaging over AMQP
  • A basic timer for periodic triggers

The Ecosystem

The pluggable nature of extensions means there are quite a few that have been developed by the open-source community. If you need to handle requests over a particular protocol, or communicate with a new database or 3rd party service, you might find what you need on PyPI.