brewtils package¶
Subpackages¶
Submodules¶
brewtils.choices module¶
-
class
brewtils.choices.
FunctionTransformer
[source]¶ Bases:
lark.visitors.Transformer
-
func_args
¶ alias of
__builtin__.list
-
url_args
¶ alias of
__builtin__.list
-
-
brewtils.choices.
parse
(input_string, parse_as=None)[source]¶ Attempt to parse a string into a choices dictionary.
Parameters: - input_string – The string to parse
- parse_as – String specifying how to parse input_string. Valid values are ‘func’ or ‘url’. Will try all valid values if None.
Returns: A dictionary containing the results of the parse
Raises: lark.common.ParseError – The parser was not able to find a valid parsing of input_string
brewtils.decorators module¶
-
brewtils.decorators.
system
(cls)[source]¶ Class decorator that marks a class as a beer-garden System
Creates a
_commands
property on the class that holds all registered commands.Parameters: cls – The class to decorated Returns: The decorated class
-
brewtils.decorators.
parameter
(_wrapped=None, key=None, type=None, multi=None, display_name=None, optional=None, default=None, description=None, choices=None, nullable=None, maximum=None, minimum=None, regex=None, is_kwarg=None, model=None, form_input_type=None)[source]¶ Decorator that enables Parameter specifications for a beer-garden Command
This decorator is intended to be used when more specification is desired for a Parameter.
For example:
@parameter(key="message", description="Message to echo", optional=True, type="String", default="Hello, World!") def echo(self, message): return message
Parameters: - _wrapped – The function to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- key – String specifying the parameter identifier. Must match an argument name of the decorated function.
- type – String indicating the type to use for this parameter.
- multi – Boolean indicating if this parameter is a multi. See documentation for discussion of what this means.
- display_name – String that will be displayed as a label in the user interface.
- optional – Boolean indicating if this parameter must be specified.
- default – The value this parameter will be assigned if not overridden when creating a request.
- description – An additional string that will be displayed in the user interface.
- choices – List or dictionary specifying allowed values. See documentation for more information.
- nullable – Boolean indicating if this parameter is allowed to be null.
- maximum – Integer indicating the maximum value of the parameter.
- minimum – Integer indicating the minimum value of the parameter.
- regex – String describing a regular expression constraint on the parameter.
- is_kwarg – Boolean indicating if this parameter is meant to be part of the decorated function’s kwargs.
- model – Class to be used as a model for this parameter. Must be a Python type object, not an instance.
- form_input_type – Only used for string fields. Changes the form input field (e.g. textarea)
Returns: The decorated function.
-
brewtils.decorators.
parameters
(*args)[source]¶ Specify multiple Parameter definitions at once
This can be useful for commands which have a large number of complicated parameters but aren’t good candidates for a Model.
@parameter(**params[cmd1][param1]) @parameter(**params[cmd1][param2]) @parameter(**params[cmd1][param3]) def cmd1(self, **kwargs): pass
Can become:
@parameters(params[cmd1]) def cmd1(self, **kwargs): pass
Parameters: *args (iterable) – Positional arguments The first (and only) positional argument must be a list containing dictionaries that describe parameters. Returns: The decorated function Return type: func
-
brewtils.decorators.
command
(_wrapped=None, command_type='ACTION', output_type='STRING', schema=None, form=None, template=None, icon_name=None, description=None)[source]¶ Decorator that marks a function as a beer-garden command
For example:
@command(output_type='JSON') def echo_json(self, message): return message
Parameters: - _wrapped – The function to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- command_type – The command type. Valid options are Command.COMMAND_TYPES.
- output_type – The output type. Valid options are Command.OUTPUT_TYPES.
- schema – A custom schema definition.
- form – A custom form definition.
- template – A custom template definition.
- icon_name – The icon name. Should be either a FontAwesome or a Glyphicon name.
- description – The command description. Will override the function’s docstring.
Returns: The decorated function.
-
brewtils.decorators.
command_registrar
(cls)¶ Class decorator that marks a class as a beer-garden System
Creates a
_commands
property on the class that holds all registered commands.Parameters: cls – The class to decorated Returns: The decorated class
-
brewtils.decorators.
plugin_param
(_wrapped=None, key=None, type=None, multi=None, display_name=None, optional=None, default=None, description=None, choices=None, nullable=None, maximum=None, minimum=None, regex=None, is_kwarg=None, model=None, form_input_type=None)¶ Decorator that enables Parameter specifications for a beer-garden Command
This decorator is intended to be used when more specification is desired for a Parameter.
For example:
@parameter(key="message", description="Message to echo", optional=True, type="String", default="Hello, World!") def echo(self, message): return message
Parameters: - _wrapped – The function to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- key – String specifying the parameter identifier. Must match an argument name of the decorated function.
- type – String indicating the type to use for this parameter.
- multi – Boolean indicating if this parameter is a multi. See documentation for discussion of what this means.
- display_name – String that will be displayed as a label in the user interface.
- optional – Boolean indicating if this parameter must be specified.
- default – The value this parameter will be assigned if not overridden when creating a request.
- description – An additional string that will be displayed in the user interface.
- choices – List or dictionary specifying allowed values. See documentation for more information.
- nullable – Boolean indicating if this parameter is allowed to be null.
- maximum – Integer indicating the maximum value of the parameter.
- minimum – Integer indicating the minimum value of the parameter.
- regex – String describing a regular expression constraint on the parameter.
- is_kwarg – Boolean indicating if this parameter is meant to be part of the decorated function’s kwargs.
- model – Class to be used as a model for this parameter. Must be a Python type object, not an instance.
- form_input_type – Only used for string fields. Changes the form input field (e.g. textarea)
Returns: The decorated function.
-
brewtils.decorators.
register
(_wrapped=None, command_type='ACTION', output_type='STRING', schema=None, form=None, template=None, icon_name=None, description=None)¶ Decorator that marks a function as a beer-garden command
For example:
@command(output_type='JSON') def echo_json(self, message): return message
Parameters: - _wrapped – The function to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- command_type – The command type. Valid options are Command.COMMAND_TYPES.
- output_type – The output type. Valid options are Command.OUTPUT_TYPES.
- schema – A custom schema definition.
- form – A custom form definition.
- template – A custom template definition.
- icon_name – The icon name. Should be either a FontAwesome or a Glyphicon name.
- description – The command description. Will override the function’s docstring.
Returns: The decorated function.
brewtils.errors module¶
-
exception
brewtils.errors.
AuthorizationRequired
[source]¶ Bases:
brewtils.errors.RestClientError
Error indicating a 401 was raised on the server
-
brewtils.errors.
BGConflictError
¶ alias of
brewtils.errors.ConflictError
-
brewtils.errors.
BGNotFoundError
¶ alias of
brewtils.errors.NotFoundError
-
brewtils.errors.
BGRequestFailedError
¶ alias of
brewtils.errors.RequestFailedError
-
brewtils.errors.
BrewmasterConnectionError
¶ alias of
brewtils.errors.RestConnectionError
-
brewtils.errors.
BrewmasterDeleteError
¶ alias of
brewtils.errors.DeleteError
-
brewtils.errors.
BrewmasterFetchError
¶ alias of
brewtils.errors.FetchError
-
brewtils.errors.
BrewmasterModelError
¶ alias of
brewtils.errors.ModelError
-
brewtils.errors.
BrewmasterModelValidationError
¶ alias of
brewtils.errors.ModelValidationError
-
brewtils.errors.
BrewmasterRestClientError
¶ alias of
brewtils.errors.RestClientError
-
brewtils.errors.
BrewmasterRestError
¶ alias of
brewtils.errors.RestError
-
brewtils.errors.
BrewmasterRestServerError
¶ alias of
brewtils.errors.RestServerError
-
brewtils.errors.
BrewmasterSaveError
¶ alias of
brewtils.errors.SaveError
-
brewtils.errors.
BrewmasterTimeoutError
¶ alias of
brewtils.errors.TimeoutExceededError
-
brewtils.errors.
BrewmasterValidationError
¶ alias of
brewtils.errors.ValidationError
-
exception
brewtils.errors.
ConflictError
[source]¶ Bases:
brewtils.errors.RestClientError
Error indicating a 409 was raised on the server
-
brewtils.errors.
ConnectionTimeoutError
¶ alias of
brewtils.errors.TimeoutExceededError
-
exception
brewtils.errors.
DeleteError
[source]¶ Bases:
brewtils.errors.RestServerError
Error Indicating a server Error occurred performing a DELETE
-
exception
brewtils.errors.
DiscardMessageException
[source]¶ Bases:
brewtils.errors.RequestProcessException
Raising an instance will result in a message not being requeued
-
exception
brewtils.errors.
FetchError
[source]¶ Bases:
brewtils.errors.RestError
Error Indicating a server Error occurred performing a GET
-
exception
brewtils.errors.
ModelError
[source]¶ Bases:
brewtils.errors.BrewtilsException
Base exception for model errors
-
exception
brewtils.errors.
ModelValidationError
[source]¶ Bases:
brewtils.errors.ModelError
Invalid model
-
exception
brewtils.errors.
NotFoundError
[source]¶ Bases:
brewtils.errors.RestClientError
Error Indicating a 404 was raised on the server
-
exception
brewtils.errors.
PluginError
[source]¶ Bases:
brewtils.errors.BrewtilsException
Generic error class
-
exception
brewtils.errors.
PluginParamError
[source]¶ Bases:
brewtils.errors.PluginError
Error used when plugins have illegal parameters
-
exception
brewtils.errors.
PluginValidationError
[source]¶ Bases:
brewtils.errors.PluginError
Plugin could not be validated successfully
-
exception
brewtils.errors.
RepublishRequestException
(request, headers)[source]¶ Bases:
brewtils.errors.RequestProcessException
Republish to the end of the message queue
Parameters: - request (
brewtils.models.Request
) – The Request to republish - headers – A dictionary of headers to be used by brewtils.request_consumer.RequestConsumer
- request (
-
exception
brewtils.errors.
RequestFailedError
(request)[source]¶ Bases:
brewtils.errors.RestError
Request returned with a 200, but the status was ERROR
-
exception
brewtils.errors.
RequestForbidden
[source]¶ Bases:
brewtils.errors.RestClientError
Error indicating a 403 was raised on the server
-
exception
brewtils.errors.
RequestProcessException
[source]¶ Bases:
brewtils.errors.BrewtilsException
Base for exceptions that occur during request processing
-
exception
brewtils.errors.
RequestPublishException
[source]¶ Bases:
brewtils.errors.BrewtilsException
Error while publishing request
-
exception
brewtils.errors.
RequestStatusTransitionError
[source]¶ Bases:
brewtils.errors.ModelValidationError
A status update was an invalid transition
-
exception
brewtils.errors.
RestClientError
[source]¶ Bases:
brewtils.errors.RestError
Wrapper for all 4XX errors
-
exception
brewtils.errors.
RestConnectionError
[source]¶ Bases:
brewtils.errors.RestServerError
Error indicating a connection error while performing a request
-
exception
brewtils.errors.
RestError
[source]¶ Bases:
brewtils.errors.BrewtilsException
Base exception for REST errors
-
exception
brewtils.errors.
RestServerError
[source]¶ Bases:
brewtils.errors.RestError
Wrapper for all 5XX errors
-
exception
brewtils.errors.
SaveError
[source]¶ Bases:
brewtils.errors.RestServerError
Error Indicating a server Error occurred performing a POST/PUT
-
exception
brewtils.errors.
TimeoutExceededError
[source]¶ Bases:
brewtils.errors.RestClientError
Error indicating a timeout occurred waiting for a request to complete
-
exception
brewtils.errors.
ValidationError
[source]¶ Bases:
brewtils.errors.RestClientError
Error Indicating a client (400) Error occurred performing a POST/PUT
-
brewtils.errors.
WaitExceededError
¶ alias of
brewtils.errors.TimeoutExceededError
-
brewtils.errors.
parse_exception_as_json
(exc)[source]¶ Attempt to parse an Exception to a JSON string.
If the exception has a single argument, no attributes, and the attribute can be converted to a valid JSON string, then that will be returned.
Otherwise, a string version of the following form will be returned:
- {
- “message”: “”, “arguments”: [], “attributes”: {}
}
Where “message” is just str(exc), “arguments” is a list of all the arguments passed to the exception attempted to be converted to a valid JSON string, and “attributes” are the attributes of the exception class.
If parsing fails at all, then a simple str() will be applied either the argument or attribute value.
Note
On python version 2, errors with custom attributes do not list those attributes as arguments.
Parameters: exc (Exception) – The exception you would like to format as JSON. Raises: ValueError
– If the exception passed in is not an Exception.Returns: A valid JSON string representing (the best we can) the exception.
brewtils.log module¶
Brewtils Logging Utilities
This module streamlines loading logging configuration from Beergarden.
Example
To use this just call configure_logging
sometime before you initialize
your Plugin object:
from brewtils import configure_logging, get_connection_info, Plugin
# Load BG connection info from environment and command line args
connection_info = get_connection_info(sys.argv[1:])
configure_logging(system_name='systemX', **connection_info)
plugin = Plugin(
my_client,
name='systemX,
version='0.0.1',
**connection_info
)
plugin.run()
-
brewtils.log.
configure_logging
(system_name=None, **kwargs)[source]¶ Load and enable a logging configuration from Beergarden
NOTE: This method will overwrite the current logging configuration.
Parameters: - system_name – Name of the system to load
- **kwargs – Beergarden connection parameters
Returns: None
-
brewtils.log.
convert_logging_config
(logging_config)[source]¶ Transform a LoggingConfig object into a Python logging configuration
Parameters: logging_config – Beergarden logging config Returns: The logging configuration Return type: dict
-
brewtils.log.
get_logging_config
(system_name=None, **kwargs)[source]¶ Retrieve a logging configuration from Beergarden
Parameters: - system_name – Name of the system to load
- **kwargs – Beergarden connection parameters
Returns: The logging configuration for the specified system
Return type: dict
-
brewtils.log.
get_python_logging_config
(bg_host, bg_port, system_name, ca_cert=None, client_cert=None, ssl_enabled=None)[source]¶ DEPRECATED: Get Beergarden’s logging configuration
This method is deprecated - consider using
get_logging_config()
Parameters: - bg_host (str) – Beergarden host
- bg_port (int) – Beergarden port
- system_name (str) – Name of the system
- ca_cert (str) – Path to CA certificate file
- client_cert (str) – Path to client certificate file
- ssl_enabled (bool) – Use SSL when connection to Beergarden
Returns: The logging configuration for the specified system
Return type: dict
-
brewtils.log.
setup_logger
(bg_host, bg_port, system_name, ca_cert=None, client_cert=None, ssl_enabled=None)[source]¶ DEPRECATED: Set Python logging to use configuration from Beergarden API
This method is deprecated - consider using
configure_logging()
This method will overwrite the current logging configuration.
Parameters: - bg_host (str) – Beergarden host
- bg_port (int) – Beergarden port
- system_name (str) – Name of the system
- ca_cert (str) – Path to CA certificate file
- client_cert (str) – Path to client certificate file
- ssl_enabled (bool) – Use SSL when connection to Beergarden
Returns: None
brewtils.models module¶
-
class
brewtils.models.
System
(name=None, description=None, version=None, id=None, max_instances=None, instances=None, commands=None, icon_name=None, display_name=None, metadata=None)[source]¶ Bases:
object
-
get_command_by_name
(command_name)[source]¶ Retrieve a particular command from the system
Parameters: command_name – Name of the command to retrieve Returns: The command object. None if the given command name does not exist in this system.
-
get_instance
(name)[source]¶ Get an instance that currently exists in the system
Parameters: name – The name of the instance to search Returns: The instance with the given name exists for this system, None otherwise
-
has_different_commands
(commands)[source]¶ Check if a set of commands is different than the current commands
Parameters: commands – The set commands to compare against the current set Returns: True if the sets are different, False if the sets are the same
-
has_instance
(name)[source]¶ Determine if an instance currently exists in the system
Parameters: name – The name of the instance to search Returns: True if an instance with the given name exists for this system, False otherwise.
-
instance_names
¶
-
schema
= 'SystemSchema'¶
-
-
class
brewtils.models.
Instance
(name=None, description=None, id=None, status=None, status_info=None, queue_type=None, queue_info=None, icon_name=None, metadata=None)[source]¶ Bases:
object
-
INSTANCE_STATUSES
= set(['DEAD', 'INITIALIZING', 'PAUSED', 'RUNNING', 'STARTING', 'STOPPED', 'STOPPING', 'UNKNOWN', 'UNRESPONSIVE'])¶
-
schema
= 'InstanceSchema'¶
-
-
class
brewtils.models.
Command
(name=None, description=None, id=None, parameters=None, command_type=None, output_type=None, schema=None, form=None, template=None, icon_name=None, system=None)[source]¶ Bases:
object
-
COMMAND_TYPES
= ('ACTION', 'INFO', 'EPHEMERAL')¶
-
OUTPUT_TYPES
= ('STRING', 'JSON', 'XML', 'HTML')¶
-
get_parameter_by_key
(key)[source]¶ Given a Key, it will return the parameter (or None) with that key
Parameters: key – Return parameter:
-
has_different_parameters
(parameters)[source]¶ Given a set of parameters, determines if the parameters provided differ from the parameters already defined on this command.
Parameters: parameters – Return boolean:
-
parameter_keys
()[source]¶ Convenience Method for returning all the keys of this command’s parameters.
Return list_of_parameters:
-
schema
= 'CommandSchema'¶
-
-
class
brewtils.models.
Parameter
(key, type=None, multi=None, display_name=None, optional=None, default=None, description=None, choices=None, parameters=None, nullable=None, maximum=None, minimum=None, regex=None, form_input_type=None)[source]¶ Bases:
object
-
FORM_INPUT_TYPES
= ('textarea',)¶
-
TYPES
= ('String', 'Integer', 'Float', 'Boolean', 'Any', 'Dictionary', 'Date', 'DateTime')¶
-
schema
= 'ParameterSchema'¶
-
-
class
brewtils.models.
Request
(system=None, system_version=None, instance_name=None, command=None, id=None, parent=None, children=None, parameters=None, comment=None, output=None, output_type=None, status=None, command_type=None, created_at=None, error_class=None, metadata=None, updated_at=None, has_parent=None, requester=None)[source]¶ Bases:
brewtils.models.RequestTemplate
-
COMMAND_TYPES
= ('ACTION', 'INFO', 'EPHEMERAL')¶
-
COMPLETED_STATUSES
= ('CANCELED', 'SUCCESS', 'ERROR')¶
-
OUTPUT_TYPES
= ('STRING', 'JSON', 'XML', 'HTML')¶
-
STATUS_LIST
= ('CREATED', 'RECEIVED', 'IN_PROGRESS', 'CANCELED', 'SUCCESS', 'ERROR')¶
-
is_ephemeral
¶
-
is_json
¶
-
schema
= 'RequestSchema'¶
-
status
¶
-
-
class
brewtils.models.
PatchOperation
(operation=None, path=None, value=None)[source]¶ Bases:
object
-
schema
= 'PatchSchema'¶
-
-
class
brewtils.models.
Choices
(type=None, display=None, value=None, strict=None, details=None)[source]¶ Bases:
object
-
DISPLAYS
= ('select', 'typeahead')¶
-
TYPES
= ('static', 'url', 'command')¶
-
schema
= 'ChoicesSchema'¶
-
-
class
brewtils.models.
LoggingConfig
(level=None, handlers=None, formatters=None, loggers=None)[source]¶ Bases:
object
-
DEFAULT_FORMAT
= '%(asctime)s - %(name)s - %(levelname)s - %(message)s'¶
-
DEFAULT_HANDLER
= {'class': 'logging.StreamHandler', 'formatter': 'default', 'stream': 'ext::/sys.stdout'}¶
-
LEVELS
= ('DEBUG', 'INFO', 'WARN', 'ERROR')¶
-
SUPPORTED_HANDLERS
= ('stdout', 'file', 'logstash')¶
-
formatter_names
¶
-
get_plugin_log_config
(**kwargs)[source]¶ Get a specific plugin logging configuration.
It is possible for different systems to have different logging configurations. This method will create the correct plugin logging configuration and return it. If a specific logger is not found for a system, then the current logging configuration will be returned.
Parameters: kwargs – Identifying information for a system (i.e. system_name) Returns:
-
handler_names
¶
-
schema
= 'LoggingConfigSchema'¶
-
-
class
brewtils.models.
Event
(name=None, payload=None, error=None, metadata=None, timestamp=None)[source]¶ Bases:
object
-
schema
= 'EventSchema'¶
-
-
class
brewtils.models.
Events
[source]¶ Bases:
enum.Enum
-
ALL_QUEUES_CLEARED
= 15¶
-
BARTENDER_STARTED
= 3¶
-
BARTENDER_STOPPED
= 4¶
-
BREWVIEW_STARTED
= 1¶
-
BREWVIEW_STOPPED
= 2¶
-
INSTANCE_INITIALIZED
= 8¶
-
INSTANCE_STARTED
= 9¶
-
INSTANCE_STOPPED
= 10¶
-
QUEUE_CLEARED
= 14¶
-
REQUEST_COMPLETED
= 7¶
-
REQUEST_CREATED
= 5¶
-
REQUEST_STARTED
= 6¶
-
SYSTEM_CREATED
= 11¶
-
SYSTEM_REMOVED
= 13¶
-
SYSTEM_UPDATED
= 12¶
-
-
class
brewtils.models.
Queue
(name=None, system=None, version=None, instance=None, system_id=None, display=None, size=None)[source]¶ Bases:
object
-
schema
= 'QueueSchema'¶
-
-
class
brewtils.models.
Principal
(id=None, username=None, roles=None, permissions=None, preferences=None, metadata=None)[source]¶ Bases:
object
-
schema
= 'PrincipalSchema'¶
-
-
class
brewtils.models.
Role
(id=None, name=None, description=None, roles=None, permissions=None)[source]¶ Bases:
object
-
schema
= 'RoleSchema'¶
-
-
class
brewtils.models.
RefreshToken
(id=None, issued=None, expires=None, payload=None)[source]¶ Bases:
object
-
schema
= 'RefreshTokenSchema'¶
-
-
class
brewtils.models.
Job
(id=None, name=None, trigger_type=None, trigger=None, request_template=None, misfire_grace_time=None, coalesce=None, next_run_time=None, success_count=None, error_count=None, status=None)[source]¶ Bases:
object
-
STATUS_TYPES
= set(['PAUSED', 'RUNNING'])¶
-
TRIGGER_TYPES
= set(['cron', 'date', 'interval'])¶
-
schema
= 'JobSchema'¶
-
-
class
brewtils.models.
RequestTemplate
(system=None, system_version=None, instance_name=None, command=None, parameters=None, comment=None, metadata=None)[source]¶ Bases:
object
-
schema
= 'RequestTemplateSchema'¶
-
-
class
brewtils.models.
DateTrigger
(run_date=None, timezone=None)[source]¶ Bases:
object
-
schema
= 'DateTriggerSchema'¶
-
brewtils.plugin module¶
-
class
brewtils.plugin.
Plugin
(client, bg_host=None, bg_port=None, ssl_enabled=None, ca_cert=None, client_cert=None, system=None, name=None, description=None, version=None, icon_name=None, instance_name=None, logger=None, parser=None, multithreaded=None, metadata=None, max_concurrent=None, bg_url_prefix=None, **kwargs)[source]¶ Bases:
object
A beer-garden Plugin.
This class represents a beer-garden Plugin - a continuously-running process that can receive and process Requests.
To work, a Plugin needs a Client instance - an instance of a class defining which Requests this plugin can accept and process. The easiest way to define
aClient
is by annotating a class with the@system
decorator.When creating a Plugin you can pass certain keyword arguments to let the Plugin know how to communicate with the beer-garden instance. These are:
bg_host
bg_port
ssl_enabled
ca_cert
client_cert
bg_url_prefix
A Plugin also needs some identifying data. You can either pass parameters to the Plugin or pass a fully defined System object (but not both). Note that some fields are optional:
Plugin( name="Test", version="1.0.0", instance_name="default", description="A Test", )
or:
the_system = System( name="Test", version="1.0.0", instance_name="default, description="A Test", ) Plugin(system=the_system)
If passing parameters directly note that these fields are required:
- name
- Environment variable
BG_NAME
will be used if not specified - version
- Environment variable
BG_VERSION
will be used if not specified - instance_name
- Environment variable
BG_INSTANCE_NAME
will be used if not specified. ‘default’ will be used if not specified and loading from environment variable was unsuccessful
And these fields are optional:
- description (Will use docstring summary line from Client if unspecified)
- icon_name
- metadata
- display_name
Plugins service requests using a
concurrent.futures.ThreadPoolExecutor
. The maximum number of threads available is controlled by the max_concurrent argument (the ‘multithreaded’ argument has been deprecated).Warning
The default value for
max_concurrent
is 1. This means that a Plugin that invokes a Command on itself in the course of processing a Request will deadlock! If you intend to do this, please setmax_concurrent
to a value that makes sense and be aware that Requests are processed in separate thread contexts!Parameters: - client – Instance of a class annotated with @system.
- bg_host (str) – Hostname of a beer-garden.
- bg_port (int) – Port beer-garden is listening on.
- ssl_enabled (bool) – Whether to use SSL for beer-garden communication.
- ca_cert – Certificate that issued the server certificate used by the beer-garden server.
- client_cert – Certificate used by the server making the connection to beer-garden.
- system – The system definition.
- name – The system name.
- description – The system description.
- version – The system version.
- icon_name – The system icon name.
- instance_name (str) – The name of the instance.
- logger (
logging.Logger
.) – A logger that will be used by the Plugin. - parser (
brewtils.schema_parser.SchemaParser
.) – The parser to use when communicating with beer-garden. - multithreaded (bool) – DEPRECATED Process requests in a separate thread.
- worker_shutdown_timeout (int) – Time to wait during shutdown to finish processing.
- metadata (dict) – Metadata specific to this plugin.
- max_concurrent (int) – Maximum number of requests to process concurrently.
- bg_url_prefix (str) – URL Prefix beer-garden is on.
- display_name (str) – The display name to use for the system.
- max_attempts (int) – Number of times to attempt updating the request before giving up (default -1 aka never).
- max_timeout (int) – Maximum amount of time to wait before retrying to update a request.
- starting_timeout (int) – Initial time to wait before the first retry.
- max_instances (int) – Max number of instances allowed for the system.
- ca_verify (bool) – Verify server certificate when making a request.
- username (str) – The username for Beergarden authentication
- password (str) – The password for Beergarden authentication
- access_token – Access token for Beergarden authentication
- refresh_token – Refresh token for Beergarden authentication
-
process_message
(target, request, headers)[source]¶ Process a message. Intended to be run on an Executor.
Parameters: - target – The object to invoke received commands on. (self or self.client)
- request – The parsed Request object
- headers – Dictionary of headers from the brewtils.request_consumer.RequestConsumer
Returns: None
-
brewtils.plugin.
PluginBase
¶ alias of
brewtils.plugin.Plugin
-
class
brewtils.plugin.
RemotePlugin
(client, bg_host=None, bg_port=None, ssl_enabled=None, ca_cert=None, client_cert=None, system=None, name=None, description=None, version=None, icon_name=None, instance_name=None, logger=None, parser=None, multithreaded=None, metadata=None, max_concurrent=None, bg_url_prefix=None, **kwargs)[source]¶ Bases:
brewtils.plugin.Plugin
brewtils.queues module¶
-
class
brewtils.queues.
PikaClient
(host='localhost', port=5672, user='guest', password='guest', connection_attempts=3, heartbeat_interval=3600, virtual_host='/', exchange='beer_garden', ssl=None, blocked_connection_timeout=None, **kwargs)[source]¶ Bases:
object
Base class for connecting to RabbitMQ using Pika
Parameters: - host – RabbitMQ host
- port – RabbitMQ port
- user – RabbitMQ user
- password – RabbitMQ password
- connection_attempts – Maximum number of retry attempts
- heartbeat – Time between RabbitMQ heartbeats
- heartbeat_interval – DEPRECATED, use heartbeat
- virtual_host – RabbitMQ virtual host
- exchange – Default exchange that will be used
- ssl – SSL Options
- blocked_connection_timeout – If not None, the value is a non-negative timeout, in seconds, for the connection to remain blocked (triggered by Connection.Blocked from broker); if the timeout expires before connection becomes unblocked, the connection will be torn down, triggering the adapter-specific mechanism for informing client app about the closed connection (e.g., on_close_callback or ConnectionClosed exception) with reason_code of InternalCloseReasons.BLOCKED_CONNECTION_TIMEOUT.
-
connection_parameters
(**kwargs)[source]¶ Get
ConnectionParameters
associated with this clientWill construct a
ConnectionParameters
object using parameters passed at initialization as defaults. Any parameters passed in kwargs will override initialization parameters.Parameters: **kwargs – Overrides for specific parameters Returns: ConnectionParameters object Return type: pika.ConnectionParameters
-
connection_url
¶ Connection URL for this client’s connection information
Type: str
brewtils.request_consumer module¶
-
class
brewtils.request_consumer.
RequestConsumer
(amqp_url=None, queue_name=None, on_message_callback=None, panic_event=None, logger=None, thread_name=None, **kwargs)[source]¶ Bases:
threading.Thread
RabbitMQ message consumer
This consumer is designed to be fault-tolerant - if RabbitMQ closes the connection the consumer will attempt to reopen it. There are limited reasons why the connection may be closed from the broker side and usually indicates permission related issues or socket timeouts.
Unexpected channel closures can indicate a problem with a command that was issued.
Parameters: - amqp_url (str) – The AMQP url to connection with
- queue_name (str) – The name of the queue to connect to
- on_message_callback (func) – The function called to invoke message processing. Must return a Future.
- panic_event (event) – An event to be set in the event of a catastrophic failure
- logger (
logging.Logger
) – A configured logger - thread_name (str) – The name to use for this thread
- max_connect_retries (int) – Number of connection retry attempts before failure. Default is -1 (retry forever).
- max_connect_backoff (int) – Maximum amount of time to wait between connection retry attempts. Default 30.
- max_concurrent (int) – Maximum requests to process concurrently
-
on_cancelok
(unused_frame)[source]¶ Invoked when RabbitMq acknowledges consumer cancellation
This method is invoked when RabbitMQ acknowledges the cancellation of a consumer. It is unused except for logging purposes.
Parameters: unused_frame (pika.frame.Method) – The Basic.CancelOK frame
-
on_channel_closed
(channel, reply_code, reply_text)[source]¶ Invoked when the connection is closed
Invoked by pika when RabbitMQ unexpectedly closes the channel. Channels are usually closed as a result of something that violates the protocol, such as attempting to re-declare an exchange or queue with different parameters.
This indicates that something has gone wrong, so close the connection to reset.
Parameters: - channel (pika.channel.Channel) – The closed channel
- reply_code (int) – The numeric reason the channel was closed
- reply_text (str) – The text reason the channel was closed
-
on_channel_open
(channel)[source]¶ Invoked when the channel has been opened
Immediately start consuming since the queue bindings are not the consumer’s responsibility.
Parameters: channel (pika.channel.Channel) – The channel object
-
on_connection_closed
(connection, reply_code, reply_text)[source]¶ Invoked when the connection is closed
This method is invoked by pika when the connection to RabbitMQ is closed unexpectedly. This method will attempt to reconnect.
Parameters: - connection (pika.connection.Connection) – the closed connection
- reply_code (int) – The server provided reply_code if given
- reply_text (basestring) – The server provided reply_text if given
-
on_connection_open
(unused_connection)[source]¶ Invoked when the connection has been established
This method is called by pika once the connection to RabbitMQ has been established. It passes the handle to the connection object in case we need it, but in this case, we’ll just mark it unused.
-
on_consumer_cancelled
(method_frame)[source]¶ Invoked when the consumer is canceled by the broker
This method will simply close the channel if it exists.
Parameters: method_frame (pika.frame.Method) – The Basic.Cancel frame
-
on_message
(channel, basic_deliver, properties, body)[source]¶ Invoked when a message is delivered from the queueing service
Invoked by pika when a message is delivered from RabbitMQ. The channel is passed for your convenience. The basic_deliver object that is passed in carries the exchange, routing key, delivery tag and a redelivered flag for the message. the properties passed in is an instance of BasicProperties with the message properties and the body is the message that was sent.
Parameters: - channel (pika.channel.Channel) – The channel object
- basic_deliver (pika.Spec.Basic.Deliver) – basic_deliver method
- properties (pika.Spec.BasicProperties) – properties
- body (bytes) – The message body
-
on_message_callback_complete
(basic_deliver, future)[source]¶ Invoked when the future returned by _on_message_callback completes.
Parameters: - basic_deliver (pika.Spec.Basic.Deliver) – basic_deliver method
- future (concurrent.futures.Future) – Completed future
Returns: None
-
open_channel
()[source]¶ Open a channel using the connection
When RabbitMQ responds that the channel is open, the on_channel_open callback will be invoked.
-
open_connection
()[source]¶ Opens a connection to RabbitMQ
This method connects to RabbitMQ, returning the connection handle. The on_connection_open method will be invoked when the connection opens.
Return type: pika.SelectConnection
-
run
()[source]¶ Run the consumer
Creates a connection to RabbitMQ and starts the IOLoop. The IOLoop will block and allow the SelectConnection to operate.
Returns:
-
start_consuming
()[source]¶ Begin consuming messages
The RabbitMQ prefetch is set to the maximum number of concurrent consumers. This ensures that messages remain in RabbitMQ until a consuming thread is available to process them.
An on_cancel_callback is registered so that the consumer is notified if it is canceled by the broker.
brewtils.schema_parser module¶
-
class
brewtils.schema_parser.
SchemaParser
[source]¶ Bases:
object
Serialize and deserialize Brewtils models
-
logger
= <logging.Logger object>¶
-
classmethod
parse_command
(command, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a command model object
Parameters: - command – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A Command object
-
classmethod
parse_event
(event, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to an event model object
Parameters: - event – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: An Event object
-
classmethod
parse_instance
(instance, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to an instance model object
Parameters: - instance – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: An Instance object
-
classmethod
parse_job
(job, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a job model object
Parameters: - job – Raw input
- from_string – True if input is a JSON string, False if a dictionary
- **kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A Job object.
-
classmethod
parse_logging_config
(logging_config, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a logging config model object
Note: for our logging_config, many is _always_ set to False. We will always return a dict from this method.
Parameters: - logging_config – The raw input
- from_string – True if ‘input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A LoggingConfig object
-
classmethod
parse_parameter
(parameter, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a parameter model object
Parameters: - parameter – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: An Parameter object
-
classmethod
parse_patch
(patch, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a patch model object
Note: for our patches, many is _always_ set to True. We will always return a list from this method.
Parameters: - patch – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A PatchOperation object
-
classmethod
parse_principal
(principal, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a principal model object
Parameters: - principal – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A Principal object
-
classmethod
parse_queue
(queue, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a queue model object
Parameters: - queue – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A Queue object
-
classmethod
parse_refresh_token
(refresh_token, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a refresh token object
Parameters: - refresh_token – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A RefreshToken object
-
classmethod
parse_request
(request, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a request model object
Parameters: - request – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A Request object
-
classmethod
parse_role
(role, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a role model object
Parameters: - role – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A Role object
-
classmethod
parse_system
(system, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a system model object
Parameters: - system – The raw input
- from_string – True if input is a JSON string, False if a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: A System object
-
classmethod
serialize_command
(command, to_string=True, **kwargs)[source]¶ Convert a command model into serialized form
Parameters: - command – The command object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of command
-
classmethod
serialize_event
(event, to_string=True, **kwargs)[source]¶ Convert a logging config model into serialized form
Parameters: - event – The event object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of event
-
classmethod
serialize_instance
(instance, to_string=True, **kwargs)[source]¶ Convert an instance model into serialized form
Parameters: - instance – The instance object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of instance
-
classmethod
serialize_job
(job, to_string=True, **kwargs)[source]¶ Convert a job model into serialized form.
Parameters: - job – The job object(s) to be serialized.
- to_string – True to generate a JSON-formatted string, False to generate a dictionary.
- **kwargs – Additional parameters to be passed to the shcema (e.g. many=True)
Returns: Serialize representation of job.
-
classmethod
serialize_logging_config
(logging_config, to_string=True, **kwargs)[source]¶ Convert a logging config model into serialize form
Parameters: - logging_config – The logging config object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of logging config
-
classmethod
serialize_parameter
(parameter, to_string=True, **kwargs)[source]¶ Convert a parameter model into serialized form
Parameters: - parameter – The parameter object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of parameter
-
classmethod
serialize_patch
(patch, to_string=True, **kwargs)[source]¶ Convert a patch model into serialized form
Parameters: - patch – The patch object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of patch
-
classmethod
serialize_principal
(principal, to_string=True, **kwargs)[source]¶ Convert a principal model into serialized form
Parameters: - principal – The principal object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation
-
classmethod
serialize_queue
(queue, to_string=True, **kwargs)[source]¶ Convert a queue model into serialized form
Parameters: - queue – The queue object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of queue
-
classmethod
serialize_refresh_token
(refresh_token, to_string=True, **kwargs)[source]¶ Convert a role model into serialized form
Parameters: - refresh_token – The token object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation
-
classmethod
serialize_request
(request, to_string=True, **kwargs)[source]¶ Convert a request model into serialized form
Parameters: - request – The request object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of request
-
classmethod
serialize_role
(role, to_string=True, **kwargs)[source]¶ Convert a role model into serialized form
Parameters: - role – The role object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation
-
classmethod
serialize_system
(system, to_string=True, include_commands=True, **kwargs)[source]¶ Convert a system model into serialized form
Parameters: - system – The system object(s) to be serialized
- to_string – True to generate a JSON-formatted string, False to generate a dictionary
- include_commands – True if the system’s command list should be included
- kwargs – Additional parameters to be passed to the Schema (e.g. many=True)
Returns: Serialized representation of system
-
brewtils.schemas module¶
-
class
brewtils.schemas.
SystemSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
InstanceSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
CommandSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
ParameterSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
RequestSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.RequestTemplateSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
PatchSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
LoggingConfigSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
EventSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
QueueSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
PrincipalSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
RoleSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
RefreshTokenSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
JobSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
DateTriggerSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
brewtils.specification module¶
brewtils.stoppable_thread module¶
Module contents¶
-
brewtils.
command
(_wrapped=None, command_type='ACTION', output_type='STRING', schema=None, form=None, template=None, icon_name=None, description=None)[source]¶ Decorator that marks a function as a beer-garden command
For example:
@command(output_type='JSON') def echo_json(self, message): return message
Parameters: - _wrapped – The function to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- command_type – The command type. Valid options are Command.COMMAND_TYPES.
- output_type – The output type. Valid options are Command.OUTPUT_TYPES.
- schema – A custom schema definition.
- form – A custom form definition.
- template – A custom template definition.
- icon_name – The icon name. Should be either a FontAwesome or a Glyphicon name.
- description – The command description. Will override the function’s docstring.
Returns: The decorated function.
-
brewtils.
parameter
(_wrapped=None, key=None, type=None, multi=None, display_name=None, optional=None, default=None, description=None, choices=None, nullable=None, maximum=None, minimum=None, regex=None, is_kwarg=None, model=None, form_input_type=None)[source]¶ Decorator that enables Parameter specifications for a beer-garden Command
This decorator is intended to be used when more specification is desired for a Parameter.
For example:
@parameter(key="message", description="Message to echo", optional=True, type="String", default="Hello, World!") def echo(self, message): return message
Parameters: - _wrapped – The function to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- key – String specifying the parameter identifier. Must match an argument name of the decorated function.
- type – String indicating the type to use for this parameter.
- multi – Boolean indicating if this parameter is a multi. See documentation for discussion of what this means.
- display_name – String that will be displayed as a label in the user interface.
- optional – Boolean indicating if this parameter must be specified.
- default – The value this parameter will be assigned if not overridden when creating a request.
- description – An additional string that will be displayed in the user interface.
- choices – List or dictionary specifying allowed values. See documentation for more information.
- nullable – Boolean indicating if this parameter is allowed to be null.
- maximum – Integer indicating the maximum value of the parameter.
- minimum – Integer indicating the minimum value of the parameter.
- regex – String describing a regular expression constraint on the parameter.
- is_kwarg – Boolean indicating if this parameter is meant to be part of the decorated function’s kwargs.
- model – Class to be used as a model for this parameter. Must be a Python type object, not an instance.
- form_input_type – Only used for string fields. Changes the form input field (e.g. textarea)
Returns: The decorated function.
-
brewtils.
system
(cls)[source]¶ Class decorator that marks a class as a beer-garden System
Creates a
_commands
property on the class that holds all registered commands.Parameters: cls – The class to decorated Returns: The decorated class
-
class
brewtils.
Plugin
(client, bg_host=None, bg_port=None, ssl_enabled=None, ca_cert=None, client_cert=None, system=None, name=None, description=None, version=None, icon_name=None, instance_name=None, logger=None, parser=None, multithreaded=None, metadata=None, max_concurrent=None, bg_url_prefix=None, **kwargs)[source]¶ Bases:
object
A beer-garden Plugin.
This class represents a beer-garden Plugin - a continuously-running process that can receive and process Requests.
To work, a Plugin needs a Client instance - an instance of a class defining which Requests this plugin can accept and process. The easiest way to define
aClient
is by annotating a class with the@system
decorator.When creating a Plugin you can pass certain keyword arguments to let the Plugin know how to communicate with the beer-garden instance. These are:
bg_host
bg_port
ssl_enabled
ca_cert
client_cert
bg_url_prefix
A Plugin also needs some identifying data. You can either pass parameters to the Plugin or pass a fully defined System object (but not both). Note that some fields are optional:
Plugin( name="Test", version="1.0.0", instance_name="default", description="A Test", )
or:
the_system = System( name="Test", version="1.0.0", instance_name="default, description="A Test", ) Plugin(system=the_system)
If passing parameters directly note that these fields are required:
- name
- Environment variable
BG_NAME
will be used if not specified - version
- Environment variable
BG_VERSION
will be used if not specified - instance_name
- Environment variable
BG_INSTANCE_NAME
will be used if not specified. ‘default’ will be used if not specified and loading from environment variable was unsuccessful
And these fields are optional:
- description (Will use docstring summary line from Client if unspecified)
- icon_name
- metadata
- display_name
Plugins service requests using a
concurrent.futures.ThreadPoolExecutor
. The maximum number of threads available is controlled by the max_concurrent argument (the ‘multithreaded’ argument has been deprecated).Warning
The default value for
max_concurrent
is 1. This means that a Plugin that invokes a Command on itself in the course of processing a Request will deadlock! If you intend to do this, please setmax_concurrent
to a value that makes sense and be aware that Requests are processed in separate thread contexts!Parameters: - client – Instance of a class annotated with @system.
- bg_host (str) – Hostname of a beer-garden.
- bg_port (int) – Port beer-garden is listening on.
- ssl_enabled (bool) – Whether to use SSL for beer-garden communication.
- ca_cert – Certificate that issued the server certificate used by the beer-garden server.
- client_cert – Certificate used by the server making the connection to beer-garden.
- system – The system definition.
- name – The system name.
- description – The system description.
- version – The system version.
- icon_name – The system icon name.
- instance_name (str) – The name of the instance.
- logger (
logging.Logger
.) – A logger that will be used by the Plugin. - parser (
brewtils.schema_parser.SchemaParser
.) – The parser to use when communicating with beer-garden. - multithreaded (bool) – DEPRECATED Process requests in a separate thread.
- worker_shutdown_timeout (int) – Time to wait during shutdown to finish processing.
- metadata (dict) – Metadata specific to this plugin.
- max_concurrent (int) – Maximum number of requests to process concurrently.
- bg_url_prefix (str) – URL Prefix beer-garden is on.
- display_name (str) – The display name to use for the system.
- max_attempts (int) – Number of times to attempt updating the request before giving up (default -1 aka never).
- max_timeout (int) – Maximum amount of time to wait before retrying to update a request.
- starting_timeout (int) – Initial time to wait before the first retry.
- max_instances (int) – Max number of instances allowed for the system.
- ca_verify (bool) – Verify server certificate when making a request.
- username (str) – The username for Beergarden authentication
- password (str) – The password for Beergarden authentication
- access_token – Access token for Beergarden authentication
- refresh_token – Refresh token for Beergarden authentication
-
process_message
(target, request, headers)[source]¶ Process a message. Intended to be run on an Executor.
Parameters: - target – The object to invoke received commands on. (self or self.client)
- request – The parsed Request object
- headers – Dictionary of headers from the brewtils.request_consumer.RequestConsumer
Returns: None
-
class
brewtils.
RemotePlugin
(client, bg_host=None, bg_port=None, ssl_enabled=None, ca_cert=None, client_cert=None, system=None, name=None, description=None, version=None, icon_name=None, instance_name=None, logger=None, parser=None, multithreaded=None, metadata=None, max_concurrent=None, bg_url_prefix=None, **kwargs)[source]¶ Bases:
brewtils.plugin.Plugin
-
class
brewtils.
EasyClient
(bg_host=None, bg_port=None, ssl_enabled=False, api_version=None, ca_cert=None, client_cert=None, parser=None, logger=None, url_prefix=None, ca_verify=True, **kwargs)[source]¶ Bases:
object
Client for simplified communication with Beergarden
This class is intended to be a middle ground between the RestClient and SystemClient. It provides a ‘cleaner’ interface to some common Beergarden operations than is exposed by the lower-level RestClient. On the other hand, the SystemClient is much better for generating Beergarden Requests.
Keyword Arguments: - bg_host (str) – Beergarden hostname
- bg_port (int) – Beergarden port
- ssl_enabled (Optional[bool]) – Whether to use SSL (HTTP vs HTTPS)
- api_version (Optional[int]) – The REST API version
- ca_cert (Optional[str]) – Path to CA certificate file
- client_cert (Optional[str]) – Path to client certificate file
- parser (Optional[SchemaParser]) – Parser to use
- logger (Optional[Logger]) – Logger to use
- url_prefix (Optional[str]) – Beergarden REST API prefix
- ca_verify (Optional[bool]) – Whether to verify the server cert hostname
- username (Optional[str]) – Username for authentication
- password (Optional[str]) – Password for authentication
- access_token (Optional[str]) – Access token for authentication
- refresh_token (Optional[str]) – Refresh token for authentication
- client_timeout (Optional[float]) – Max time to wait for a server response
-
can_connect
(**kwargs)[source]¶ Determine if the Beergarden server is responding.
- Kwargs:
- Arguments passed to the underlying Requests method
Returns: A bool indicating if the connection attempt was successful. Will return False only if a ConnectionError is raised during the attempt. Any other exception will be re-raised. Raises: requests.exceptions.RequestException
– The connection attempt resulted in an exception that indicates something other than a basic connection error. For example, an error with certificate verification.
-
clear_all_queues
()[source]¶ Cancel and remove all Requests in all queues
Returns: True if the clear was successful Return type: bool
-
clear_queue
(queue_name)[source]¶ Cancel and remove all Requests from a message queue
Parameters: queue_name (str) – The name of the queue to clear Returns: True if the clear was successful Return type: bool
-
create_job
(job)[source]¶ Create a new Job
Parameters: job (Job) – New Job definition Returns: The newly-created Job Return type: Job
-
create_request
(request, **kwargs)[source]¶ Create a new Request
Parameters: - request – New request definition
- kwargs – Extra request parameters
Keyword Arguments: - blocking (bool) – Wait for request to complete before returning
- timeout (int) – Maximum seconds to wait for completion
Returns: The newly-created Request
Return type:
-
create_system
(system)[source]¶ Create a new System
Parameters: system (System) – The System to create Returns: The newly-created system Return type: System
-
find_jobs
(**kwargs)[source]¶ Find Jobs using keyword arguments as search parameters
Parameters: **kwargs – Search parameters Returns: List of Jobs matching the search parameters Return type: List[Job]
-
find_requests
(**kwargs)[source]¶ Find Requests using keyword arguments as search parameters
Parameters: **kwargs – Search parameters Returns: List of Systems matching the search parameters Return type: List[Request]
-
find_systems
(**kwargs)[source]¶ Find Systems using keyword arguments as search parameters
Parameters: **kwargs – Search parameters Returns: List of Systems matching the search parameters Return type: List[System]
-
find_unique_request
(**kwargs)[source]¶ Find a unique request
Note
If ‘id’ is a given keyword argument then all other parameters will be ignored.
Parameters: **kwargs – Search parameters Returns: The Request if found, None otherwise Return type: Request, None Raises: FetchError
– More than one matching Request was found
-
find_unique_system
(**kwargs)[source]¶ Find a unique system
Note
If ‘id’ is a given keyword argument then all other parameters will be ignored.
Parameters: **kwargs – Search parameters Returns: The System if found, None otherwise Return type: System, None Raises: FetchError
– More than one matching System was found
-
get_instance
(instance_id)[source]¶ Get an Instance
Parameters: instance_id – The Id Returns: The Instance
-
get_instance_status
(instance_id)[source]¶ Get an Instance
WARNING: This method currently returns the Instance, not the Instance’s status. This behavior will be corrected in 3.0.
To prepare for this change please use get_instance() instead of this method.
Parameters: instance_id – The Id Returns: The status
-
get_logging_config
(system_name)[source]¶ Get logging configuration for a System
Parameters: system_name (str) – The name of the System Returns: The configuration object Return type: LoggingConfig
-
get_user
(user_identifier)[source]¶ Find a user
Parameters: user_identifier (str) – User ID or username Returns: The User Return type: Principal
-
get_version
(**kwargs)[source]¶ Get Bartender, Brew-view, and API version information
Parameters: **kwargs – Extra parameters Returns: Response object with version information in the body Return type: dict
-
initialize_instance
(instance_id)[source]¶ Start an Instance
Parameters: instance_id (str) – The Instance ID Returns: The updated Instance Return type: Instance
-
instance_heartbeat
(instance_id)[source]¶ Send an Instance heartbeat
Parameters: instance_id (str) – The Instance ID Returns: True if the heartbeat was successful Return type: bool
-
pause_job
(job_id)[source]¶ Pause a Job
Parameters: job_id (str) – The Job ID Returns: The updated Job Return type: Job
-
publish_event
(*args, **kwargs)[source]¶ Publish a new event
Parameters: - *args – If a positional argument is given it’s assumed to be an Event and will be used
- **kwargs – Will be used to construct a new Event to publish if no Event is given in the positional arguments
Keyword Arguments: _publishers (Optional[List[str]]) – List of publisher names. If given the Event will only be published to the specified publishers. Otherwise all publishers known to Beergarden will be used.
Returns: True if the publish was successful
Return type: bool
-
remove_instance
(instance_id)[source]¶ Remove an Instance
Parameters: instance_id (str) – The Instance ID Returns: True if the remove was successful Return type: bool
-
remove_job
(job_id)[source]¶ Remove a unique Job
Parameters: job_id (str) – The Job ID Returns: True if removal was successful Return type: bool Raises: DeleteError
– Couldn’t remove Job
-
remove_system
(**kwargs)[source]¶ Remove a unique System
Parameters: **kwargs – Search parameters Returns: True if removal was successful Return type: bool Raises: FetchError
– Couldn’t find a System matching given parameters
-
resume_job
(job_id)[source]¶ Resume a Job
Parameters: job_id (str) – The Job ID Returns: The updated Job Return type: Job
-
update_instance_status
(instance_id, new_status)[source]¶ Update an Instance status
Parameters: - instance_id (str) – The Instance ID
- new_status (str) – The new status
Returns: The updated Instance
Return type:
-
update_request
(request_id, status=None, output=None, error_class=None)[source]¶ Update a Request
Parameters: - request_id (str) – The Request ID
- status (Optional[str]) – New Request status
- output (Optional[str]) – New Request output
- error_class (Optional[str]) – New Request error class
Returns: The updated response
Return type: Response
-
update_system
(system_id, new_commands=None, **kwargs)[source]¶ Update a System
Parameters: - system_id (str) – The System ID
- new_commands (Optional[List[Command]]) – New System commands
Keyword Arguments: - metadata (dict) – New System metadata
- description (str) – New System description
- display_name (str) – New System display name
- icon_name (str) – New System icon name
Returns: The updated system
Return type:
-
class
brewtils.
SystemClient
(bg_host=None, bg_port=None, system_name=None, 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, raise_on_error=False, **kwargs)[source]¶ 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 FetchError 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
ConnectionTimeoutError
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.
- raise_on_error – Raises an error if the request ends in an error state.
- username – Username for Beergarden authentication
- password – Password for Beergarden authentication
- access_token – Access token for Beergarden authentication
- refresh_token – Refresh token for Beergarden authentication
- client_timeout – Max time to will wait for server response
-
create_bg_request
(command_name, **kwargs)[source]¶ 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
()[source]¶ 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: FetchError – If unable to find a matching System Returns: None
-
send_bg_request
(**kwargs)[source]¶ 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: ValidationError – 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.
-
brewtils.
get_easy_client
(**kwargs)[source]¶ Easy way to get an EasyClient
The benefit to this method over creating an EasyClient directly is that this method will also search the environment for parameters. Kwargs passed to this method will take priority, however.
Parameters: **kwargs – Options for configuring the EasyClient Returns: The configured client Return type: brewtils.rest.easy_client.EasyClient
-
brewtils.
get_argument_parser
()[source]¶ Get an ArgumentParser pre-populated with Brewtils arguments
This is helpful if you’re expecting additional command line arguments to a plugin startup script.
This enables doing something like:
def main(): parser = get_argument_parser() parser.add_argument('positional_arg') parsed_args = parser.parse_args(sys.argv[1:]) # Now you can use the extra argument client = MyClient(parsed_args.positional_arg) # But you'll need to be careful when using the 'normal' Brewtils # configuration loading methods: # Option 1: Tell Brewtils about your customized parser connection = get_connection_info(cli_args=sys.argv[1:], argument_parser=parser) # Option 2: Use the parsed CLI as a dictionary connection = get_connection_info(**vars(parsed_args)) # Now specify connection kwargs like normal plugin = RemotePlugin(client, name=... **connection)
IMPORTANT: Note that in both cases the returned
connection
object will not contain your new value. Both options just prevent normal CLI parsing from failing on the unknown argument.Returns: ArgumentParser: Argument parser with Brewtils arguments loaded
-
brewtils.
get_connection_info
(cli_args=None, argument_parser=None, **kwargs)[source]¶ Wrapper around
load_config
that returns only connection parametersParameters: - cli_args (list, optional) – List of command line arguments for configuration loading
- argument_parser (ArgumentParser, optional) – Argument parser to use when parsing cli_args. Supplying this allows adding additional arguments prior to loading the configuration. This can be useful if your startup script takes additional arguments.
- **kwargs – Additional configuration overrides
Returns: dict: Parameters needed to make a connection to Beergarden
-
brewtils.
load_config
(cli_args=None, argument_parser=None, **kwargs)[source]¶ Load configuration using Yapconf
Configuration will be loaded from these sources, with earlier sources having higher priority:
**kwargs
passed to this methodcli_args
passed to this method- Environment variables using the
BG_
prefix - Default values in the brewtils specification
Parameters: - cli_args (list, optional) – List of command line arguments for configuration loading
- argument_parser (ArgumentParser, optional) – Argument parser to use when parsing cli_args. Supplying this allows adding additional arguments prior to loading the configuration. This can be useful if your startup script takes additional arguments. See get_argument_parser for additional information.
- **kwargs – Additional configuration overrides
Returns: The resolved configuration object
Return type: box.Box
-
brewtils.
get_bg_connection_parameters
(cli_args=None, argument_parser=None, **kwargs)¶ Wrapper around
load_config
that returns only connection parametersParameters: - cli_args (list, optional) – List of command line arguments for configuration loading
- argument_parser (ArgumentParser, optional) – Argument parser to use when parsing cli_args. Supplying this allows adding additional arguments prior to loading the configuration. This can be useful if your startup script takes additional arguments.
- **kwargs – Additional configuration overrides
Returns: dict: Parameters needed to make a connection to Beergarden