brewtils.rest package¶
Submodules¶
brewtils.rest.client module¶
-
class
brewtils.rest.client.
RestClient
(bg_host=None, bg_port=None, ssl_enabled=False, api_version=None, logger=None, ca_cert=None, client_cert=None, url_prefix=None, ca_verify=True, **kwargs)[source]¶ Bases:
object
Simple Rest Client for communicating to with beer-garden.
The is the low-level client responsible for making the actual REST calls. Other clients (e.g.
brewtils.rest.easy_client.EasyClient
) build on this by providing useful abstractions.Parameters: - bg_host – beer-garden REST API hostname.
- bg_port – beer-garden REST API port.
- ssl_enabled – Flag indicating whether to use HTTPS when communicating with beer-garden.
- api_version – The beer-garden REST API version. Will default to the latest version.
- logger – The logger to use. If None one will be created.
- ca_cert – beer-garden REST API server CA certificate.
- client_cert – The client certificate to use when making requests.
- url_prefix – beer-garden REST API Url Prefix.
- ca_verify – Flag indicating whether to verify server certificate when making a request.
- username – Username for Beergarden authentication
- password – Password for Beergarden authentication
- access_token – Access token for Beergarden authentication
- refresh_token – Refresh token for Beergarden authentication
- client_timeout – Max time to will wait for server response
-
JSON_HEADERS
= {'Accept': 'text/plain', 'Content-type': 'application/json'}¶
-
LATEST_VERSION
= 1¶
-
delete_instance
(*args, **kwargs)[source]¶ Performs a DELETE on an Instance URL
Parameters: instance_id – The ID of the instance to remove Returns: Response to the request
-
delete_job
(*args, **kwargs)[source]¶ Performs a DELETE on a Job URL
Parameters: job_id – The ID of the job to remove Returns: Response to the request
-
delete_queue
(*args, **kwargs)[source]¶ Performs a DELETE on a specific Queue URL
Returns: Response to the request
-
delete_queues
(*args, **kwargs)[source]¶ Performs a DELETE on the Queues URL
Returns: Response to the request
-
delete_system
(*args, **kwargs)[source]¶ Performs a DELETE on a System URL
Parameters: system_id – The ID of the system to remove Returns: Response to the request
-
get_command
(*args, **kwargs)[source]¶ Performs a GET on the Command URL
Parameters: command_id – ID of command Returns: Response to the request
-
get_config
(*args, **kwargs)[source]¶ Perform a GET to the config URL
Parameters: kwargs – Passed to underlying Requests method Returns: The request response
-
get_instance
(*args, **kwargs)[source]¶ Performs a GET on the Instance URL
Parameters: instance_id – ID of instance Returns: Response to the request
-
get_job
(*args, **kwargs)[source]¶ Performs a GET on the Job URL
Parameters: job_id – ID of job Returns: Response to the request
-
get_logging_config
(*args, **kwargs)[source]¶ Perform a GET to the logging config URL
Parameters: kwargs – Parameters to be used in the GET request Returns: The request response
-
get_queues
(*args, **kwargs)[source]¶ Performs a GET on the Queues URL
Returns: Response to the request
-
get_request
(*args, **kwargs)[source]¶ Performs a GET on the Request URL
Parameters: request_id – ID of request Returns: Response to the request
-
get_requests
(*args, **kwargs)[source]¶ Performs a GET on the Requests URL
Parameters: kwargs – Parameters to be used in the GET request Returns: Response to the request
-
get_system
(*args, **kwargs)[source]¶ Performs a GET on the System URL
Parameters: - system_id – ID of system
- kwargs – Parameters to be used in the GET request
Returns: Response to the request
-
get_systems
(*args, **kwargs)[source]¶ Perform a GET on the System collection URL
Parameters: kwargs – Parameters to be used in the GET request Returns: The request response
-
get_tokens
(username=None, password=None)[source]¶ Use a username and password to get access and refresh tokens
Parameters: - username – Beergarden username
- password – Beergarden password
Returns: Response object
-
get_user
(*args, **kwargs)[source]¶ Performs a GET on the specific User URL
Returns: Response to the request Parameters: user_identifier – ID or username of User
-
get_version
(*args, **kwargs)[source]¶ Perform a GET to the version URL
Parameters: kwargs – Parameters to be used in the GET request Returns: The request response
-
patch_instance
(*args, **kwargs)[source]¶ Performs a PATCH on the instance URL
Parameters: - instance_id – ID of instance
- payload – The update specification
Returns: Response
-
patch_job
(*args, **kwargs)[source]¶ Performs a PATCH on the Job URL
Parameters: - job_id – ID of request
- payload – New job definition
Returns: Response to the request
-
patch_request
(*args, **kwargs)[source]¶ Performs a PATCH on the Request URL
Parameters: - request_id – ID of request
- payload – New request definition
Returns: Response to the request
-
patch_system
(*args, **kwargs)[source]¶ Performs a PATCH on a System URL
Parameters: - system_id – ID of system
- payload – The update specification
Returns: Response
-
post_event
(*args, **kwargs)[source]¶ Performs a POST on the event URL
Parameters: - payload – New event definition
- publishers – Array of publishers to use
Returns: Response to the request
-
post_jobs
(*args, **kwargs)[source]¶ Performs a POST on the Job URL
Parameters: payload – New job definition Returns: Response to the request
-
post_requests
(*args, **kwargs)[source]¶ Performs a POST on the Request URL
Parameters: - payload – New request definition
- kwargs – Extra request parameters
Keyword Arguments: - blocking – Wait for request to complete
- timeout – Maximum seconds to wait
Returns: Response to the request
-
class
brewtils.rest.client.
TimeoutAdapter
(**kwargs)[source]¶ Bases:
requests.adapters.HTTPAdapter
Transport adapter with a default request timeout
-
send
(*args, **kwargs)[source]¶ Sends PreparedRequest object. Returns Response object.
Parameters: - request – The
PreparedRequest
being sent. - stream – (optional) Whether to stream the request content.
- timeout (float or tuple or urllib3 Timeout object) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
- verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use
- cert – (optional) Any user-provided SSL certificate to be trusted.
- proxies – (optional) The proxies dictionary to apply to the request.
Return type: requests.Response
- request – The
-
brewtils.rest.easy_client module¶
-
class
brewtils.rest.easy_client.
EasyClient
(bg_host=None, bg_port=None, ssl_enabled=False, api_version=None, ca_cert=None, client_cert=None, parser=None, logger=None, url_prefix=None, ca_verify=True, **kwargs)[source]¶ Bases:
object
Client for simplified communication with Beergarden
This class is intended to be a middle ground between the RestClient and SystemClient. It provides a ‘cleaner’ interface to some common Beergarden operations than is exposed by the lower-level RestClient. On the other hand, the SystemClient is much better for generating Beergarden Requests.
Keyword Arguments: - bg_host (str) – Beergarden hostname
- bg_port (int) – Beergarden port
- ssl_enabled (Optional[bool]) – Whether to use SSL (HTTP vs HTTPS)
- api_version (Optional[int]) – The REST API version
- ca_cert (Optional[str]) – Path to CA certificate file
- client_cert (Optional[str]) – Path to client certificate file
- parser (Optional[SchemaParser]) – Parser to use
- logger (Optional[Logger]) – Logger to use
- url_prefix (Optional[str]) – Beergarden REST API prefix
- ca_verify (Optional[bool]) – Whether to verify the server cert hostname
- username (Optional[str]) – Username for authentication
- password (Optional[str]) – Password for authentication
- access_token (Optional[str]) – Access token for authentication
- refresh_token (Optional[str]) – Refresh token for authentication
- client_timeout (Optional[float]) – Max time to wait for a server response
-
can_connect
(**kwargs)[source]¶ Determine if the Beergarden server is responding.
- Kwargs:
- Arguments passed to the underlying Requests method
Returns: A bool indicating if the connection attempt was successful. Will return False only if a ConnectionError is raised during the attempt. Any other exception will be re-raised. Raises: requests.exceptions.RequestException
– The connection attempt resulted in an exception that indicates something other than a basic connection error. For example, an error with certificate verification.
-
clear_all_queues
()[source]¶ Cancel and remove all Requests in all queues
Returns: True if the clear was successful Return type: bool
-
clear_queue
(queue_name)[source]¶ Cancel and remove all Requests from a message queue
Parameters: queue_name (str) – The name of the queue to clear Returns: True if the clear was successful Return type: bool
-
create_job
(job)[source]¶ Create a new Job
Parameters: job (Job) – New Job definition Returns: The newly-created Job Return type: Job
-
create_request
(request, **kwargs)[source]¶ Create a new Request
Parameters: - request – New request definition
- kwargs – Extra request parameters
Keyword Arguments: - blocking (bool) – Wait for request to complete before returning
- timeout (int) – Maximum seconds to wait for completion
Returns: The newly-created Request
Return type:
-
create_system
(system)[source]¶ Create a new System
Parameters: system (System) – The System to create Returns: The newly-created system Return type: System
-
find_jobs
(**kwargs)[source]¶ Find Jobs using keyword arguments as search parameters
Parameters: **kwargs – Search parameters Returns: List of Jobs matching the search parameters Return type: List[Job]
-
find_requests
(**kwargs)[source]¶ Find Requests using keyword arguments as search parameters
Parameters: **kwargs – Search parameters Returns: List of Systems matching the search parameters Return type: List[Request]
-
find_systems
(**kwargs)[source]¶ Find Systems using keyword arguments as search parameters
Parameters: **kwargs – Search parameters Returns: List of Systems matching the search parameters Return type: List[System]
-
find_unique_request
(**kwargs)[source]¶ Find a unique request
Note
If ‘id’ is a given keyword argument then all other parameters will be ignored.
Parameters: **kwargs – Search parameters Returns: The Request if found, None otherwise Return type: Request, None Raises: FetchError
– More than one matching Request was found
-
find_unique_system
(**kwargs)[source]¶ Find a unique system
Note
If ‘id’ is a given keyword argument then all other parameters will be ignored.
Parameters: **kwargs – Search parameters Returns: The System if found, None otherwise Return type: System, None Raises: FetchError
– More than one matching System was found
-
get_instance
(instance_id)[source]¶ Get an Instance
Parameters: instance_id – The Id Returns: The Instance
-
get_instance_status
(instance_id)[source]¶ Get an Instance
WARNING: This method currently returns the Instance, not the Instance’s status. This behavior will be corrected in 3.0.
To prepare for this change please use get_instance() instead of this method.
Parameters: instance_id – The Id Returns: The status
-
get_logging_config
(system_name)[source]¶ Get logging configuration for a System
Parameters: system_name (str) – The name of the System Returns: The configuration object Return type: LoggingConfig
-
get_user
(user_identifier)[source]¶ Find a user
Parameters: user_identifier (str) – User ID or username Returns: The User Return type: Principal
-
get_version
(**kwargs)[source]¶ Get Bartender, Brew-view, and API version information
Parameters: **kwargs – Extra parameters Returns: Response object with version information in the body Return type: dict
-
initialize_instance
(instance_id)[source]¶ Start an Instance
Parameters: instance_id (str) – The Instance ID Returns: The updated Instance Return type: Instance
-
instance_heartbeat
(instance_id)[source]¶ Send an Instance heartbeat
Parameters: instance_id (str) – The Instance ID Returns: True if the heartbeat was successful Return type: bool
-
pause_job
(job_id)[source]¶ Pause a Job
Parameters: job_id (str) – The Job ID Returns: The updated Job Return type: Job
-
publish_event
(*args, **kwargs)[source]¶ Publish a new event
Parameters: - *args – If a positional argument is given it’s assumed to be an Event and will be used
- **kwargs – Will be used to construct a new Event to publish if no Event is given in the positional arguments
Keyword Arguments: _publishers (Optional[List[str]]) – List of publisher names. If given the Event will only be published to the specified publishers. Otherwise all publishers known to Beergarden will be used.
Returns: True if the publish was successful
Return type: bool
-
remove_instance
(instance_id)[source]¶ Remove an Instance
Parameters: instance_id (str) – The Instance ID Returns: True if the remove was successful Return type: bool
-
remove_job
(job_id)[source]¶ Remove a unique Job
Parameters: job_id (str) – The Job ID Returns: True if removal was successful Return type: bool Raises: DeleteError
– Couldn’t remove Job
-
remove_system
(**kwargs)[source]¶ Remove a unique System
Parameters: **kwargs – Search parameters Returns: True if removal was successful Return type: bool Raises: FetchError
– Couldn’t find a System matching given parameters
-
resume_job
(job_id)[source]¶ Resume a Job
Parameters: job_id (str) – The Job ID Returns: The updated Job Return type: Job
-
update_instance_status
(instance_id, new_status)[source]¶ Update an Instance status
Parameters: - instance_id (str) – The Instance ID
- new_status (str) – The new status
Returns: The updated Instance
Return type:
-
update_request
(request_id, status=None, output=None, error_class=None)[source]¶ Update a Request
Parameters: - request_id (str) – The Request ID
- status (Optional[str]) – New Request status
- output (Optional[str]) – New Request output
- error_class (Optional[str]) – New Request error class
Returns: The updated response
Return type: Response
-
update_system
(system_id, new_commands=None, **kwargs)[source]¶ Update a System
Parameters: - system_id (str) – The System ID
- new_commands (Optional[List[Command]]) – New System commands
Keyword Arguments: - metadata (dict) – New System metadata
- description (str) – New System description
- display_name (str) – New System display name
- icon_name (str) – New System icon name
Returns: The updated system
Return type:
-
brewtils.rest.easy_client.
handle_response_failure
(response, default_exc=<class 'brewtils.errors.RestError'>, raise_404=True)[source]¶ Deal with a response with non-2xx status code
Parameters: - response – The response object
- default_exc – The exception to raise if no specific exception is warranted
- raise_404 – If True a response with status code 404 will raise a NotFoundError. If False the method will return None.
Returns: None - this function will always raise
Raises: NotFoundError
– Status code 404 and raise_404 is TrueWaitExceededError
– Status code 408ConflictError
– Status code 409ValidationError
– Any other 4xx status codesRestConnectionError
– Status code 503default_exc
– Any other status code
-
brewtils.rest.easy_client.
wrap_response
(return_boolean=False, parse_method='', parse_many=False, default_exc=<class 'brewtils.errors.RestError'>, raise_404=True)[source]¶ Decorator to consolidate response parsing and error handling
Parameters: - return_boolean – If True, a successful response will also return True
- parse_method – The response’s json will be passed to this method of the SchemaParser
- parse_many – This will be passed as the ‘many’ parameter when parsing the response
- default_exc – Will be passed to handle_response_failure for failed responses
- raise_404 – Will be passed to handle_response_failure for failed responses
Returns: - True if return_boolean is True and the response status code is 2xx.
- The response object if return_boolean is False and parse_method is “”
- A parsed Brewtils model if return_boolean is False and parse_method is defined
Raises: RestError
– The response has a non-2xx status code. Note that the specific exception raised depends on the response status code and the argument passed as the default_exc parameter.
brewtils.rest.system_client module¶
-
class
brewtils.rest.system_client.
SystemClient
(bg_host=None, bg_port=None, system_name=None, version_constraint='latest', default_instance='default', always_update=False, timeout=None, max_delay=30, api_version=None, ssl_enabled=False, ca_cert=None, blocking=True, max_concurrent=None, client_cert=None, url_prefix=None, ca_verify=True, raise_on_error=False, **kwargs)[source]¶ Bases:
object
High-level client for generating requests for a beer-garden System.
- SystemClient creation:
This class is intended to be the main way to create beer-garden requests. Create an instance with beer-garden connection information (optionally including a url_prefix) and a system name:
client = SystemClient(host, port, 'example_system', ssl_enabled=True, url_prefix=None)
Pass additional keyword arguments for more granularity:
- version_constraint:
- Allows specifying a particular system version. Can be a version literal (‘1.0.0’) or the special value ‘latest.’ Using ‘latest’ will allow the the SystemClient to retry a request if it fails due to a missing system (see Creating Requests).
- default_instance:
- The instance name to use when creating a request if no other instance name is specified. Since each request must be addressed to a specific instance this is a convenience to prevent needing to specify the ‘default’ instance for each request.
- always_update:
- Always attempt to reload the system definition before making a request. This is useful to ensure Requests are always made against the latest version of the system. If not set the System definition will be loaded once (upon making the first request) and then only reloaded if a Request fails.
- Loading the System:
- The System definition is lazily loaded, so nothing happens until the first attempt to send a Request. At that point the SystemClient will query beer-garden to get a system definition that matches the system_name and version_constraint. If no matching system can be found a FetchError will be raised. If always_update was set to True this will happen before making each request, not just the first.
- Making a Request:
The standard way to create and send requests is by calling object attributes:
request = client.example_command(param_1='example_param')
In the normal case this will block until the request completes. Request completion is determined by periodically polling beer-garden to check the Request status. The time between polling requests starts at 0.5s and doubles each time the request has still not completed, up to max_delay. If a timeout was specified and the Request has not completed within that time a
ConnectionTimeoutError
will be raised.It is also possible to create the SystemClient in non-blocking mode by specifying blocking=False. In this case the request creation will immediately return a Future and will spawn a separate thread to poll for Request completion. The max_concurrent parameter is used to control the maximum threads available for polling.
# Create a SystemClient with blocking=False client = SystemClient(host, port, 'example_system', ssl_enabled=True, blocking=False) # Create and send 5 requests without waiting for request completion futures = [client.example_command(param_1=number) for number in range(5)] # Now wait on all requests to complete concurrent.futures.wait(futures)
If the request creation process fails (e.g. the command failed validation) and version_constraint is ‘latest’ then the SystemClient will check to see if a different version is available, and if so it will attempt to make the request on that version. This is so users of the SystemClient that don’t necessarily care about the target system version don’t need to be restarted if the target system is updated.
- Tweaking beer-garden Request Parameters:
There are several parameters that control how beer-garden routes / processes a request. To denote these as intended for beer-garden itself (rather than a parameter to be passed to the Plugin) prepend a leading underscore to the argument name.
Sending to another instance:
request = client.example_command(_instance_name='instance_2', param_1='example_param')
Request with a comment:
request = client.example_command(_comment='I'm a beer-garden comment!', param_1='example_param')
Without the leading underscore the arguments would be treated the same as param_1 - another parameter to be passed to the plugin.
Parameters: - host – beer-garden REST API hostname.
- port – beer-garden REST API port.
- system_name – The name of the system to use.
- version_constraint – The system version to use. Can be specific or ‘latest’.
- default_instance – The instance to use if not specified when creating a request.
- always_update – Should check for a newer System version before each request.
- timeout – Length of time to wait for a request to complete. ‘None’ means wait forever.
- max_delay – Maximum time to wait between checking the status of a created request.
- api_version – beer-garden API version.
- ssl_enabled – Flag indicating whether to use HTTPS when communicating with beer-garden.
- ca_cert – beer-garden REST API server CA certificate.
- blocking – Block after request creation until the request completes.
- max_concurrent – Maximum number of concurrent requests allowed.
- client_cert – The client certificate to use when making requests.
- url_prefix – beer-garden REST API URL Prefix.
- ca_verify – Flag indicating whether to verify server certificate when making a request.
- raise_on_error – Raises an error if the request ends in an error state.
- username – Username for Beergarden authentication
- password – Password for Beergarden authentication
- access_token – Access token for Beergarden authentication
- refresh_token – Refresh token for Beergarden authentication
- client_timeout – Max time to will wait for server response
-
create_bg_request
(command_name, **kwargs)[source]¶ Create a callable that will execute a beer-garden request when called.
Normally you interact with the SystemClient by accessing attributes, but there could be certain cases where you want to create a request without sending it.
Example:
client = SystemClient(host, port, 'system', blocking=False) requests = [] # No arguments requests.append(client.create_bg_request('command_1')) # arg_1 will be passed as a parameter requests.append(client.create_bg_request('command_2', arg_1='Hi!')) futures = [request() for request in requests] # Calling creates and sends the request concurrent.futures.wait(futures) # Wait for all the futures to complete
Parameters: - command_name – The name of the command that will be sent.
- kwargs – Additional arguments to pass to send_bg_request.
Raises: AttributeError – The system does not have a command with the given command_name.
Returns: A partial that will create and execute a beer-garden request when called.
-
load_bg_system
()[source]¶ Query beer-garden for a System definition
This method will make the query to beer-garden for a System matching the name and version constraints specified during SystemClient instance creation.
If this method completes successfully the SystemClient will be ready to create and send Requests.
Raises: FetchError – If unable to find a matching System Returns: None
-
send_bg_request
(**kwargs)[source]¶ Actually create a Request and send it to beer-garden
Note
This method is intended for advanced use only, mainly cases where you’re using the SystemClient without a predefined System. It assumes that everything needed to construct the request is being passed in kwargs. If this doesn’t sound like what you want you should check out create_bg_request.
Parameters: kwargs – All necessary request parameters, including beer-garden internal parameters Raises: ValidationError – If the Request creation failed validation on the server Returns: If the SystemClient was created with blocking=True a completed request object, otherwise a Future that will return the Request when it completes.
Module contents¶
-
brewtils.rest.
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