Welcome to libsolace’s documentation!

libsolace is a python library to manage the configuration of Solace messaging appliances. This project has a modular design which provides the basic features required to manage pairs of Solace Appliances.

Basics

Managed objects within Solace are managed through plugin.Plugin. Plugins are used to create SEMP requests, which can then be posted to the appliance through a SolaceAPI.SolaceAPI instance.

During the creation of SEMP requests, Plugins will enqueue the request in a instance of SolaceCommandQueue.SolaceCommandQueue which will also validate the request against the appropriate XSD for the version of SolOS-TR the appliance is running.

Example:

>>> import libsolace.settingsloader as settings
>>> from libsolace.SolaceAPI import SolaceAPI
>>> client = SolaceAPI("dev")
>>> list_requests = client.manage("NullPlugin", foo="bar", baz="jaz")
>>> type(list_requests)
<class 'libsolace.items.NullPlugin.NullPlugin'>
class libsolace.SolaceAPI.SolaceAPI(environment, version=None, detect_status=True, testmode=False, **kwargs)[source]

Connects to a Solace cluster’s primary and backup appliance(s)

a SolaceAPI instance contains a SolaceXMLBuilder and a SolaceCommandQueue in order to facilitate the generation of SEMP XML requests, enqueuing the XML requests, and sending them to the appliance(s) through the rpc(str) method.

SolaceAPI connects to both appliances in a redundant pair setup and gets the the primary and backup node states. Typically you issue the same SEMP command to both appliances. Commands can also be issued to either the primary or the backup appliance utilizing the primaryOnly and backupOnly kwargs. see: rpc()

The version of the SolOS-TR OS is detected on automatically, and this behaviour can be overridden with the version kwarg. If using the VMR you will want to pass in both detect_status=False and version=”soltr/7_1_1”.

Parameters:
  • environment (str) – the environemnt
  • detect_status (bool) – detection of node primary/backup status, pass True here for the VMR or single appliances.
  • version (str) – override appliance version detection. Some versions of SolOS-TR require you to set the language level a bit higher like the VMR for example.
  • testmode (bool) – Tells the api to connect using the READ_ONLY_USER as defined in the libsolace.yaml file.
Return type:

SolaceAPI.SolaceAPI

Returns:

instance

Examples:
>>> from libsolace.SolaceXMLBuilder import SolaceXMLBuilder
>>> api = SolaceAPI("dev")
>>> api.x = SolaceXMLBuilder("LOG: Showing the Message Spool in %s" % api.environment, version=api.version)
>>> api.x.show.message_spool.detail
OrderedDict()
>>> response = api.rpc(api.x)

Setting the API version if detection fails

>>> from libsolace.SolaceXMLBuilder import SolaceXMLBuilder
>>> api = SolaceAPI("dev", version="soltr/7_1_1")
>>> api.x = SolaceXMLBuilder("My description of what im doing", version=api.version)
>>> api.x.show.message_spool
OrderedDict()
>>> response = api.rpc(api.x, primaryOnly=True)
>>> response[0]['rpc-reply']['rpc']['show']['message-spool']['message-spool-info']['config-status']
u'Enabled (Primary)'

Query the backup appliance only

>>> from libsolace.SolaceXMLBuilder import SolaceXMLBuilder
>>> api = SolaceAPI("dev", detect_status=False)
>>> api.x = SolaceXMLBuilder("My Something something", version=api.version)
>>> api.x.show.version
OrderedDict()
>>> r = api.rpc(api.x, backupOnly=True)
>>> # check the response was the "configured" backup
>>> r[0]['HOST'] == settings.SOLACE_CONF["dev"]['MGMT'][1]
True

Get a instance of some plugin from the plugin manager

>>> api = SolaceAPI("dev")
>>> type(api.manage("NullPlugin"))
<class 'libsolace.items.NullPlugin.NullPlugin'>
get_memory()[source]

Returns the Memory Usage

Example of request XML <rpc semp-version=”soltr/6_0”>

<show>
<memory></memory>

</show>

</rpc>

get_message_spool(**kwargs)[source]

show message spool :param version:

get_redundancy()[source]

Return redundancy status

Example:
>>> api = SolaceAPI("dev")
>>> api.get_redundancy()[0]['rpc-reply']['rpc']['show']['redundancy']['config-status']
u'Enabled'
manage(plugin_name, **kwargs)[source]

Gets a plugin, configures it, then allows direct communication with it.

Plugins are passed the kwargs directly if any are specified.

Example:
>>> api = SolaceAPI("dev")
>>> p1 = api.manage("NullPlugin")
>>> p1.some_method("foo", bar="baz")
(('foo',), {'bar': 'baz'})
>>> p2 = api.manage("NullPlugin", a="a")
>>> p2.kwargs['a']
'a'
rpc(xml, allowfail=False, primaryOnly=False, backupOnly=False, xml_response=False, **kwargs)[source]

Execute a SEMP command on the appliance(s), call with a string representation of a SolaceXMLBuilder instance.

Args:

xml(str): string representation of a SolaceXMLBuilder instance. allowFail(Optional(bool)): tollerate some types of errors from the

appliance.

primaryOnly(Optional(bool)): only execute on primary appliance. backupOnly(Optional(bool)): only execute on backup appliance.

