brewtils.rest package

Submodules

brewtils.rest.client module

class brewtils.rest.client.BrewmasterRestClient(*args, **kwargs)

Bases: brewtils.rest.client.RestClient

class brewtils.rest.client.RestClient(host, port, ssl_enabled=False, api_version=None, logger=None, ca_cert=None, client_cert=None, url_prefix=None, ca_verify=True)

Bases: object

Simple Rest Client for communicating to with beer-garden.

The is the low-level client responsible for making the actual REST calls. Other clients (e.g. brewtils.rest.easy_client.EasyClient) build on this by providing useful abstractions.

Parameters:

• host – beer-garden REST API hostname.
• port – beer-garden REST API port.
• ssl_enabled – Flag indicating whether to use HTTPS when communicating with beer-garden.
• api_version – The beer-garden REST API version. Will default to the latest version.
• logger – The logger to use. If None one will be created.
• ca_cert – beer-garden REST API server CA certificate.
• client_cert – The client certificate to use when making requests.
• url_prefix – beer-garden REST API Url Prefix.
• ca_verify – Flag indicating whether to verify server certificate when making a request.

JSON_HEADERS = {'Accept': 'text/plain', 'Content-type': 'application/json'}

LATEST_VERSION = 1

delete_queue(queue_name)

Performs a DELETE on a specific Queue URL

Returns:Response to the request

delete_queues()

Performs a DELETE on the Queues URL

Returns:Response to the request

delete_system(system_id)

Performs a DELETE on a System URL

Parameters:system_id – The ID of the system to remove Returns:Response to the request

get_command(command_id)

Performs a GET on the Command URL

Parameters:command_id – ID of command Returns:Response to the request

get_commands()

Performs a GET on the Commands URL

get_logging_config(**kwargs)

Perform a GET to the logging config URL

Parameters:kwargs – Parameters to be used in the GET request Returns:The request response

get_queues()

Performs a GET on the Queues URL

Returns:Response to the request

get_request(request_id)

Performs a GET on the Request URL

Parameters:request_id – ID of request Returns:Response to the request

get_requests(**kwargs)

Performs a GET on the Requests URL

Parameters:kwargs – Parameters to be used in the GET request Returns:Response to the request

get_system(system_id, **kwargs)

Performs a GET on the System URL

Parameters:

• system_id – ID of system
• kwargs – Parameters to be used in the GET request

Returns:

Response to the request

get_systems(**kwargs)

Perform a GET on the System collection URL

Parameters:kwargs – Parameters to be used in the GET request Returns:The request response

get_version(**kwargs)

Perform a GET to the version URL

Parameters:kwargs – Parameters to be used in the GET request Returns:The request response

patch_instance(instance_id, payload)

Performs a PATCH on the instance URL

Parameters:

• instance_id – ID of instance
• payload – The update specification

Returns:

Response

patch_request(request_id, payload)

Performs a PATCH on the Request URL

Parameters:

• request_id – ID of request
• payload – New request definition

Returns:

Response to the request

patch_system(system_id, payload)

Performs a PATCH on a System URL

Parameters:

• system_id – ID of system
• payload – The update specification

Returns:

Response

post_event(payload, publishers=None)

Performs a POST on the event URL

Parameters:

• payload – New event definition
• publishers – Array of publishers to use

Returns:

Response to the request

post_requests(payload)

Performs a POST on the Request URL

Parameters:payload – New request definition Returns:Response to the request

post_systems(payload)

Performs a POST on the System URL

Parameters:payload – New request definition Returns:Response to the request

brewtils.rest.easy_client module

class brewtils.rest.easy_client.BrewmasterEasyClient(*args, **kwargs)

Bases: brewtils.rest.easy_client.EasyClient

class brewtils.rest.easy_client.EasyClient(host, port, ssl_enabled=False, api_version=None, ca_cert=None, client_cert=None, parser=None, logger=None, url_prefix=None, ca_verify=True)

Bases: object

Client for communicating with beer-garden.

This class provides nice wrappers around the functionality provided by a brewtils.rest.client.RestClient

Parameters:

• host – beer-garden REST API hostname.
• port – beer-garden REST API port.
• ssl_enabled – Flag indicating whether to use HTTPS when communicating with beer-garden.
• api_version – The beer-garden REST API version. Will default to the latest version.
• ca_cert – beer-garden REST API server CA certificate.
• client_cert – The client certificate to use when making requests.
• parser – The parser to use. If None will default to an instance of BrewmasterSchemaParser.
• logger – The logger to use. If None one will be created.
• url_prefix – beer-garden REST API URL Prefix.
• ca_verify – Flag indicating whether to verify server certificate when making a request.

