brewtils package¶
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: Dictionary containing the parse results
Raises: lark.common.ParseError
– Unable to find a valid parsing of input_string
brewtils.decorators module¶
-
brewtils.decorators.
client
(_wrapped=None, bg_name=None, bg_version=None)[source]¶ Class decorator that marks a class as a beer-garden Client
Using this decorator is no longer strictly necessary. It was previously required in order to mark a class as being a Beer-garden Client, and contained most of the logic that currently resides in the
parse_client
function. However, that’s no longer the case and this currently exists mainly for back-compatibility reasons.Applying this decorator to a client class does have the nice effect of preventing linters from complaining if any special attributes are used. So that’s something.
Those special attributes are below. Note that these are just placeholders until the actual values are populated when the client instance is assigned to a Plugin:
_bg_name
: an optional system name_bg_version
: an optional system version_bg_commands
: holds all registered commands_current_request
: Reference to the currently executing request
Parameters: - _wrapped – The class to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- bg_name – Optional plugin name
- bg_version – Optional plugin version
Returns: The decorated class
-
brewtils.decorators.
command
(_wrapped=None, description=None, parameters=None, command_type='ACTION', output_type='STRING', schema=None, form=None, template=None, icon_name=None, hidden=False)[source]¶ Decorator for specifying Command details
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.
- description – The command description. If not given the first line of the method docstring will be used.
- parameters – A list of Command parameters. It’s recommended to use @parameter decorators to declare Parameters instead of declaring them here, but it is allowed. Any Parameters given here will be merged with Parameters sourced from decorators and inferred from the method signature.
- 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.
- hidden – Flag controlling whether the command is visible on the user interface.
Returns: The decorated function
-
brewtils.decorators.
parameter
(_wrapped=None, key=None, 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, type_info=None, is_kwarg=None, model=None)[source]¶ Decorator for specifying Parameter details
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. If the decorated object is a method the key must match an argument name.
- 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.
- parameters – Any nested parameters. See also: the ‘model’ argument.
- 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.
- form_input_type – Specify the form input field type (e.g. textarea). Only used for string fields.
- type_info – Type-specific information. Mostly reserved for future use.
- is_kwarg – Boolean indicating if this parameter is meant to be part of the decorated function’s kwargs. Only applies when the decorated object is a method.
- model – Class to be used as a model for this parameter. Must be a Python type object, not an instance.
Returns: The decorated function
-
brewtils.decorators.
parameters
(*args, **kwargs)[source]¶ Decorator for specifying 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.
- **kwargs – Used for bookkeeping. Don’t set any of these yourself!
Returns: The decorated function
Return type: func
-
brewtils.decorators.
system
(_wrapped=None, bg_name=None, bg_version=None)¶ Class decorator that marks a class as a beer-garden Client
Using this decorator is no longer strictly necessary. It was previously required in order to mark a class as being a Beer-garden Client, and contained most of the logic that currently resides in the
parse_client
function. However, that’s no longer the case and this currently exists mainly for back-compatibility reasons.Applying this decorator to a client class does have the nice effect of preventing linters from complaining if any special attributes are used. So that’s something.
Those special attributes are below. Note that these are just placeholders until the actual values are populated when the client instance is assigned to a Plugin:
_bg_name
: an optional system name_bg_version
: an optional system version_bg_commands
: holds all registered commands_current_request
: Reference to the currently executing request
Parameters: - _wrapped – The class to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- bg_name – Optional plugin name
- bg_version – Optional plugin version
Returns: The decorated class
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
-
exception
brewtils.errors.
BGGivesUpError
[source]¶ Bases:
brewtils.errors.RequestProcessException
Special exception that indicates Beer-garden is giving up
This exception is not raised directly, instead it’s a special value for a request’s error_class attribute. It indicates the request may have information that has not been persisted to the database, but Beer-garden is choosing to abandon further attempts to update it.
Typically indicates a request output is too large or the maximum number of update retry attempts has been reached.
-
brewtils.errors.
BGNotFoundError
¶ alias of
brewtils.errors.NotFoundError
-
brewtils.errors.
BGRequestFailedError
¶ alias of
brewtils.errors.RequestFailedError
-
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.
ErrorLogLevelCritical
[source]¶ Bases:
exceptions.Exception
Mixin to log an exception at the CRITICAL level
-
exception
brewtils.errors.
ErrorLogLevelDebug
[source]¶ Bases:
exceptions.Exception
Mixin to log an exception at the DEBUG level
-
exception
brewtils.errors.
ErrorLogLevelError
[source]¶ Bases:
exceptions.Exception
Mixin to log an exception at the ERROR level
-
exception
brewtils.errors.
ErrorLogLevelInfo
[source]¶ Bases:
exceptions.Exception
Mixin to log an exception at the INFO level
-
exception
brewtils.errors.
ErrorLogLevelWarning
[source]¶ Bases:
exceptions.Exception
Mixin to log an exception at the WARNING level
-
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 – The Request to republish
- headers – A dictionary of headers to be used by brewtils.pika.PikaConsumer
-
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.
SuppressStacktrace
[source]¶ Bases:
exceptions.Exception
Mixin that will suppress stacktrace logging
-
exception
brewtils.errors.
TimeoutExceededError
[source]¶ Bases:
brewtils.errors.RestClientError
Error indicating a timeout occurred waiting for a request to complete
-
exception
brewtils.errors.
TooLargeError
[source]¶ Bases:
brewtils.errors.RestClientError
Error indicating a 413 was raised on the server
-
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
(raw_config, namespace=None, system_name=None, system_version=None, instance_name=None)[source]¶ Load and enable a logging configuration from Beergarden
WARNING: This method will modify the current logging configuration.
The configuration will be template substituted using the keyword arguments passed to this function. For example, a handler like this:
handlers: file: backupCount: 5 class: "logging.handlers.RotatingFileHandler" encoding: utf8 formatter: default level: INFO maxBytes: 10485760 filename: "$system_name.log"
Will result in logging to a file with the same name as the given system_name.
This will also ensure that directories exist for any file-based handlers. Default behavior for the Python logging module is to not create directories that do not already exist, which would dramatically lower the utility of templating.
Parameters: - raw_config – Configuration to apply
- namespace – Used for configuration templating
- system_name – Used for configuration templating
- system_version – Used for configuration templating
- instance_name – Used for configuration templating
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.
default_config
(level='INFO')[source]¶ Get a basic logging configuration with the given level
-
brewtils.log.
find_log_file
()[source]¶ Find the file name for the first file handler attached to the root logger
-
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.
read_log_file
(log_file, start_line=None, end_line=None)[source]¶ Read lines from a log file
Parameters: - log_file – The file to read from
- start_line – Starting line to read
- end_line – Ending line to read
Returns: Lines read from the file
-
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, namespace=None, local=None)[source]¶ Bases:
brewtils.models.BaseModel
-
get_command_by_name
(command_name)[source]¶ Retrieve a particular command from the system
Parameters: command_name (str) – The command name Returns: The command if it exists, None otherwise Return type: Command
-
get_instance_by_id
(id, raise_missing=False)[source]¶ Get an instance that currently exists in the system
Parameters: - id (str) – The instance id
- raise_missing (bool) – If True, raise an exception if an Instance with the
- id is not found. If False, will return None in that case. (given) –
Returns: The instance if it exists, None otherwise
Return type: Raises: ModelError
– Instance was not found and raise_missing=True
-
get_instance_by_name
(name, raise_missing=False)[source]¶ Get an instance that currently exists in the system
Parameters: - name (str) – The instance name
- raise_missing (bool) – If True, raise an exception if an Instance with the
- name is not found. If False, will return None in that case. (given) –
Returns: The instance if it exists, None otherwise
Return type: Raises: ModelError
– Instance was not found and raise_missing=True
-
has_different_commands
(commands)[source]¶ Check if a set of commands is different than the current commands
Parameters: commands (Sequence[Command]) – Command collection for comparison Returns: True if the given Commands differ, False if they are identical Return type: bool
-
has_instance
(name)[source]¶ Determine if an instance currently exists in the system
Parameters: name (str) – The instance name Returns: True if an instance with the given name exists, False otherwise Return type: bool
-
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:
brewtils.models.BaseModel
-
INSTANCE_STATUSES
= set(['DEAD', 'INITIALIZING', 'PAUSED', 'RUNNING', 'STARTING', 'STOPPED', 'STOPPING', 'UNKNOWN', 'UNRESPONSIVE'])¶
-
schema
= 'InstanceSchema'¶
-
-
class
brewtils.models.
Command
(name=None, description=None, parameters=None, command_type=None, output_type=None, schema=None, form=None, template=None, icon_name=None, hidden=False)[source]¶ Bases:
brewtils.models.BaseModel
-
COMMAND_TYPES
= ('ACTION', 'INFO', 'EPHEMERAL', 'ADMIN')¶
-
OUTPUT_TYPES
= ('STRING', 'JSON', 'XML', 'HTML', 'JS', 'CSS')¶
-
get_parameter_by_key
(key)[source]¶ Lookup a Parameter using a given key
Parameters: key (str) – The Parameter key to use Returns: A Parameter with the given key If a Parameter with the given key does not exist None will be returned.
Return type: Parameter (Optional)
-
has_different_parameters
(parameters)[source]¶ Determine if parameters differ from the current parameters
Parameters: parameters (Sequence[Parameter]) – Parameter collection for comparison Returns: True if the given Parameters differ, False if they are identical Return type: bool
-
parameter_keys
()[source]¶ Get a list of all Parameter keys
Returns: A list containing each Parameter’s key attribute Return type: list[str]
-
parameter_keys_by_type
(desired_type)[source]¶ Get a list of all Parameter keys, filtered by Parameter type
Parameters: desired_type (str) – Parameter type Returns: A list containing matching Parameters’ key attribute Return type: list[str]
-
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, type_info=None, is_kwarg=None, model=None)[source]¶ Bases:
brewtils.models.BaseModel
-
FORM_INPUT_TYPES
= ('textarea',)¶
-
TYPES
= ('String', 'Integer', 'Float', 'Boolean', 'Any', 'Dictionary', 'Date', 'DateTime', 'Bytes', 'Base64')¶
-
keys_by_type
(desired_type)[source]¶ Gets all keys by the specified type.
Since parameters can be nested, this method will also return all keys of all nested parameters. The return value is a possibly nested list, where the first value of each list is going to be a string, while the next value is a list.
Parameters: desired_type (str) – Desired type Returns: An empty list if the type does not exist, otherwise it will be a list containing at least one entry which is a string, each subsequent entry is a nested list with the same structure.
-
schema
= 'ParameterSchema'¶
-
-
class
brewtils.models.
Request
(system=None, system_version=None, instance_name=None, namespace=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, hidden=None, updated_at=None, has_parent=None, requester=None)[source]¶ Bases:
brewtils.models.RequestTemplate
-
COMMAND_TYPES
= ('ACTION', 'INFO', 'EPHEMERAL', 'ADMIN')¶
-
COMPLETED_STATUSES
= ('CANCELED', 'SUCCESS', 'ERROR')¶
-
OUTPUT_TYPES
= ('STRING', 'JSON', 'XML', 'HTML', 'JS', 'CSS')¶
-
STATUS_LIST
= ('CREATED', 'RECEIVED', 'IN_PROGRESS', 'CANCELED', 'SUCCESS', 'ERROR')¶
-
classmethod
from_template
(template, **kwargs)[source]¶ Create a Request instance from a RequestTemplate
Parameters: - template – The RequestTemplate to use
- **kwargs – Optional overrides to use in place of the template’s attributes
Returns: The new Request instance
-
is_ephemeral
¶
-
is_json
¶
-
schema
= 'RequestSchema'¶
-
status
¶
-
-
class
brewtils.models.
PatchOperation
(operation=None, path=None, value=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'PatchSchema'¶
-
-
class
brewtils.models.
Choices
(type=None, display=None, value=None, strict=None, details=None)[source]¶ Bases:
brewtils.models.BaseModel
-
DISPLAYS
= ('select', 'typeahead')¶
-
TYPES
= ('static', 'url', 'command')¶
-
schema
= 'ChoicesSchema'¶
-
-
class
brewtils.models.
LoggingConfig
(level=None, handlers=None, formatters=None, loggers=None)[source]¶ Bases:
brewtils.models.BaseModel
-
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.
Keyword Arguments: information for a system (Identifying) – Returns: The logging configuration for this system
-
handler_names
¶
-
schema
= 'LoggingConfigSchema'¶
-
-
class
brewtils.models.
Event
(name=None, namespace=None, garden=None, metadata=None, timestamp=None, payload_type=None, payload=None, error=None, error_message=None)[source]¶ Bases:
brewtils.models.BaseModel
-
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¶
-
DB_CREATE
= 16¶
-
DB_DELETE
= 18¶
-
DB_UPDATE
= 17¶
-
ENTRY_STARTED
= 31¶
-
ENTRY_STOPPED
= 32¶
-
FILE_CREATED
= 24¶
-
GARDEN_CREATED
= 19¶
-
GARDEN_ERROR
= 28¶
-
GARDEN_NOT_CONFIGURED
= 29¶
-
GARDEN_REMOVED
= 21¶
-
GARDEN_STARTED
= 25¶
-
GARDEN_STOPPED
= 26¶
-
GARDEN_SYNC
= 30¶
-
GARDEN_UNREACHABLE
= 27¶
-
GARDEN_UPDATED
= 20¶
-
INSTANCE_INITIALIZED
= 8¶
-
INSTANCE_STARTED
= 9¶
-
INSTANCE_STOPPED
= 10¶
-
INSTANCE_UPDATED
= 23¶
-
JOB_CREATED
= 33¶
-
JOB_DELETED
= 34¶
-
JOB_PAUSED
= 35¶
-
JOB_RESUMED
= 36¶
-
PLUGIN_LOGGER_FILE_CHANGE
= 37¶
-
QUEUE_CLEARED
= 14¶
-
REQUEST_CANCELED
= 29¶
-
REQUEST_COMPLETED
= 7¶
-
REQUEST_CREATED
= 5¶
-
REQUEST_STARTED
= 6¶
-
REQUEST_UPDATED
= 22¶
-
RUNNER_REMOVED
= 40¶
-
RUNNER_STARTED
= 38¶
-
RUNNER_STOPPED
= 39¶
-
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:
brewtils.models.BaseModel
-
schema
= 'QueueSchema'¶
-
-
class
brewtils.models.
Principal
(id=None, username=None, roles=None, permissions=None, preferences=None, metadata=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'PrincipalSchema'¶
-
-
class
brewtils.models.
Role
(id=None, name=None, description=None, permissions=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'RoleSchema'¶
-
-
class
brewtils.models.
RefreshToken
(id=None, issued=None, expires=None, payload=None)[source]¶ Bases:
brewtils.models.BaseModel
-
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, max_instances=None)[source]¶ Bases:
brewtils.models.BaseModel
-
STATUS_TYPES
= set(['PAUSED', 'RUNNING'])¶
-
TRIGGER_TYPES
= set(['cron', 'date', 'file', 'interval'])¶
-
schema
= 'JobSchema'¶
-
-
class
brewtils.models.
RequestFile
(storage_type=None, filename=None, id=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'RequestFileSchema'¶
-
-
class
brewtils.models.
File
(id=None, owner_id=None, owner_type=None, updated_at=None, file_name=None, file_size=None, chunks=None, chunk_size=None, owner=None, job=None, request=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'FileSchema'¶
-
-
class
brewtils.models.
FileChunk
(id=None, file_id=None, offset=None, data=None, owner=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'FileChunkSchema'¶
-
-
class
brewtils.models.
FileStatus
(owner_id=None, owner_type=None, updated_at=None, file_name=None, file_size=None, chunks=None, chunk_size=None, chunk_id=None, file_id=None, offset=None, data=None, valid=None, missing_chunks=None, expected_max_size=None, size_ok=None, expected_number_of_chunks=None, number_of_chunks=None, chunks_ok=None, operation_complete=None, message=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'FileStatusSchema'¶
-
-
class
brewtils.models.
RequestTemplate
(system=None, system_version=None, instance_name=None, namespace=None, command=None, command_type=None, parameters=None, comment=None, metadata=None, output_type=None)[source]¶ Bases:
brewtils.models.BaseModel
-
TEMPLATE_FIELDS
= ['system', 'system_version', 'instance_name', 'namespace', 'command', 'command_type', 'parameters', 'comment', 'metadata', 'output_type']¶
-
schema
= 'RequestTemplateSchema'¶
-
-
class
brewtils.models.
DateTrigger
(run_date=None, timezone=None)[source]¶ Bases:
brewtils.models.BaseModel
-
scheduler_attributes
¶
-
scheduler_kwargs
¶
-
schema
= 'DateTriggerSchema'¶
-
-
class
brewtils.models.
CronTrigger
(year=None, month=None, day=None, week=None, day_of_week=None, hour=None, minute=None, second=None, start_date=None, end_date=None, timezone=None, jitter=None)[source]¶ Bases:
brewtils.models.BaseModel
-
scheduler_attributes
¶
-
scheduler_kwargs
¶
-
schema
= 'CronTriggerSchema'¶
-
-
class
brewtils.models.
IntervalTrigger
(weeks=None, days=None, hours=None, minutes=None, seconds=None, start_date=None, end_date=None, timezone=None, jitter=None, reschedule_on_finish=None)[source]¶ Bases:
brewtils.models.BaseModel
-
scheduler_attributes
¶
-
scheduler_kwargs
¶
-
schema
= 'IntervalTriggerSchema'¶
-
-
class
brewtils.models.
FileTrigger
(pattern=None, path=None, recursive=None, callbacks=None)[source]¶ Bases:
brewtils.models.BaseModel
-
scheduler_attributes
¶
-
scheduler_kwargs
¶
-
schema
= 'FileTriggerSchema'¶
-
-
class
brewtils.models.
Garden
(id=None, name=None, status=None, status_info=None, namespaces=None, systems=None, connection_type=None, connection_params=None)[source]¶ Bases:
brewtils.models.BaseModel
-
GARDEN_STATUSES
= set(['BLOCKED', 'ERROR', 'INITIALIZING', 'NOT_CONFIGURED', 'RUNNING', 'STOPPED', 'UNKNOWN', 'UNREACHABLE'])¶
-
schema
= 'GardenSchema'¶
-
-
class
brewtils.models.
Operation
(model=None, model_type=None, args=None, kwargs=None, target_garden_name=None, source_garden_name=None, operation_type=None)[source]¶ Bases:
brewtils.models.BaseModel
-
schema
= 'OperationSchema'¶
-
brewtils.plugin module¶
-
class
brewtils.plugin.
Plugin
(client=None, system=None, logger=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 a
Client
is by annotating a class with the@system
decorator.A Plugin needs certain pieces of information in order to function correctly. These can be grouped into two high-level categories: identifying information and connection information.
Identifying information is how Beer-garden differentiates this Plugin from all other Plugins. If you already have fully-defined System model you can pass that directly to the Plugin (
system=my_system
). However, normally it’s simpler to pass the pieces directly:name
(required)version
(required)instance_name
(required, but defaults to “default”)namespace
description
icon_name
metadata
display_name
Connection information tells the Plugin how to communicate with Beer-garden. The most important of these is the
bg_host
(to tell the plugin where to find the Beer-garden you want to connect to):bg_host
bg_port
bg_url_prefix
ssl_enabled
ca_cert
ca_verify
client_cert
An example plugin might look like this:
Plugin( name="Test", version="1.0.0", instance_name="default", namespace="test plugins", description="A Test", bg_host="localhost", )
Plugins use Yapconf for configuration loading, which means that values can be discovered from sources other than direct argument passing. Config can be passed as command line arguments:
python my_plugin.py --bg-host localhost
Values can also be specified as environment variables with a “BG_” prefix:
BG_HOST=localhost python my_plugin.py
Plugins service requests using a
concurrent.futures.ThreadPoolExecutor
. The maximum number of threads available is controlled by themax_concurrent
argument.Warning
Normally the processing of each Request occurs in a distinct thread context. If you need to access shared state please be careful to use appropriate concurrency mechanisms.
Warning
The default value for
max_concurrent
is 5, but setting it to 1 is allowed. This means that a Plugin will essentially be single-threaded, but realize this means that if the Plugin invokes a Command on itself in the course of processing a Request then the Plugin will deadlock!Parameters: - client – Instance of a class annotated with
@system
. - bg_host (str) – Beer-garden hostname
- bg_port (int) – Beer-garden port
- bg_url_prefix (str) – URL path that will be used as a prefix when communicating with Beer-garden. Useful if Beer-garden is running on a URL other than ‘/’.
- ssl_enabled (bool) – Whether to use SSL for Beer-garden communication
- ca_cert (str) – Path to certificate file containing the certificate of the authority that issued the Beer-garden server certificate
- ca_verify (bool) – Whether to verify Beer-garden server certificate
- client_cert (str) – Path to client certificate to use when communicating with Beer-garden
- api_version (int) – Beer-garden API version to use
- client_timeout (int) – Max time to wait for Beer-garden server response
- username (str) – Username for Beer-garden authentication
- password (str) – Password for Beer-garden authentication
- access_token (str) – Access token for Beer-garden authentication
- refresh_token (str) – Refresh token for Beer-garden authentication
- system (
brewtils.models.System
) – A Beer-garden System definition. Incompatible with name, version, description, display_name, icon_name, max_instances, and metadata parameters. - name (str) – System name
- version (str) – System version
- description (str) – System description
- display_name (str) – System display name
- icon_name (str) – System icon name
- max_instances (int) – System maximum instances
- metadata (dict) – System metadata
- instance_name (str) – Instance name
- namespace (str) – Namespace name
- logger (
logging.Logger
) – Logger that will be used by the Plugin. Passing a logger will prevent the Plugin from preforming any additional logging configuration. - worker_shutdown_timeout (int) – Time to wait during shutdown to finish processing
- max_concurrent (int) – Maximum number of requests to process concurrently
- max_attempts (int) – Number of times to attempt updating of a Request before giving up. Negative numbers are interpreted as no maximum.
- max_timeout (int) – Maximum amount of time to wait between Request update attempts. Negative numbers are interpreted as no maximum.
- starting_timeout (int) – Initial time to wait between Request update attempts. Will double on subsequent attempts until reaching max_timeout.
- mq_max_attempts (int) – Number of times to attempt reconnection to message queue before giving up. Negative numbers are interpreted as no maximum.
- mq_max_timeout (int) – Maximum amount of time to wait between message queue reconnect attempts. Negative numbers are interpreted as no maximum.
- mq_starting_timeout (int) – Initial time to wait between message queue reconnect attempts. Will double on subsequent attempts until reaching mq_max_timeout.
- working_directory (str) – Path to a preferred working directory. Only used when working with bytes parameters.
-
bg_host
¶
-
bg_port
¶
-
bg_url_prefix
¶
-
bm_client
¶
-
ca_cert
¶
-
ca_verify
¶
-
client
¶
-
client_cert
¶
-
connection_parameters
¶
-
instance
¶
-
instance_name
¶
-
logger
¶
-
max_attempts
¶
-
max_concurrent
¶
-
max_timeout
¶
-
metadata
¶
-
shutdown_event
¶
-
ssl_enabled
¶
-
starting_timeout
¶
-
system
¶
-
unique_name
¶
-
class
brewtils.plugin.
PluginBase
(*args, **kwargs)[source]¶ Bases:
brewtils.plugin.Plugin
-
class
brewtils.plugin.
RemotePlugin
(*args, **kwargs)[source]¶ Bases:
brewtils.plugin.Plugin
brewtils.queues module¶
This module currently exists to maintain backwards compatibility.
-
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_handling module¶
-
class
brewtils.request_handling.
AdminProcessor
(target, updater, consumer, validation_funcs=None, logger=None, plugin_name=None, max_workers=None, resolvers=None, working_directory=None)[source]¶ Bases:
brewtils.request_handling.RequestProcessor
RequestProcessor with slightly modified process method
-
process_message
(target, request, headers)[source]¶ Process a message. Intended to be run on an Executor.
Will invoke the command and set the final status / output / error_class.
Will NOT set the status to IN_PROGRESS or set the request context.
Parameters: - target – The object to invoke received commands on
- request – The parsed Request
- headers – Dictionary of headers from the PikaConsumer
Returns: None
-
-
class
brewtils.request_handling.
HTTPRequestUpdater
(ez_client, shutdown_event, **kwargs)[source]¶ Bases:
brewtils.request_handling.RequestUpdater
RequestUpdater implementation based around an EasyClient.
Parameters: - ez_client – EasyClient to use for communication
- shutdown_event – threading.Event to allow for timely shutdowns
- logger – A logger
Keyword Arguments: - logger – A logger
- max_attempts – Max number of unsuccessful updates before discarding the message
- max_timeout – Maximum amount of time (seconds) to wait between update attempts
- starting_timeout – Starting time to wait (seconds) between update attempts
-
update_request
(request, headers)[source]¶ Sends a Request update to beer-garden
Ephemeral requests do not get updated, so we simply skip them.
- If brew-view appears to be down, it will wait for brew-view to come back
- up before updating.
If this is the final attempt to update, we will attempt a known, good request to give some information to the user. If this attempt fails then we simply discard the message.
Parameters: - request – The request to update
- headers – A dictionary of headers from the PikaConsumer
Returns: None
Raises: RepublishMessageException
– The Request update failed (any reason)
-
class
brewtils.request_handling.
NoopUpdater
(*args, **kwargs)[source]¶ Bases:
brewtils.request_handling.RequestUpdater
RequestUpdater implementation that explicitly does not update.
-
class
brewtils.request_handling.
RequestConsumer
(*args, **kwargs)[source]¶ Bases:
threading.Thread
Base class for consumers
Classes deriving from this are expected to provide a concrete implementation for a specific queue type.
After the consumer is created it will be passed to a
RequestProcessor
. The processor will then set theon_message_callback
property of the consumer to the correct method.This means when the consumer receives a message it should invoke its own
_on_message_callback
method with the message body and headers as parameters:self._on_message_callback(body, properties.headers)
-
static
create
(connection_type=None, **kwargs)[source]¶ Factory method for consumer creation
Currently the only supported connection_type is “rabbitmq”, which will return an instance of
brewtils.pika.PikaConsumer
.Parameters: - connection_type (str) – String describing connection type
- kwargs – Keyword arguments to be passed to the Consumer initializer
Returns: Concrete instance of RequestConsumer
Raises: ValueError
– The specified connection_type does not map to a consumer class
-
on_message_callback
¶
-
static
-
class
brewtils.request_handling.
RequestProcessor
(target, updater, consumer, validation_funcs=None, logger=None, plugin_name=None, max_workers=None, resolvers=None, working_directory=None)[source]¶ Bases:
object
Class responsible for coordinating Request processing
The RequestProcessor is responsible for the following: - Defining on_message_received callback that will be invoked by the PikaConsumer - Parsing the request - Invoking the command on the target - Formatting the output - Reporting request updates to Beergarden (using a RequestUpdater)
Parameters: - target – Incoming requests will be invoked on this object
- updater – RequestUpdater that will be used for updating requests
- validation_funcs – List of functions that will called before invoking a command
- logger – A logger
- plugin_name – The Plugin’s unique name
- max_workers – Max number of threads to use in the executor pool
-
on_message_received
(message, headers)[source]¶ Callback function that will be invoked for received messages
This will attempt to parse the message and then run the parsed Request through all validation functions that this RequestProcessor knows about.
If the request parses cleanly and passes validation it will be submitted to this RequestProcessor’s ThreadPoolExecutor for processing.
Parameters: - message – The message string
- headers – The header dictionary
Returns: A future that will complete when processing finishes
Raises: DiscardMessageException
– The request failed to parse correctlyRequestProcessException
– Validation failures should raise a subclass of this
-
process_message
(target, request, headers)[source]¶ Process a message. Intended to be run on an Executor.
Will set the status to IN_PROGRESS, invoke the command, and set the final status / output / error_class.
Parameters: - target – The object to invoke received commands on
- request – The parsed Request
- headers – Dictionary of headers from the PikaConsumer
Returns: None
brewtils.schema_parser module¶
-
class
brewtils.schema_parser.
SchemaParser
[source]¶ Bases:
object
Serialize and deserialize Brewtils models
-
logger
= <logging.Logger object>¶
-
classmethod
parse
(data, model_class, from_string=False, **kwargs)[source]¶ Convert a JSON string or dictionary into a model object
Parameters: - data – The raw input
- model_class – Class object of the desired model type
- 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 model 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_file
(file, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a file model object
Parameters: - file – 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 File object
-
classmethod
parse_garden
(garden, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a garden model object
Parameters: - garden – 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 Garden 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
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_operation
(operation, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a garden model object
Parameters: - operation – 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 Operation 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_request_file
(request_file, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a request file model object
Parameters: - request_file – 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 RequestFile 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_runner
(runner, from_string=False, **kwargs)[source]¶ Convert raw JSON string or dictionary to a runner model object
Parameters: - runner – 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 Runner 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
(model, to_string=False, schema_name=None, **kwargs)[source]¶ Convert a model object or list of models into a dictionary or JSON string.
This is potentially recursive - here’s how this should work:
- Determine the correct schema to use for serializing. This can be explicitly
passed as an argument, or it can be determined by inspecting the model to serialize. - Determine if the model to serialize is a collection or a single object.
- If it’s a single object, serialize it and return that.
- If it’s a collection, construct a list by calling this method for each
individual item in the collection. Then serialize that and return it.
Parameters: - model – The model or model list
- to_string – True to generate a JSON string, False to generate a dictionary
- schema_name – Name of schema to use for serializing. If None, will be
- by inspecting model (determined) –
- **kwargs – Additional parameters to be passed to the Schema. Note that the ‘many’ parameter will be set correctly automatically.
Returns: A serialized model representation
-
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_garden
(garden, to_string=True, **kwargs)[source]¶ Convert an garden model into serialized form
Parameters: - garden – 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 garden
-
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_operation
(operation, to_string=True, **kwargs)[source]¶ Convert an operation model into serialized form
Parameters: - operation – 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 operation
-
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_request_file
(request_file, to_string=True, **kwargs)[source]¶ Convert a request file model into serialized form
Parameters: - request_file – The request file 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 file
-
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_runner
(runner, to_string=True, **kwargs)[source]¶ Convert a runner model into serialized form
Parameters: - operation – 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 runner
-
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.
RequestFileSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
FileSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
FileChunkSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
FileStatusSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
PatchSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
unwrap_envelope
(data, many)[source]¶ Helper function for parsing the different patch formats.
This exists because previously multiple patches serialized like:
{ "operations": [ {"operation": "replace", ...}, {"operation": "replace", ...} ... ] }
But we also wanted to be able to handle a simple list:
[ {"operation": "replace", ...}, {"operation": "replace", ...} ... ]
Patches are now (as of v3) serialized as the latter. Prior to v3 they were serialized as the former.
-
-
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>¶
-
-
class
brewtils.schemas.
IntervalTriggerSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
CronTriggerSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
-
class
brewtils.schemas.
FileTriggerSchema
(strict=True, **kwargs)[source]¶ Bases:
brewtils.schemas.BaseSchema
-
opts
= <marshmallow.schema.SchemaOpts object>¶
-
brewtils.specification module¶
brewtils.stoppable_thread module¶
Module contents¶
-
brewtils.
client
(_wrapped=None, bg_name=None, bg_version=None)[source]¶ Class decorator that marks a class as a beer-garden Client
Using this decorator is no longer strictly necessary. It was previously required in order to mark a class as being a Beer-garden Client, and contained most of the logic that currently resides in the
parse_client
function. However, that’s no longer the case and this currently exists mainly for back-compatibility reasons.Applying this decorator to a client class does have the nice effect of preventing linters from complaining if any special attributes are used. So that’s something.
Those special attributes are below. Note that these are just placeholders until the actual values are populated when the client instance is assigned to a Plugin:
_bg_name
: an optional system name_bg_version
: an optional system version_bg_commands
: holds all registered commands_current_request
: Reference to the currently executing request
Parameters: - _wrapped – The class to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- bg_name – Optional plugin name
- bg_version – Optional plugin version
Returns: The decorated class
-
brewtils.
command
(_wrapped=None, description=None, parameters=None, command_type='ACTION', output_type='STRING', schema=None, form=None, template=None, icon_name=None, hidden=False)[source]¶ Decorator for specifying Command details
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.
- description – The command description. If not given the first line of the method docstring will be used.
- parameters – A list of Command parameters. It’s recommended to use @parameter decorators to declare Parameters instead of declaring them here, but it is allowed. Any Parameters given here will be merged with Parameters sourced from decorators and inferred from the method signature.
- 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.
- hidden – Flag controlling whether the command is visible on the user interface.
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, parameters=None, nullable=None, maximum=None, minimum=None, regex=None, form_input_type=None, type_info=None, is_kwarg=None, model=None)[source]¶ Decorator for specifying Parameter details
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. If the decorated object is a method the key must match an argument name.
- 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.
- parameters – Any nested parameters. See also: the ‘model’ argument.
- 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.
- form_input_type – Specify the form input field type (e.g. textarea). Only used for string fields.
- type_info – Type-specific information. Mostly reserved for future use.
- is_kwarg – Boolean indicating if this parameter is meant to be part of the decorated function’s kwargs. Only applies when the decorated object is a method.
- model – Class to be used as a model for this parameter. Must be a Python type object, not an instance.
Returns: The decorated function
-
brewtils.
system
(_wrapped=None, bg_name=None, bg_version=None)¶ Class decorator that marks a class as a beer-garden Client
Using this decorator is no longer strictly necessary. It was previously required in order to mark a class as being a Beer-garden Client, and contained most of the logic that currently resides in the
parse_client
function. However, that’s no longer the case and this currently exists mainly for back-compatibility reasons.Applying this decorator to a client class does have the nice effect of preventing linters from complaining if any special attributes are used. So that’s something.
Those special attributes are below. Note that these are just placeholders until the actual values are populated when the client instance is assigned to a Plugin:
_bg_name
: an optional system name_bg_version
: an optional system version_bg_commands
: holds all registered commands_current_request
: Reference to the currently executing request
Parameters: - _wrapped – The class to decorate. This is handled as a positional argument and shouldn’t be explicitly set.
- bg_name – Optional plugin name
- bg_version – Optional plugin version
Returns: The decorated class
-
class
brewtils.
Plugin
(client=None, system=None, logger=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 a
Client
is by annotating a class with the@system
decorator.A Plugin needs certain pieces of information in order to function correctly. These can be grouped into two high-level categories: identifying information and connection information.
Identifying information is how Beer-garden differentiates this Plugin from all other Plugins. If you already have fully-defined System model you can pass that directly to the Plugin (
system=my_system
). However, normally it’s simpler to pass the pieces directly:name
(required)version
(required)instance_name
(required, but defaults to “default”)namespace
description
icon_name
metadata
display_name
Connection information tells the Plugin how to communicate with Beer-garden. The most important of these is the
bg_host
(to tell the plugin where to find the Beer-garden you want to connect to):bg_host
bg_port
bg_url_prefix
ssl_enabled
ca_cert
ca_verify
client_cert
An example plugin might look like this:
Plugin( name="Test", version="1.0.0", instance_name="default", namespace="test plugins", description="A Test", bg_host="localhost", )
Plugins use Yapconf for configuration loading, which means that values can be discovered from sources other than direct argument passing. Config can be passed as command line arguments:
python my_plugin.py --bg-host localhost
Values can also be specified as environment variables with a “BG_” prefix:
BG_HOST=localhost python my_plugin.py
Plugins service requests using a
concurrent.futures.ThreadPoolExecutor
. The maximum number of threads available is controlled by themax_concurrent
argument.Warning
Normally the processing of each Request occurs in a distinct thread context. If you need to access shared state please be careful to use appropriate concurrency mechanisms.
Warning
The default value for
max_concurrent
is 5, but setting it to 1 is allowed. This means that a Plugin will essentially be single-threaded, but realize this means that if the Plugin invokes a Command on itself in the course of processing a Request then the Plugin will deadlock!Parameters: - client – Instance of a class annotated with
@system
. - bg_host (str) – Beer-garden hostname
- bg_port (int) – Beer-garden port
- bg_url_prefix (str) – URL path that will be used as a prefix when communicating with Beer-garden. Useful if Beer-garden is running on a URL other than ‘/’.
- ssl_enabled (bool) – Whether to use SSL for Beer-garden communication
- ca_cert (str) – Path to certificate file containing the certificate of the authority that issued the Beer-garden server certificate
- ca_verify (bool) – Whether to verify Beer-garden server certificate
- client_cert (str) – Path to client certificate to use when communicating with Beer-garden
- api_version (int) – Beer-garden API version to use
- client_timeout (int) – Max time to wait for Beer-garden server response
- username (str) – Username for Beer-garden authentication
- password (str) – Password for Beer-garden authentication
- access_token (str) – Access token for Beer-garden authentication
- refresh_token (str) – Refresh token for Beer-garden authentication
- system (
brewtils.models.System
) – A Beer-garden System definition. Incompatible with name, version, description, display_name, icon_name, max_instances, and metadata parameters. - name (str) – System name
- version (str) – System version
- description (str) – System description
- display_name (str) – System display name
- icon_name (str) – System icon name
- max_instances (int) – System maximum instances
- metadata (dict) – System metadata
- instance_name (str) – Instance name
- namespace (str) – Namespace name
- logger (
logging.Logger
) – Logger that will be used by the Plugin. Passing a logger will prevent the Plugin from preforming any additional logging configuration. - worker_shutdown_timeout (int) – Time to wait during shutdown to finish processing
- max_concurrent (int) – Maximum number of requests to process concurrently
- max_attempts (int) – Number of times to attempt updating of a Request before giving up. Negative numbers are interpreted as no maximum.
- max_timeout (int) – Maximum amount of time to wait between Request update attempts. Negative numbers are interpreted as no maximum.
- starting_timeout (int) – Initial time to wait between Request update attempts. Will double on subsequent attempts until reaching max_timeout.
- mq_max_attempts (int) – Number of times to attempt reconnection to message queue before giving up. Negative numbers are interpreted as no maximum.
- mq_max_timeout (int) – Maximum amount of time to wait between message queue reconnect attempts. Negative numbers are interpreted as no maximum.
- mq_starting_timeout (int) – Initial time to wait between message queue reconnect attempts. Will double on subsequent attempts until reaching mq_max_timeout.
- working_directory (str) – Path to a preferred working directory. Only used when working with bytes parameters.
-
bg_host
¶
-
bg_port
¶
-
bg_url_prefix
¶
-
bm_client
¶
-
ca_cert
¶
-
ca_verify
¶
-
client
¶
-
client_cert
¶
-
connection_parameters
¶
-
instance
¶
-
instance_name
¶
-
logger
¶
-
max_attempts
¶
-
max_concurrent
¶
-
max_timeout
¶
-
metadata
¶
-
shutdown_event
¶
-
ssl_enabled
¶
-
starting_timeout
¶
-
system
¶
-
unique_name
¶
-
class
brewtils.
EasyClient
(*args, **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.
Parameters: - bg_host (str) – Beer-garden hostname
- bg_port (int) – Beer-garden port
- bg_url_prefix (str) – URL path that will be used as a prefix when communicating with Beer-garden. Useful if Beer-garden is running on a URL other than ‘/’.
- ssl_enabled (bool) – Whether to use SSL for Beer-garden communication
- ca_cert (str) – Path to certificate file containing the certificate of the authority that issued the Beer-garden server certificate
- ca_verify (bool) – Whether to verify Beer-garden server certificate
- client_cert (str) – Path to client certificate to use when communicating with Beer-garden
- api_version (int) – Beer-garden API version to use
- client_timeout (int) – Max time to wait for Beer-garden server response
- username (str) – Username for Beer-garden authentication
- password (str) – Password for Beer-garden authentication
- access_token (str) – Access token for Beer-garden authentication
- refresh_token (str) – Refresh token for Beer-garden authentication
-
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
-
delete_file
(file_id)[source]¶ Delete a given file on the Beer Garden server.
Parameters: file_id – The beer garden-assigned file id. Returns: The API response
-
download_file
(file_id)[source]¶ Download a file from the Beer Garden server.
Parameters: file_id – The beer garden-assigned file id. Returns: A file object
-
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
-
forward
(operation)[source]¶ Forwards an Operation
Parameters: operation – The Operation to be forwarded Returns: The API response
-
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’s status
Parameters: instance_id – The Id Returns: The Instance’s status
-
get_logging_config
(system_name=None, local=False)[source]¶ Get a logging configuration
Note that the system_name is not relevant and is only provided for backward-compatibility.
Parameters: system_name (str) – UNUSED Returns: The configuration object Return type: dict
-
get_queues
()[source]¶ Retrieve all queue information
Returns: List of all Queues Return type: List[Queue]
-
get_system
(system_id, **kwargs)[source]¶ Get a System
Parameters: system_id – The Id Returns: The System
-
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, runner_id=None)[source]¶ Start an Instance
Parameters: - instance_id (str) – The Instance ID
- runner_id (str) – The PluginRunner ID, if any
Returns: The updated Instance
Return type:
-
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
-
rescan
()[source]¶ Rescan local plugin directory
Returns: True if rescan was successful Return type: bool
-
resume_job
(job_id)[source]¶ Resume a Job
Parameters: job_id (str) – The Job ID Returns: The updated Job Return type: Job
-
update_instance
(instance_id, **kwargs)[source]¶ Update an Instance status
Parameters: instance_id (str) – The Instance ID
Keyword Arguments: - new_status (str) – The new status
- metadata (dict) – Will be added to existing instance metadata
Returns: The updated Instance
Return type:
-
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: - add_instance (Instance) – An Instance to append
- 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:
-
upload_file
(file_to_upload, desired_filename=None, file_params=None)[source]¶ Upload a given file to the Beer Garden server.
Parameters: - file_to_upload – Can either be an open file descriptor or a path.
- desired_filename – The desired filename, if none is provided it
- use the basename of the file_to_upload (will) –
- file_params – The metadata surrounding the file. Valid Keys: See brewtils File model
Returns: A BG file ID.
-
class
brewtils.
SystemClient
(*args, **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 and a system name:
client = SystemClient( system_name='example_system', system_namespace='default', bg_host="host", bg_port=2337, )
Note: Passing an empty string as the system_namespace parameter will evalutate to the local garden’s default namespace.
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 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 instance for each request.
- always_update:
- If True the SystemClient will 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 when making the first request and will only be 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 only 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( system_name='example_system', system_namespace='default', bg_host="localhost", bg_port=2337, 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 newer 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 every time the target system is updated.
It’s also possible to control what happens when a Request results in an ERROR. If the
raise_on_error
parameter is set to False (the default) then Requests that are not successful simply result in a Request with a status of ERROR, and it is the plugin developer’s responsibility to check for this case. However, ifraise_on_error
is set to True then this will result in aRequestFailedError
being raised. This will happen regardless of the value of theblocking
flag.- 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.
Request that raises:
client = SystemClient( system_name="foo", system_namespace='default', bg_host="localhost", bg_port=2337, ) try: client.command_that_errors(_raise_on_error=True) except RequestFailedError: print("I could have just ignored this")
Parameters: - system_name (str) – Name of the System to make Requests on
- system_namespace (str) – Namespace of the System to make Requests on
- version_constraint (str) – System version to make Requests on. Can be specific (‘1.0.0’) or ‘latest’.
- default_instance (str) – Name of the Instance to make Requests on
- always_update (bool) – Whether to check if a newer version of the System exists
before making each Request. Only relevant if
version_constraint='latest'
- timeout (int) – Seconds to wait for a request to complete. ‘None’ means wait forever.
- max_delay (int) – Maximum number of seconds to wait between status checks for a created request
- blocking (bool) – Flag indicating whether creation will block until the Request is complete or return a Future that will complete when the Request does
- max_concurrent (int) – Maximum number of concurrent requests allowed. Only has an effect when blocking=False.
- raise_on_error (bool) – Flag controlling whether created Requests that complete with an ERROR state should raise an exception
- bg_host (str) – Beer-garden hostname
- bg_port (int) – Beer-garden port
- bg_url_prefix (str) – URL path that will be used as a prefix when communicating with Beer-garden. Useful if Beer-garden is running on a URL other than ‘/’.
- ssl_enabled (bool) – Whether to use SSL for Beer-garden communication
- ca_cert (str) – Path to certificate file containing the certificate of the authority that issued the Beer-garden server certificate
- ca_verify (bool) – Whether to verify Beer-garden server certificate
- client_cert (str) – Path to client certificate to use when communicating with Beer-garden
- api_version (int) – Beer-garden API version to use
- client_timeout (int) – Max time to wait for Beer-garden server response
- username (str) – Username for Beer-garden authentication
- password (str) – Password for Beer-garden authentication
- access_token (str) – Access token for Beer-garden authentication
- refresh_token (str) – Refresh token for Beer-garden authentication
-
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) # Create two callables - one with a parameter and one without uncreated_requests = [ client.create_bg_request('command_1', arg_1='Hi!'), client.create_bg_request('command_2'), ] # Calling creates and sends the request # The result of each is a future because blocking=False on the SystemClient futures = [req() for req in uncreated_requests] # Wait for all the futures to complete concurrent.futures.wait(futures)
Parameters: - command_name (str) – Name of the Command to send
- kwargs (dict) – Will be passed as parameters when creating the Request
Returns: Partial that will create and execute a Beer-garden request when called
Raises: AttributeError
– System does not have a Command with the given command_name
-
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.
Returns: None Raises: FetchError
– Unable to find a matching System
-
send_bg_request
(*args, **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 outcreate_bg_request
.Parameters: - args (list) – Unused. Passing positional parameters indicates a bug
- kwargs (dict) – All necessary request parameters, including Beer-garden internal parameters
Returns: A completed Request object blocking=False: A future that will be completed when the Request does
Return type: blocking=True
Raises: ValidationError
– Request creation failed validation on the server
-
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=True, environment=True, argument_parser=None, bootstrap=False, **kwargs)[source]¶ Load configuration using Yapconf
Configuration will be loaded from these sources, with earlier sources having higher priority:
**kwargs
passed to this method- Command line arguments (if
cli_args
argument is not False) - Environment variables using the
BG_
prefix (ifenvironment
argument - is not False)
- Environment variables using the
- Default values in the brewtils specification
Parameters: - cli_args (Union[bool, list], optional) – Specifies whether command line should be used as a configuration source - True: Argparse will use the standard sys.argv[1:] - False: Command line arguments will be ignored when loading configuration - List of strings: Will be parsed as CLI args (instead of using sys.argv)
- environment (bool) – Specifies whether environment variables (with the
BG_
prefix) should be used when loading configuration - argument_parser (ArgumentParser, optional, deprecated) – 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.
configure_logging
(raw_config, namespace=None, system_name=None, system_version=None, instance_name=None)[source]¶ Load and enable a logging configuration from Beergarden
WARNING: This method will modify the current logging configuration.
The configuration will be template substituted using the keyword arguments passed to this function. For example, a handler like this:
handlers: file: backupCount: 5 class: "logging.handlers.RotatingFileHandler" encoding: utf8 formatter: default level: INFO maxBytes: 10485760 filename: "$system_name.log"
Will result in logging to a file with the same name as the given system_name.
This will also ensure that directories exist for any file-based handlers. Default behavior for the Python logging module is to not create directories that do not already exist, which would dramatically lower the utility of templating.
Parameters: - raw_config – Configuration to apply
- namespace – Used for configuration templating
- system_name – Used for configuration templating
- system_version – Used for configuration templating
- instance_name – Used for configuration templating
Returns: None
-
brewtils.
normalize_url_prefix
(url_prefix)[source]¶ Enforce a consistent URL representation
The normalized prefix will begin and end with ‘/’. If there is no prefix the normalized form will be ‘/’.
Examples
INPUT NORMALIZED None ‘/’ ‘’ ‘/’ ‘/’ ‘/’ ‘example’ ‘/example/’ ‘/example’ ‘/example/’ ‘example/’ ‘/example/’ ‘/example/’ ‘/example/’
Parameters: url_prefix (str) – The prefix Returns: The normalized prefix Return type: str