Returns:
data response list as from appliances. Json-like data
Example:
>>> from libsolace.SolaceXMLBuilder import SolaceXMLBuilder
>>> conn = SolaceAPI("dev")
>>> conn.x = SolaceXMLBuilder(version = conn.version)
>>> conn.x.show.version
OrderedDict()
>>> type(conn.rpc(str(conn.x)))
<type 'list'>
class libsolace.plugin.Plugin(*args, **kwargs)[source]

Bases: object

This is the plugin core object where all plugins should extend from and register too.

Plugin Example:

>>> import pprint
>>> import libsolace
>>> from libsolace.plugin import Plugin
>>> @libsolace.plugin_registry.register
>>> class Bar(Plugin):
>>>     plugin_name = "BarPlugin"
>>>     def __init__(self):
>>>         pass
>>>     # Instance methods work!
>>>     def hello(self, name):
>>>         print("Hello %s from %s" % (name, self))
>>>     # Static methods work too!
>>>     @staticmethod
>>>     def gbye():
>>>         print("Cheers!")
>>> libsolace.plugin_registry('BarPlugin').hello("dude")
>>> libsolace.plugin_registry('BarPlugin').gbye()
>>> pprint.pprint(dir(libsolace.plugin_registry('BarPlugin')))

Plugin Instantiation:

>>> import libsolace.settingsloader as settings
>>> from libsolace.SolaceAPI import SolaceAPI
>>> api = SolaceAPI("dev")
>>> my_plugin = api.manage("NullPlugin")
>>> type(my_plugin)
<class 'libsolace.items.NullPlugin.NullPlugin'>

Direct Instantiation:

>>> import libsolace.settingsloader as settings
>>> import libsolace
>>> my_clazz = libsolace.plugin_registry("NullPlugin", settings=settings)
>>> my_instance = my_clazz(settings=settings)
exists = False
plugin_name = 'Plugin'

the plugin’s name, override this in the derived class!

plugins = [<class 'libsolace.items.NullPlugin.NullPlugin'>, <class 'libsolace.items.SolaceACLProfile.SolaceACLProfile'>, <class 'libsolace.items.SolaceUser.SolaceUser'>, <class 'libsolace.items.SolaceUsers.SolaceUsers'>, <class 'libsolace.items.SolaceVPN.SolaceVPN'>, <class 'libsolace.items.SolaceQueue.SolaceQueue'>, <class 'libsolace.plugins.NamingStandard.NamingStandard'>, <class 'libsolace.plugins.ZoinksNamingStandard.ZoinksNamingStandard'>, <class 'libsolace.items.SolaceClientProfile.SolaceClientProfile'>, <class 'libsolace.plugins.Utilities.Utilities'>, <class 'libsolace.plugins.InfluxDBClient.InfluxDBClient'>, <class 'libsolace.plugins.YAMLClient.YAMLClient'>]
plugins_dict = OrderedDict([('NullPlugin', <class 'libsolace.items.NullPlugin.NullPlugin'>), ('SolaceACLProfile', <class 'libsolace.items.SolaceACLProfile.SolaceACLProfile'>), ('SolaceUser', <class 'libsolace.items.SolaceUser.SolaceUser'>), ('SolaceUsers', <class 'libsolace.items.SolaceUsers.SolaceUsers'>), ('SolaceVPN', <class 'libsolace.items.SolaceVPN.SolaceVPN'>), ('SolaceQueue', <class 'libsolace.items.SolaceQueue.SolaceQueue'>), ('NamingStandard', <class 'libsolace.plugins.NamingStandard.NamingStandard'>), ('ZoinksNamingStandard', <class 'libsolace.plugins.ZoinksNamingStandard.ZoinksNamingStandard'>), ('SolaceClientProfile', <class 'libsolace.items.SolaceClientProfile.SolaceClientProfile'>), ('Utilities', <class 'libsolace.plugins.Utilities.Utilities'>), ('InfluxDBClient', <class 'libsolace.plugins.InfluxDBClient.InfluxDBClient'>), ('YAMLClient', <class 'libsolace.plugins.YAMLClient.YAMLClient'>)])
register(object_class, *args, **kwargs)[source]

Registers a object with the plugin registry, typically used as a decorator.

Parameters:object_class – the class to register as a plugin
Example:
>>> @libsolace.plugin_registry.register
>>> class Foo(Plugin)
>>> ...
set_exists(state)[source]

set_exists is used as caching in order to cut down on SEMP queries to validate existence of items. For example, if you create a new VPN in “batch” mode, After the “create-vpn” XML is generated, set_exists is set to True so subsequent requests decorated with the only_if_exists will function correctly since set_exists states that the object will exist.

Parameters:state (bool) – the existence state of the object
Returns:
class libsolace.plugin.PluginClass[source]

Bases: type

This is a metaclass for construction only, see Plugin rather

class libsolace.plugin.PluginResponse(xml, **kwargs)[source]

Bases: object

Encapsulating class for holding SEMP requests and their accompanying kwargs.

Example:

>>> request = PluginResponse('<rpc semp-version="soltr/7_1_1"><show><memory/></show></rpc>', primaryOnly=True)
>>> request.xml
'<rpc semp-version="soltr/7_1_1"><show><memory/></show></rpc>'
kwargs = None

the kwargs

xml = None

the XML

Indices and tables