Library¶

The public API of the Warthog library is maintained in the warthog.api module. This is done for the purposes of clearly identifying which parts of the library are public and which parts are internal.

Functionality in the warthog.client, warthog.config, warthog.transport, and warthog.exceptions modules is included in this module under a single, flat namespace. This allows a simple and consistent way to interact with the library.

Note

When using the library, always make sure to access classes and functions through the warthog.api module, not each individual module.

warthog.client¶

Simple interface for a load balancer with retry logic and intelligent draining of nodes.

class warthog.client.WarthogClient(scheme_host, username, password, verify=None, ssl_version=None, network_retries=None, commands=None)[source]¶

Client for interacting with an A10 load balancer to get the status of nodes managed by it, enable them, and disable them.

This class is thread safe.

Changed in version 0.8.0: Removed .disabled_context() method.

__init__(scheme_host, username, password, verify=None, ssl_version=None, network_retries=None, commands=None)[source]¶

Set the load balancer scheme/host/port combination, username and password to use for connecting and authenticating with the load balancer.

Whether or not to verify certificates when using HTTPS may be toggled via the verify parameter. This can enable you to use a self signed certificate for the load balancer while still using HTTPS.

The version of SSL or TLS to use may be specified as a ssl module protocol constant via the ssl_version parameter.

The maximum number of times to retry network operations on transient errors can be specified via the network_retries parameter.

If the command factory is not supplied, a default instance will be used. The command factory is responsible for creating new requests.Session instances to be used by each command. It is typically only necessary to override this for unit testing purposes.

Changed in version 0.9.0: Added the optional verify parameter to make use of self-signed certs easier.

Changed in version 0.10.0: Added the optional ssl_version parameter to make use of alternate SSL or TLS versions easier.

Changed in version 2.0.0: Added the optional network_retries parameter to make use of retry logic on transient network errors. A non-zero number of retries is used by default if this is not specified. Previously, no retries were attempted on transient network errors.

Changed in version 2.0.0: Removed the optional wait_interval parameter. This is now passed directly as an argument to enable_node() or disable_node() methods.

Parameters:

scheme_host (basestring) – Scheme, host, and port combination of the load balancer.
username (basestring) – Name of the user to authenticate with.
password (basestring) – Password for the user to authenticate with.
verify (bool|None) – True to verify certificates when using HTTPS, False to skip verification, None to use the library default. The default is to verify certificates.
ssl_version (int|None) – ssl module constant for specifying which version of SSL or TLS to use when connecting to the load balancer over HTTPS, None to use the library default. The default is to use TLSv1.2.
network_retries (int|None) – Maximum number of times to retry network operations on transient network errors. Default is to retry network operations a non-zero number of times.
commands (CommandFactory) – Factory instance for creating new commands for starting and ending sessions with the load balancer.

disable_server(server, max_retries=5, wait_interval=2.0)[source]¶

Disable a server at the node level, optionally retrying when there are transient errors and waiting for the number of active connections to the server to reach zero.

If max_retries is zero, no attempt will be made to wait until there are no active connections to the server, the method will try a single time to disable the server and then return immediately.

Changed in version 2.0.0: Added the optional wait_interval parameter.

Parameters:	server (basestring) – Hostname of the server to disable max_retries (int) – Max number of times to sleep and retry while waiting for the number of active connections to a server to reach zero. wait_interval (float) – How long (in seconds) to wait between each check to see if the number of active connections to a server has reached zero.
Returns:	True if the server was disabled, false otherwise.
Return type:	bool
Raises:	warthog.exceptions.WarthogAuthFailureError – If authentication with the load balancer failed when trying to establish a new session for this operation. warthog.exceptions.WarthogNoSuchNodeError – If the load balancer does not recognize the given hostname. warthog.exceptions.WarthogApiError – If there are any other problems disabling the given server.

enable_server(server, max_retries=5, wait_interval=2.0)[source]¶

Enable a server at the node level, optionally retrying when there are transient errors and waiting for the server to enter the expected, enabled state.

