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 aSolaceAPI.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: 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_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
-