Transports¶
Abstract transport and state machine for hosts state.
- class cumin.transports.Command(command, timeout=None, ok_codes=None)[source]¶
Bases:
object
Class to represent a command.
Command constructor.
- Parameters:
command (str) -- the command to execute.
timeout (int, optional) -- the command's timeout in seconds.
ok_codes (list, optional) -- a list of exit codes to be considered successful for the command. The exit code zero is considered successful by default, if this option is set it override it. If set to an empty list
[]
, it means that any code is considered successful.
- __repr__()[source]¶
Return the representation of the
Command
.The representation allow to instantiate a new
Command
instance with the same properties.- Returns:
the representation of the object.
- Return type:
- __str__()[source]¶
Return the string representation of the command.
- Returns:
the string representation of the object.
- Return type:
- __eq__(other)[source]¶
Equality operation. Allow to directly compare a
Command
object to another or a string.
- __ne__(other)[source]¶
Inequality operation. Allow to directly compare a Command object to another or a string.
- property timeout¶
Timeout of the
Command
.- Getter:
Returns the current timeout or
None
if not set.- Setter:
float
,int
,None
: the timeout in seconds for the execution of the command on each host. Bothfloat
andint
are accepted and converted internally tofloat
. IfNone
the timeout is reset to its default value.- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- property ok_codes¶
List of exit codes to be considered successful for the execution of the
Command
.- Getter:
Returns the current ok_codes or a
list
with the element0
if not set.- Setter:
list[int]
,None
: list of exit codes to be considered successful for the execution of the command on each host. Must be alist
ofint
in the range0-255
included, orNone
to unset it. The exit code0
is considered successful by default, but it can be overriden setting this property. Set it to an emptylist
to consider any exit code successful.- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- class cumin.transports.State(init=None)[source]¶
Bases:
object
State machine for the state of a host.
State constructor. The initial state is set to pending it not provided.
- Parameters:
init (int, optional) -- the initial state from where to start. The pending state will be used if not set.
- Raises:
cumin.transports.InvalidStateError -- if init is an invalid state.
- pending = 0¶
Valid state property, one for each
cumin.transports.State.valid_states
.
- scheduled = 1¶
Valid state property, one for each
cumin.transports.State.valid_states
.
- running = 2¶
Valid state property, one for each
cumin.transports.State.valid_states
.
- success = 3¶
Valid state property, one for each
cumin.transports.State.valid_states
.
- failed = 4¶
Valid state property, one for each
cumin.transports.State.valid_states
.
- timeout = 5¶
Valid state property, one for each
cumin.transports.State.valid_states
.
- states_representation = ('pending', 'scheduled', 'running', 'success', 'failed', 'timeout')¶
Tuple with the string representations of the valid states.
- Type:
tuple()
- allowed_state_transitions = {0: (1,), 1: (2,), 2: (2, 3, 4, 5), 3: (0,), 4: (), 5: ()}¶
Dictionary with
{valid state: tuple of valid states}
mapping of the allowed transitions between all the possile states.This is the diagram of the allowed transitions:
- Type:
- __getattr__(name)[source]¶
Attribute accessor.
- Accessible properties:
- Parameters:
according to Python's Data model
object.__getattr__()
.- Raises:
exceptions.AttributeError -- if the attribute name is not available.
- __repr__()[source]¶
Return the representation of the
State
.The representation allow to instantiate a new
State
instance with the same properties.- Returns:
the representation of the object.
- Return type:
- __str__()[source]¶
Return the string representation of the state.
- Returns:
the string representation of the object.
- Return type:
- update(new)[source]¶
Transition the state from the current state to the new one, if the transition is allowed.
- Parameters:
new (int) -- the new state to set. Only specific state transitions are allowed.
- Raises:
cumin.transports.StateTransitionError -- if the transition is not allowed, see
allowed_state_transitions
.
- _cmp(other)[source]¶
Comparison operation. Allow to directly compare a state object to another or to an integer.
- Parameters:
other (mixed) -- the object to compare the current instance to.
- Raises:
ValueError -- if the comparing object is not an instance of State or an integer.
- exception cumin.transports.WorkerError[source]¶
Bases:
CuminError
Custom exception class for worker errors.
- exception cumin.transports.StateTransitionError[source]¶
Bases:
CuminError
Exception raised when an invalid transition for a node's State was attempted.
- exception cumin.transports.InvalidStateError[source]¶
Bases:
CuminError
Exception raised when an invalid transition for a node's State was attempted.
- class cumin.transports.Target(hosts, batch_size=None, batch_size_ratio=None, batch_sleep=None)[source]¶
Bases:
object
Targets management class.
Constructor, inizialize the Target with the list of hosts and additional parameters.
- Parameters:
hosts (ClusterShell.NodeSet.NodeSet, list) -- hosts that will be targeted, both
ClusterShell.NodeSet.NodeSet
andlist
are accepted and converted automatically toClusterShell.NodeSet.NodeSet
internally.batch_size (int, optional) -- set the batch size so that no more that this number of hosts are targeted at any given time. It must be a positive integer. If greater than the number of hosts it will be auto-resized to the number of hosts.
batch_size_ratio (float, optional) -- set the batch size with a ratio so that no more that this fraction of hosts are targeted at any given time. It must be a float between 0 and 1 and will raise exception if after rounding it there are 0 hosts selected.
batch_sleep (float, optional) -- sleep time in seconds between the end of execution of one host in the batch and the start in the next host. It must be a positive float.
- Raises:
cumin.transports.WorkerError -- if the hosts parameter is empty or invalid, if both the batch_size and batch_size_ratio parameters are set or if the batch_size_ratio selects no hosts.
- property first_batch¶
First batch of the hosts to target.
- Getter:
Returns a
ClusterShell.NodeSet.NodeSet
of the first batch of hosts, according to the batch_size.
- _compute_batch_size(batch_size, hosts)[source]¶
Compute the batch_size based on the hosts size and return the value to be used.
- Parameters:
batch_size (int, None) -- a positive integer to indicate the batch_size to apply when executing the worker or
None
to get its default value of all the hosts. If greater than the number of hosts, the number of hosts will be used as value instead.hosts (ClusterShell.NodeSet.NodeSet) -- the list of hosts to use to calculate the batch size.
- Returns:
the effective batch_size to use.
- Return type:
- class cumin.transports.BaseWorker(config, target)[source]¶
Bases:
object
abstract
Worker interface to be extended by concrete workers.Worker constructor. Setup environment variables and initialize properties.
- Parameters:
- abstract execute()[source]¶
Execute the task as configured.
- Returns:
0
on success, a positive integer on failure.- Return type:
- Raises:
cumin.transports.WorkerError -- if misconfigured.
- abstract get_results()[source]¶
Iterate over the results (generator).
- Yields:
tuple -- with
(hosts, result)
for each host(s) of the current execution.
- property commands¶
Commands for the current execution.
- abstract property handler¶
Get and set the handler for the current execution.
- Getter:
Returns the current handler or
None
if not set.- Setter:
str
,EventHandler
,None
: an event handler to be notified of the progress during execution. Its interface depends on the actual transport chosen. Accepted values are: * None => don't use an event handler (default) * str => a string label to choose one of the available default EventHandler classes in that transport, * an event handler class object (not instance)
- property timeout¶
Global timeout for the current execution.
- Getter:
int: returns the current timeout or
0
(no timeout) if not set.- Setter:
int
,None
: timeout for the current execution in seconds. Must be a positive integer orNone
to reset it.- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- property success_threshold¶
Success threshold for the current execution.
- Getter:
float: returns the current success_threshold or
1.0
(100%) if not set.- Setter:
float
,None
: The success ratio threshold that must be reached to consider the run successful. Afloat
between0
and1
orNone
to reset it. The specific meaning might change based on the chosen transport.- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- cumin.transports.validate_list(property_name, value, allow_empty=False)[source]¶
Validate a list.
- Parameters:
- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- cumin.transports.validate_positive_integer(property_name, value)[source]¶
Validate a positive integer or
None
.- Parameters:
- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- cumin.transports.validate_positive_float(property_name, value)[source]¶
Validate a positive float or
None
.- Parameters:
- Raises:
cumin.transports.WorkerError -- if trying to set it to an invalid value.
- cumin.transports.raise_error(property_name, message, value)[source]¶
Raise a
WorkerError
exception.
- class cumin.transports.BaseExecutionProgress[source]¶
Bases:
object
abstract
Listener interface to consume notification of the status of successful / failed hosts.The listener needs to be notified of the total number of hosts when the operation starts, and then notified of successes and failures.
- abstract init(num_hosts: int) None [source]¶
Initialize the progress bars.
- Parameters:
num_hosts (int) -- the total number of hosts
- class cumin.transports.TqdmProgressBars[source]¶
Bases:
BaseExecutionProgress
Progress bars based on TQDM.
Create the progress bars.
Note
the progress bars themselves are not initalized at object creation.
init()
needs to be called before using the progress bars.- init(num_hosts: int) None [source]¶
Initialize the progress bars.
- Parameters:
num_hosts (int) -- the total number of hosts
- class cumin.transports.NoProgress[source]¶
Bases:
BaseExecutionProgress
Used as a null object to disable the display of execution progress.
Available transports