If max_retries is zero, no attempt will be made to wait until the server enters the expected, enabled state, the method will try a single time to enable the server then return immediately.

Changed in version 2.0.0: Added the optional wait_interval parameter.

Parameters:	server (basestring) – Hostname of the server to enable max_retries (int) – Max number of times to sleep and retry while waiting for the server to enter the “enabled” state. wait_interval (float) – How long (in seconds) to wait between each check to see if the server has entered the “enabled” state.
Returns:	True if the server was enabled, false otherwise
Return type:	bool
Raises:	warthog.exceptions.WarthogAuthFailureError – If authentication with the load balancer failed when trying to establish a new session for this operation. warthog.exceptions.WarthogNoSuchNodeError – If the load balancer does not recognize the given hostname. warthog.exceptions.WarthogApiError – If there are any other problems enabling the given server.

get_connections(server)[source]¶

Get the current number of active connections to a server, at the node level.

The number of connections will be 0 or a positive integer.

Parameters:	server (basestring) – Hostname of the server to get the number of active connections for.
Returns:	The number of active connections total for the node, across all groups the server is in.
Return type:	int
Raises:	warthog.exceptions.WarthogAuthFailureError – If authentication with the load balancer failed when trying to establish a new session for this operation. warthog.exceptions.WarthogNoSuchNodeError – If the load balancer does not recognize the given hostname. warthog.exceptions.WarthogApiError – If there are any other problems getting the active connections for the given server.

New in version 0.4.0.

get_status(server)[source]¶

Get the current status of the given server, at the node level.

The status will be one of the constants warthog.core.STATUS_ENABLED warthog.core.STATUS_DISABLED, or warthog.core.STATUS_DOWN.

Parameters:	server (basestring) – Hostname of the server to get the status of.
Returns:	The current status of the server, enabled, disabled, or down.
Return type:	basestring
Raises:	warthog.exceptions.WarthogAuthFailureError – If authentication with the load balancer failed when trying to establish a new session for this operation. warthog.exceptions.WarthogNoSuchNodeError – If the load balancer does not recognize the given hostname. warthog.exceptions.WarthogApiError – If there are any other problems getting the status of the given server.

class warthog.client.CommandFactory(transport_factory)[source]¶

Factory for getting new warthog.core command instances that each perform some type of request against the load balancer API.

It is typically not required for user code to instantiate this class directly unless you have special requirements and need to inject a custom transport_factory method.

This class is thread safe.

__init__(transport_factory)[source]¶

Set the a factory that will create new HTTP Sessions instances to be used for executing commands.

Parameters:	transport_factory (callable) – Callable for creating new Session instances for executing commands.

get_active_connections(scheme_host, session_id, server)[source]¶

Get a new command to get the number of active connections to a server.

Parameters:	scheme_host (basestring) – Scheme, host, and port combination of the load balancer. session_id (basestring) – Previously authenticated session ID. server (basestring) – Host name of the server to get the number of active connections to.
Returns:	A new command to get active connections to a server.
Return type:	warthog.core.NodeActiveConnectionsCommand

get_disable_server(scheme_host, session_id, server)[source]¶

Get a new command to disable a server at the node level.

Parameters:	scheme_host (basestring) – Scheme, host, and port combination of the load balancer. session_id (basestring) – Previously authenticated session ID. server (basestring) – Host name of the server to disable.
Returns:	A new command to disable a server.
Return type:	warthog.core.NodeDisableCommand

get_enable_server(scheme_host, session_id, server)[source]¶

Get a new command to enable a server at the node level.

Parameters:	scheme_host (basestring) – Scheme, host, and port combination of the load balancer. session_id (basestring) – Previously authenticated session ID. server (basestring) – Host name of the server to enable.
Returns:	A new command to enable a server.
Return type:	warthog.core.NodeEnableCommand

get_server_status(scheme_host, session_id, server)[source]¶

Get a new command to get the status (enabled / disabled) of a server.

Parameters:	scheme_host (basestring) – Scheme, host, and port combination of the load balancer. session_id (basestring) – Previously authenticated session ID. server (basestring) – Host name of the server to get the status of.
Returns:	A new command to get the status of a server.
Return type:	warthog.core.NodeStatusCommand