clear_all_queues()

Cancel and clear all messages from all queues

Returns:The response

clear_queue(queue_name)

Cancel and clear all messages from a queue

Returns:The response

create_request(request)

Create a new request.

Parameters:request – The request to create Returns:The response

create_system(system)

Create a new system by POSTing to a BREWMASTER server.

Parameters:system – The system to create Returns:The system creation response

find_requests(**kwargs)

Find requests using keyword arguments as search parameters.

Parameters:kwargs – Search parameters Returns:A list of request instances satisfying the given search parameters

find_systems(**kwargs)

Find systems using keyword arguments as search parameters.

Parameters:kwargs – Search parameters Returns:A list of system instances satisfying the given search parameters

find_unique_request(**kwargs)

Find a unique request using keyword arguments as search parameters.

Note

If ‘id’ is present in kwargs then all other parameters will be ignored.

Parameters:kwargs – Search parameters Returns:One request instance

find_unique_system(**kwargs)

Find a unique system using keyword arguments as search parameters.

Parameters:kwargs – Search parameters Returns:One system instance

get_logging_config(system_name)

Get the logging configuration for a particular system.

Parameters:system_name – Name of system Returns:LoggingConfig object

get_queues()

Retrieve all queue information

Returns:The response

get_version(**kwargs)

initialize_instance(instance_id)

Start an instance by PATCHing to a BREWMASTER server.

Parameters:instance_id – The ID of the instance to start Returns:The start response

instance_heartbeat(instance_id)

Send heartbeat to BREWMASTER for health and status purposes

Parameters:instance_id – The ID of the instance Returns:The response

publish_event(*args, **kwargs)

Publish a new event.

Parameters:

• args – The Event to create
• _publishers – Optional list of specific publishers. If None all publishers will be used.
• kwargs – If no Event is given in the *args, on will be constructed from the kwargs

Returns:

The response

remove_system(**kwargs)

Remove a specific system using keyword arguments as search parameters.

Parameters:kwargs – Search parameters Returns:The response

update_instance_status(instance_id, new_status)

Update an instance by PATCHing to a BREWMASTER server.

Parameters:

• instance_id – The ID of the instance to start
• new_status – The updated status

Returns:

The start response

update_request(request_id, status=None, output=None, error_class=None)

Set various fields on a request with a PATCH

Parameters:

• request_id – The ID of the request to update
• status – The new status
• output – The new output
• error_class – The new error class

Returns:

The response

update_system(system_id, new_commands=None, **kwargs)

Update a system with a PATCH

Parameters:

• system_id – The ID of the system to update
• new_commands – The new commands

Keyword Arguments:  

• metadata (dict) The updated metadata for the system
• description (str) The updated description for the system
• display_name (str) The updated display_name for the system
• icon_name (str) The updated icon_name for the system

Returns:

The response

brewtils.rest.system_client module

class brewtils.rest.system_client.BrewmasterSystemClient(*args, **kwargs)

Bases: brewtils.rest.system_client.SystemClient

class brewtils.rest.system_client.SystemClient(host, port, system_name, version_constraint='latest', default_instance='default', always_update=False, timeout=None, max_delay=30, api_version=None, ssl_enabled=False, ca_cert=None, blocking=True, max_concurrent=None, client_cert=None, url_prefix=None, ca_verify=True)

Bases: object

High-level client for generating requests for a beer-garden System.

SystemClient creation:

This class is intended to be the main way to create beer-garden requests. Create an instance with beer-garden connection information (optionally including a url_prefix) and a system name:

client = SystemClient(host, port, 'example_system', ssl_enabled=True, url_prefix=None)

Pass additional keyword arguments for more granularity:

version_constraint:

Allows specifying a particular system version. Can be a version literal (‘1.0.0’) or the special value ‘latest.’ Using ‘latest’ will allow the the SystemClient to retry a request if it fails due to a missing system (see Creating Requests).

default_instance:

The instance name to use when creating a request if no other instance name is specified. Since each request must be addressed to a specific instance this is a convenience to prevent needing to specify the ‘default’ instance for each request.

always_update:

Always attempt to reload the system definition before making a request. This is useful to ensure Requests are always made against the latest version of the system. If not set the System definition will be loaded once (upon making the first request) and then only reloaded if a Request fails.

Loading the System:

The System definition is lazily loaded, so nothing happens until the first attempt to send a Request. At that point the SystemClient will query beer-garden to get a system definition that matches the system_name and version_constraint. If no matching system can be found a BrewmasterFetchError will be raised. If always_update was set to True this will happen before making each request, not just the first.

