Code Generation

Significant portions of nucleon.amqp are code generated from various AMQP specifications and templates.

The actual specifications used are:

  • amqp0-9-1.extended.xml from RabbitMQ’s protocol docs - all the objects defined in AMQP plus several defined for RabbitMQ extensions. Note that this has actually been modified to address one or two errata.
  • amqp-rabbitmq-0.9.1.json, part of rabbitmq-codegen

In principle the JSON document could be eliminated as I believe the XML file contains a superset of information, eg. documentation that is used in docstrings.

The templates used are in templates/.

How to run the code generation

Simply run:

$ make

in the root of the project. This should clone the rabbitmq-codegen Mercurial repo if it does not already exist locally.

This ultimately invokes a method in codegen.py to generate each of the necessary files.

What is generated

The output of the code generation are two files spec.py and spec_exception.py.

nucleon/amqp/spec.py

spec.py contains classes corresponding to all of the method frames in the AMQP specification.

Each frame has these properties and methods:

class Frame
METHOD_ID

A numeric constant; the ID of the type of frame as it appears on the wire.

name

A string that is the protocol-level name of the frame, eg. queue.declare-ok

has_content

Whether or not the frame has content, ie. a message. Such a frame is followed on the wire by a properties/header frame and then zero or more payload frames.

static decode(buffer)

Decode an instance of the frame from the data encoded in buffer.

encode()

Encode the frame instance. This returns an iterable of tuples of the form (frame_type, payload).

Because Frame classes are intended for performance and are not expected to be subclasses, they define appropriate __slots__ and therefore do not possess an instance dictionary.

Also defined in spec.py are functions for encoding and decoding message properties:

nucleon.amqp.spec.decode_basic_properties(buffer)[source]
nucleon.amqp.spec.encode_basic_properties(body_size, props)[source]

Finally, and most importantly, there is defined the FrameWriter abstract class, which defines all of the AMQP methods as method calls.

@nucleon.amqp.spec.syncmethod(*responses)[source]

This decorator is used to add blocking semantics to FrameWriter methods that are defined as synchronous. Synchronous methods are not invoked directly, but are instead passed to self._call_sync with the responses specified in the decorator.

class nucleon.amqp.spec.FrameWriter[source]

Interface for converting AMQP client method calls to AMQP frames.

The underlying transport is not defined here; subclasses can implement this by defining ._send() and ._send_message() to encode the frame and ultimately write it to the wire.

_send(frame)[source]
_send_message(frame, headers, payload)[source]
_call_sync(method, responses, *args, **kwargs)[source]

Hook for making a method call synchronous.

Subclasses should re-implement this method to call method in such a way that the client will receive one of the methods in responses as a response.

nucleon/amqp/spec_exceptions.py

This file contains exceptions for each of the error codes defined in the specification.

Table Of Contents

Previous topic

Glossary

This Page