get_session_end(scheme_host, session_id)[source]¶

Get a new command instance to close an existing session.

Parameters:	scheme_host (basestring) – Scheme, host, and port combination of the load balancer. session_id (basestring) – Previously authenticated session ID.
Returns:	A new command to close a session.
Return type:	warthog.core.SessionEndCommand

get_session_start(scheme_host, username, password)[source]¶

Get a new command instance to start a session.

Parameters:	scheme_host (basestring) – Scheme, host, and port combination of the load balancer. username (basestring) – Name of the user to authenticate with. password (basestring) – Password for the user to authenticate with.
Returns:	A new command to start a session.
Return type:	warthog.core.SessionStartCommand

warthog.config¶

Load and parse configuration for a client from an INI-style file.

class warthog.config.WarthogConfigLoader(config_file=None, encoding=None, path_resolver=None, config_parser=None)[source]¶

Load and parse configuration from an INI-style WarthogClient configuration file.

If a specific configuration file is given during construction, this file will be used instead of checking the multiple possible default locations for configuration files. The default locations to be checked are an ordered list of paths contained in DEFAULT_CONFIG_LOCATIONS.

Note

When checking for configuration files in default locations, each file will only be checked to see if it exists. It will not be checked to see if the file is readable or correctly formatted.

This class is thread safe.

New in version 0.4.0.

Changed in version 0.6.0: Loading, parsing, and access of configuration settings is now thread safe.

Changed in version 0.6.0: The .parse_configuration() method has been removed and the functionality has been split into the .initialize() and .get_settings() methods.

Changed in version 0.10.0: The WarthogConfigLoader.__init__() method no longer directly takes a standard library INI parser as an option parameter, instead it now takes a WarthogConfigParser instance as an optional parameter.

Changed in version 0.10.0: See Changelog or CLI Tool for details about the changes to configuration file format.

__init__(config_file=None, encoding=None, path_resolver=None, config_parser=None)[source]¶

Optionally, set a specific configuration file, the encoding of the file, resolver to determine the configuration file to use, and custom configuration parser implementation.

By default, multiple locations will be checked for a configuration file, the file is assumed to use UTF-8 encoding, and an

Parameters:

config_file (str|unicode) – Optional explicit path to a configuration file to use.
encoding (str|unicode) – Encoding to use for reading the configuration file. Default is UTF-8
path_resolver (callable) – Callable that accepts a single argument (the explicit configuration file path to use) and determines what configuration file to use. It is typically only necessary to set this parameter for unit testing purposes.
config_parser (WarthogConfigParser) – Optional configuration parser to use for reading and parsing the expected INI format for a Warthog configuration file. It is typically only necessary to set this parameter for unit testing purposes.

get_settings()[source]¶

Get previously loaded and parsed configuration settings, raise an exception if the settings have not already been loaded and parsed.

New in version 0.6.0.

Returns:	Struct of configuration settings for the Warthog client
Return type:	WarthogConfigSettings
Raises:	RuntimeError – If a configuration file has not already been loaded and parsed.

initialize()[source]¶

Load and parse a configuration an INI-style configuration file.

The values parsed will be stored as a WarthogConfigSettings instance that may be accessed with the get_settings() method.

New in version 0.6.0.

Changed in version 0.8.0: Errors locating or parsing configuration files now result in Warthog-specific exceptions (warthog.exceptions.WarthogConfigError) instead of ValueError, IOError, or RuntimeError.

Returns:	Fluent interface
Return type:	WarthogConfigLoader
Raises:	warthog.exceptions.WarthogNoConfigFileError – If no explicit configuration file was given and there were no configuration files in any of the default locations checked or if the configuration file could not be opened or read for some reason. warthog.exceptions.WarthogMalformedConfigFileError – If the configuration file was malformed such has missing the required ‘warthog’ section or any of the expected values. See the CLI Tool section for more information about the expected configuration settings.

class warthog.config.WarthogConfigSettings(scheme_host, username, password, verify, ssl_version)¶

