Implementation details¶

Architecture¶

The Architecture of Maloja tries to ensure:

Each distinct Use Case has a command to achieve it

Commands are invoked from the CLI, the Console or both as fits the Use Case

Each command is implemented in a separate module

Common operations against the API are the responsibility of a Broker module

Components of the Maloja toolkit

Common types¶

Maloja defines lightweight types for many things, including API tokens:

class maloja.types.Token(t, url, key, value)¶

Status messages:

class maloja.types.Status(id, job, path)¶

As well as other message types which we’ll see later on. There’s also a class to represent user plugins.

class maloja.types.Plugin(name, description, selector, workflow)¶: This data structure describes a Maloja plugin. It is the type expected by the maloja.plugin interface.

Common utilities¶

A small number of functions are used frequently for parsing, sorting and storing data.

maloja.workflow.utils.find_xpath(xpath, tree, namespaces={}, **kwargs)[source]¶

Find elements within an XML tree whose attributes match certain values.

Parameters:	xpath – an xpath query string. tree – xml.etree.ElementTree object. namespaces – a dictionary of namespace prefixes. kwargs – specifies attribute values to filter by.
Returns:	An iterator over valid elements.

maloja.workflow.path.find_ypath(path: maloja.workflow.path.Path, query, **kwargs)[source]¶

Find objects within the Maloja cache tree whose attributes match certain values.

Parameters:	path – search location in cache. query – an archetype of the object to look for. kwargs – specifies attribute values to filter by. If no keyword arguments are supplied, then attributes on the query object serve as criteria to be matched.
Returns:	An iterator over matching (path, object) tuples.

maloja.workflow.utils.group_by_type(items)[source]¶

Group a sequence of items by the type of item.

Returns:	A dictionary of lists. Keys in the dictionary are types.

Broker module¶

class maloja.broker.Broker(operations, results, *args, executor=None, loop=None, **kwargs)[source]¶

The Broker manages all Maloja’s interactions with the VMware API. It is responsible for taking messages from an operations queue and initiating an action for each one.

The Broker caches your API authorization token. It also maintains a requests session with the API.

The best way to create a Broker object is with the maloja.broker.create_broker() function.

tasks = {'operation_task': None}¶

A Broker is an active object. The tasks it runs in the background of your program are stored in this dictionary.

To wait for a Broker to finish takes code like this:

tasks = concurrent.futures.wait(set(broker.tasks.values()))

maloja.broker.create_broker(operations, results, max_workers=None, loop=None)[source]¶

Parameters:	operations – a queue object. Push operations to this queue. results – a queue object. Get results from this queue. max_workers – the number of threads to use in the executor pool. Leave this as None to get a sensible default value. loop – an asyncio loop object. Not implemented.
Returns:	A new Broker object

Messages¶

A broker object dispatches messages it finds in its operations queue. Examples of these are:

maloja.types.Survey

maloja.types.Design

maloja.types.Inspection

maloja.types.Stop

maloja.broker.handler(msg, session, token, results=None, status=None, **kwargs)[source]¶

The Broker provides this handler to dispatch messages it receives to functions which know how to execute them.

This design allows new modules to be implemented and to register functions for receipt of specific message types.

Every handler function receives these positional arguments:

Parameters:	msg – the message object. session – a requests.futures session object. token – an authorization Token for the VMware API. results – a queue object so your handler can send back status messages. status – the current status at the point your handler is invoked.

Surveyor module¶

The Surveyor is registered to run whenever a maloja.types.Survey message is received by the Broker.

class maloja.surveyor.Surveyor[source]¶

The Surveyor is responsible for exploring a virtual infrastructure. It starts at Org level and finds networks and Edge Gateways. It descends down through vDCs, via catalogs and vApps to Vms.

The Surveyor is a singleton; only one survey may run at a time. It is stateless; all necessary data is passed on from one task to the next, or else saved into YAML files.

Planner module¶

The planner module allows offline inspection of a design file.

A design file conforms to YAML syntax. It is made up of items from a survey (also YAML) assembled in a hierarchical structure.

You can test the module using one of the example files which come with your Maloja installation.

On Ubuntu 14.04:

$ ~/py3.4/bin/maloja @options.private plan --input=maloja/test/use_case01.yaml

On Windows 8.1:

> %USERPROFILE%\py3.5\Scripts\maloja @options.private plan --input=maloja/test/use_case01.yaml

Builder module¶

The Builder is registered to run whenever a maloja.types.Design message is received by the Broker.

class maloja.broker.Builder(objs, results, executor=None, loop=None, **kwargs)[source]¶

The Builder accepts a sequence of objects from the data model and uses them to construct new virtual infrastructure.

monitor(task, session, status=None, backoff=1)[source]¶: The builder launches this method whenever a VMware task is initiated. The method tracks the progress of the task.

__init__(objs, results, executor=None, loop=None, **kwargs)[source]¶

Parameters:	objs – a sequence of Maloja objects results – a queue to which status reports will be pushed executor – a concurrent.futures.Executor object

__call__(session, token, callback=None, status=None, **kwargs)[source]¶

A Builder is a callable object which runs in its own thread.

It gets started up like this:

executor.submit(builder, session, token, callback, status)

Parameters:	session – a requests.futures session object. token – an authorization Token for the VMware API. callback – a function to be called when the builder is done. status – the current status at the point the builder is invoked.

Inspector module¶

The Inspector is registered to run whenever a maloja.types.Inspection message is received by the Broker.

class maloja.inspector.Inspector(objs, results, executor=None, loop=None, **kwargs)[source]¶

The Inspector accepts a sequence of objects from the data model and uses them to check existing virtual infrastructure.

__init__(objs, results, executor=None, loop=None, **kwargs)[source]¶

Parameters:	objs – a sequence of Maloja objects results – a queue to which status reports will be pushed executor – a concurrent.futures.Executor object

__call__(session, token, callback=None, status=None, name=None)[source]¶

An Inspector is a callable object which runs in its own thread.

It gets started up like this:

executor.submit(inspector, session, token, callback, status)

Parameters:	session – a requests.futures session object. token – an authorization Token for the VMware API. callback – a function to be called when the inspector is done. status – the current status at the point the inspector is invoked. name – the name of the entity to be checked.