Making a Request:

The standard way to create and send requests is by calling object attributes:

request = client.example_command(param_1='example_param')

In the normal case this will block until the request completes. Request completion is determined by periodically polling beer-garden to check the Request status. The time between polling requests starts at 0.5s and doubles each time the request has still not completed, up to max_delay. If a timeout was specified and the Request has not completed within that time a BrewmasterTimeoutError will be raised.

It is also possible to create the SystemClient in non-blocking mode by specifying blocking=False. In this case the request creation will immediately return a Future and will spawn a separate thread to poll for Request completion. The max_concurrent parameter is used to control the maximum threads available for polling.

# Create a SystemClient with blocking=False
client = SystemClient(host, port, 'example_system', ssl_enabled=True, blocking=False)

# Create and send 5 requests without waiting for request completion
futures = [client.example_command(param_1=number) for number in range(5)]

# Now wait on all requests to complete
concurrent.futures.wait(futures)

If the request creation process fails (e.g. the command failed validation) and version_constraint is ‘latest’ then the SystemClient will check to see if a different version is available, and if so it will attempt to make the request on that version. This is so users of the SystemClient that don’t necessarily care about the target system version don’t need to be restarted if the target system is updated.

Tweaking beer-garden Request Parameters:

There are several parameters that control how beer-garden routes / processes a request. To denote these as intended for beer-garden itself (rather than a parameter to be passed to the Plugin) prepend a leading underscore to the argument name.

Sending to another instance:

request = client.example_command(_instance_name='instance_2', param_1='example_param')

Request with a comment:

request = client.example_command(_comment='I'm a beer-garden comment!',
                                 param_1='example_param')

Without the leading underscore the arguments would be treated the same as param_1 - another parameter to be passed to the plugin.

Parameters:

• host – beer-garden REST API hostname.
• port – beer-garden REST API port.
• system_name – The name of the system to use.
• version_constraint – The system version to use. Can be specific or ‘latest’.
• default_instance – The instance to use if not specified when creating a request.
• always_update – Should check for a newer System version before each request.
• timeout – Length of time to wait for a request to complete. ‘None’ means wait forever.
• max_delay – Maximum time to wait between checking the status of a created request.
• api_version – beer-garden API version.
• ssl_enabled – Flag indicating whether to use HTTPS when communicating with beer-garden.
• ca_cert – beer-garden REST API server CA certificate.
• blocking – Block after request creation until the request completes.
• max_concurrent – Maximum number of concurrent requests allowed.
• client_cert – The client certificate to use when making requests.
• url_prefix – beer-garden REST API URL Prefix.
• ca_verify – Flag indicating whether to verify server certificate when making a request.

create_bg_request(command_name, **kwargs)

Create a callable that will execute a beer-garden request when called.

Normally you interact with the SystemClient by accessing attributes, but there could be certain cases where you want to create a request without sending it.

Example:

client = SystemClient(host, port, 'system', blocking=False)
requests = []

# No arguments
requests.append(client.create_bg_request('command_1'))

# arg_1 will be passed as a parameter
requests.append(client.create_bg_request('command_2', arg_1='Hi!'))

futures = [request() for request in requests]   # Calling creates and sends the request
concurrent.futures.wait(futures)                # Wait for all the futures to complete

Parameters:

• command_name – The name of the command that will be sent.
• kwargs – Additional arguments to pass to send_bg_request.

Raises:

AttributeError – The system does not have a command with the given command_name.

Returns:

A partial that will create and execute a beer-garden request when called.

load_bg_system()

Query beer-garden for a System definition

This method will make the query to beer-garden for a System matching the name and version constraints specified during SystemClient instance creation.

If this method completes successfully the SystemClient will be ready to create and send Requests.

Raises:BrewmasterFetchError – If unable to find a matching System Returns:None

send_bg_request(**kwargs)

Actually create a Request and send it to beer-garden

Note

This method is intended for advanced use only, mainly cases where you’re using the SystemClient without a predefined System. It assumes that everything needed to construct the request is being passed in kwargs. If this doesn’t sound like what you want you should check out create_bg_request.

Parameters:kwargs – All necessary request parameters, including beer-garden internal parameters Raises:BrewmasterValidationError – If the Request creation failed validation on the server Returns:If the SystemClient was created with blocking=True a completed request object, otherwise a Future that will return the Request when it completes.

Module contents

brewtils.rest.normalize_url_prefix(url_prefix)