password¶: Alias for field number 2

scheme_host¶: Alias for field number 0

ssl_version¶: Alias for field number 4

username¶: Alias for field number 1

verify¶: Alias for field number 3

warthog.transport¶

Methods to configure how to interact with the load balancer API over HTTP or HTTPS.

warthog.transport.get_transport_factory(verify=None, ssl_version=None, retries=None)[source]¶

Get a new callable that returns requests.Session instances that have been configured according to the given parameters.

requests.Session instances are then used for interacting with the API of the load balancer over HTTP or HTTPS.

Changed in version 0.10.0: Using the requests/urllib3 default is no longer an option. Passing a None value for ssl_version will result in using the Warthog default (TLS v1).

Changed in version 2.0.0: Added the retries parameter and default it to a number greater than zero.

Parameters:	verify (bool\|None) – Should SSL certificates by verified when connecting over HTTPS? Default is `True`. If you have chosen not to verify certificates warnings about this emitted by the requests library will be suppressed. ssl_version (int\|None) – Explicit version of SSL to use for HTTPS connections to an A10 load balancer. The version is a constant as specified by the `ssl` module. The default is TLSv1. retries (int\|None) – The maximum number of times to retry operations on transient network errors. Note this only applies to cases where we haven’t yet sent any data to the server (e.g. connection errors, DNS errors, etc.)
Returns:	A callable to return new configured session instances for making HTTP(S) requests
Return type:	callable

warthog.exceptions¶

Exceptions raised by the Warthog client or library.

exception warthog.exceptions.WarthogApiError(msg, api_msg=None, api_code=None)[source]¶

Bases: warthog.exceptions.WarthogError

Base for errors raised in the course of interacting with the load balancer.

__init__(msg, api_msg=None, api_code=None)[source]¶

exception warthog.exceptions.WarthogAuthFailureError(msg, api_msg=None, api_code=None)[source]¶

Bases: warthog.exceptions.WarthogApiError

The credentials for authentication are invalid.

exception warthog.exceptions.WarthogConfigError(msg)[source]¶

Bases: warthog.exceptions.WarthogError

Base for errors raised while parsing or loading configuration.

exception warthog.exceptions.WarthogError(msg)[source]¶

Bases: exceptions.Exception

Base for all errors raised by the Warthog library.

__init__(msg)[source]¶

exception warthog.exceptions.WarthogInvalidSessionError(msg, api_msg=None, api_code=None)[source]¶

Bases: warthog.exceptions.WarthogApiError

The session ID or auth token used while performing some action is unrecognized.

exception warthog.exceptions.WarthogMalformedConfigFileError(msg, missing_section=None, missing_option=None)[source]¶

Bases: warthog.exceptions.WarthogConfigError

The configuration file is missing required sections or fields.

__init__(msg, missing_section=None, missing_option=None)[source]¶

exception warthog.exceptions.WarthogNoConfigFileError(msg, locations_checked=None)[source]¶

Bases: warthog.exceptions.WarthogConfigError

No configuration file could be found.

__init__(msg, locations_checked=None)[source]¶

exception warthog.exceptions.WarthogNoSuchNodeError(msg, api_msg=None, api_code=None, server=None)[source]¶

Bases: warthog.exceptions.WarthogNodeError

The host being operated on is unrecognized.

exception warthog.exceptions.WarthogNodeError(msg, api_msg=None, api_code=None, server=None)[source]¶

Bases: warthog.exceptions.WarthogApiError

Base for errors specific to operating on some individual node.

__init__(msg, api_msg=None, api_code=None, server=None)[source]¶

exception warthog.exceptions.WarthogNodeStatusError(msg, api_msg=None, api_code=None, server=None)[source]¶

Bases: warthog.exceptions.WarthogNodeError

There was some error while getting the status of a node.

exception warthog.exceptions.WarthogPermissionError(msg, api_msg=None, api_code=None, server=None)[source]¶

Bases: warthog.exceptions.WarthogNodeError

The credentials lack required permissions to perform an operation.

New in version 1.999.0.