Connection multi classes

This file describes the utility wrapper for multiple connections.

ssh_utilities.multi_connection

The main module with toplevel MultiConnection class.

The connection class is the main public class that initializes local or remote connection arrays of classes as needed abcd on input arguments.

class ssh_utilities.multi_connection.MultiConnection(ssh_servers: Union[List[str], str], local: Union[List[bool], bool] = False, quiet: bool = False, thread_safe: Union[List[bool], bool] = False, allow_agent: Union[List[bool], bool] = True)

Bases: ssh_utilities.multi_connection._dict_interface.DictInterface, ssh_utilities.multi_connection._persistence.Pesistence, ssh_utilities.abstract._connection.ConnectionABC

Wrapper for multiple connections.

All methods work exactly the same as for single connections, only now they return Generators instead of their respective values. Can be used to prallelize connections or to share one ssh connection or just to cleverly manage pool of connections.

Connection can be effectively made parallel by passig same key more times to the constructor or by other methods. Namely __add__, __setitem__, update. This means that in fact under each key a pool of connections can be registered. These are organized in collections.deque.

The MultiConnection supports dict interface but with few differences as more connections can be registered under one key. Basically you can think of it as a distionary which allows duplicit keys. All the dict methods work as expected. See expamples section or docs for more detailes.

Parameters:

ssh_servers (Union[List[str], str]) – list od ssh srevers to connect to
local (Union[List[bool], bool], optional) – bool or list of bools specifying if the respective connection(s), should be local or remote by default False
quiet (bool, optional) – bool or a list of bools specifing if login messages should be printed, on individula connections initialization by default False
thread_safe (Union[List[bool], bool], optional) – bool or a list of bools specifying if respective connection(s) should, be made thead safe or not by default False

Examples

Make connection parallel

>>> from ssh_utilities import MultiConnection
>>> # this will create two connection instances both connected to server1
>>> Multiconnection([server1, server1])

This results in MultiConnection with a pool of two connections to server1 registered under key server1

Dict intreface

>>> from ssh_utilities import MultiConnection
>>> mc = Multiconnection([server1, server1])
>>> # we always implement normal dict-like method which works as expected
>>> mc.get(server1)
>>> <SSHConnection instance connected to server1>
>>> # in each case there is always also a method with `_all` suffix by
>>> # which you can acces the whole pool of connections registered under
>>> # the key
>>> mc.get_all(server1)
>>> <deque with two independent SSHConnections to server 1>

classmethod add_hosts(hosts: Union[_HOSTS, List[_HOSTS]], allow_agent: Union[bool, List[bool]])

Add or override availbale host read fron ssh config file.

You can use supplied config parser to parse some externaf ssh config file.

Parameters:	hosts (Union[_HOSTS, List[_HOSTS]]) – dictionary or a list of dictionaries containing keys: user, hostname and identityfile allow_agent (Union[bool, List[bool]]) – bool or a list of bools with corresponding length to list of hosts. if only one bool is passed in, it will be used for all host entries

See also

:func:ssh_utilities.config_parser

builtins

Inner class providing access to substitutions for python builtins.

Type:	abc.Builtins

classmethod get_available_hosts() → List[str]

List all elegible hosts for connection from ~/.ssh/config.

Returns:	list of available hosts
Return type:	List[str]

os

Inner class providing access to substitutions for python os module.

Type:	abc.Os

pathlib

Inner class providing access to substitutions for pathlib module.

Type:	abc.Pathlib

shutil

Inner class providing access to substitutions for shutil module.

Type:	abc.Shutil

subprocess

Inner class providing access to substitutions for subprocess module.

Type:	abc.Subprocess

to_dict() → Dict[int, Dict[str, Union[str, bool, int, None]]]

Saves all the importatnt info from object to dictonary.

Returns:	dictionary representing the object
Return type:	Dict[int, Dict[str, Optional[Union[str, bool, int, None]]]]

ssh_utilities.multi_connection._delegated

Module that provides delegation callables.

These callables defer calls from MultiConnection to individual connections.

ssh_utilities.multi_connection._delegated.Inner(abc_parent: ABCs, multi_connection: MultiConnection)

Class implementing the inner classes of connection object.

Reimplementation of abstract methods is done auto-magically. This function is esentially a factory for the inner classes of connection.

This makes the class hierarchy ‘transposed’ instead of this:

>>> [Connection1.method1(), Connection2.method1()]
>>> [Connection1.method2(), Connection2.method2()]

we now essentialy have:

>>> method1[Connection1, Connection2]
>>> method2[Connection1, Connection2]

The methods become classes and each one holds reference to all open connections

Parameters:	abc_parent (ABCs) – The abstract parent that is going to be reimplemented multi_connection (MultiConnection) – reference to MultiConnection object

See also

ssh_utilities.multi_conncection.MultiConnection

ssh_utilities.multi_connection._dict_interface

Module providing dictionary interface for multi_connection.

class ssh_utilities.multi_connection._dict_interface.DictInterface

Bases: collections.abc.MutableMapping

Class providing dictionary interface methods to MultiConnection.

See also

ssh_utilities.multi_conncection.MultiConnection

_add_multi(other: MultiConnection): Register multiple new connections.

_add_one(other: _CONN, key: Optional[str] = None)

Add one connecction to the underlying dictionary.

Parameters:	other (_CONN) – SSHConnection or LocalConnection key (Optional[str]) – if used connection is added under this key, else key is extracted from connection.server_name attribute

Warning

If key is already pressent among registered connections no KeyError is raised as one would expect in dictionary but instead connection is added to the pool of connections to the specific host

clear(): Close and delete all underlying connections.

copy() → _DictInterface1

Get a shallow copy of MultiConnection.

Returns:	MultiConnection object shallow copy
Return type:	MultiConnection

get(key: str, *args) → Optional[_CONN]

Get one connection from MultiConnection object based on key.

This will return only one connection from pool registered under key.

Parameters:	key (str) – key denoting the connection default (Any, optional) – optianal value returned if key is not pressent
Returns:	SSHConnection or LocalConnection object shallow copy
Return type:	_CONN
Raises:	`KeyError` – if the input key is not present among the connections and default is not defined.

get_all(key: str, *args) → Optional[Deque[_CONN]]

Get pool of connections from MultiConnection object based on key.

This will return the all the connections registered under key orgainzed in collections.deque

Parameters:	key (str) – key denoting the connection pool default (Any, optional) – optianal value returned if key is not pressent
Returns:	SSHConnection or LocalConnection object shallow copy
Return type:	_CONN
Raises:	`AttributeError` – if the input key is not present among the connections and default is not defined.

items() → ItemsView[str, _CONN]

Iterate over key, Connection pairs same as dict.items method.

This method returns only one connection for each registered key.

Warning

MultiConnection has seemingly duplicate keys but this is caused by the fact that each key can have multiple connections registered under itself this way connection to some host can be effectively made parallel.

Yields:	ItemsView[str, _CONN] – key, SSHConnection/LocalConnection

See also

items_all()

items_all() → ItemsView[str, _CONN]

Iterate over key, Connection pairs same as dict.items method.

This returns all connections for each registered key.

Warning

MultiConnection has seemingly duplicate keys but this is caused by the fact that each key can have multiple connections registered under itself this way connection to some host can be effectively made parallel.

Yields:	ItemsView[str, _CONN] – key, SSHConnection/LocalConnection

See also

items_all()

keys() → KeysView[str]

Iterate over registered key same as dict.keys method.

This method iterates only over unique keys.

Warning

MultiConnection has seemingly duplicate keys but this is caused by the fact that each key can have multiple connections registered under itself this way connection to some host can be effectively made parallel.

Yields:	KeysView[str] – unique keys poining to connection pools

See also

keys_all()

keys_all() → KeysView[str]

Iterate over registered key same as dict.keys method.

This method returnes each key as many times as many connections are registered in its pool.

Warning

MultiConnection has seemingly duplicate keys but this is caused by the fact that each key can have multiple connections registered under itself this way connection to some host can be effectively made parallel.

Yields:	KeysView[str] – key

See also

keys_all()

pop(key: str, *args) → _CONN

Pop one connection from MultiConnection object based on key.

Parameters:	key (str) – key denoting the connection default (Any, optional) – optianal value returned if key is not pressent
Returns:	SSHConnection or LocalConnection object
Return type:	_CONN
Raises:	`KeyError` – if the input key is not present among the connections and default is not defined.

pop_all(key: str, *args) → Deque[_CONN]

Pop pool of connections from MultiConnection object based on key.

Parameters:	key (str) – key denoting the connection default (Any, optional) – optianal value returned if key is not pressent
Returns:	SSHConnection or LocalConnection objects in deque container
Return type:	Deque[_CONN]
Raises:	`KeyError` – if the input key is not present among the connections and default is not defined.

popitem() → Tuple[str, _CONN]

Pops one key, connection pair from MultiConnection.

Returns:	key, SSHConnection/LocalConnection pair
Return type:	Tuple[str, _CONN]

popitem_all() → Tuple[str, Deque[_CONN]]

Pops one key, connection pool pair from MultiConnection.

Returns:	key, Deque[SSHConnection]/ Deque[LocalConnection] pair
Return type:	Tuple[str, Deque[_CONN]]

update(other: MultiConnection)

Updates Multiconnection with another Multiconnection.

This only merges underlying dictionaries holding connections

Parameters:	other (MultiConnection) – the added object of same type as self

values() → ValuesView[_CONN]

Iterate over registered Connections same as dict.values method.

This method returns only one connection for each registered key.

Warning

MultiConnection has seemingly duplicate keys but this is caused by the fact that each key can have multiple connections registered under itself this way connection to some host can be effectively made parallel.

Yields:	ValuesView[_CONN] – SSHConnection/LocalConnection

See also

values_all()

values_all() → ValuesView[_CONN]

Iterate over registered Connections same as dict.values method.

This method iterates all connections for each of the keys.

Warning

MultiConnection has seemingly duplicate keys but this is caused by the fact that each key can have multiple connections registered under itself this way connection to some host can be effectively made parallel.

Yields:	ValuesView[_CONN] – SSHConnection/LocalConnection

See also

values()

ssh_utilities.multi_connection._persistence

Module providing persistance methods for multi_connection.

Adds the ability to persist object using: - str - dictionary - pickle - deepcopy

class ssh_utilities.multi_connection._persistence.Pesistence

Bases: object

Class providing persistance methods to MultiConnection.

Adds the ability to persist object using: - str - dictionary - pickle - deepcopy

See also

ssh_utilities.multi_conncection.MultiConnection

static _parse_persistence_dict(d: dict) → Tuple[List[str], List[int], List[bool], List[bool]]

Parses dictionary produced by to_dict method.

Parameters:	d (dict) – dictionary of values needed to reinitialize the class
Returns:	Tuple of lists with parsed information
Return type:	Tuple[List[str], List[int], List[bool], List[bool]]

classmethod from_dict(json: dict, quiet: bool = False) → MultiConnection

Initializes Connection from str.

String must be formated as defined by base.ConnectionABC._to_str method.

Parameters:	json (dict) – dictionary initialize connection from quiet (bool) – If True suppress login messages
Returns:	initialized local or remmote connection based on parameters parsed from string
Return type:	Union[SSHConnection, LocalConnection]
Raises:	`KeyError` – if required key is missing from string

classmethod from_str(string: str, quiet: bool = False) → MultiConnection

Initializes Connection from str.

String must be formated as defined by base.ConnectionABC._to_str method.

Parameters:	string (str) – json str to initialize connection from quiet (bool) – If True suppress login messages
Returns:	initialized local or remmote connection based on parameters parsed from string
Return type:	Union[SSHConnection, LocalConnection]
Raises:	`KeyError` – if required key is missing from string

to_dict() → Dict[int, Dict[str, Union[str, bool, int, None]]]

Saves all the importatnt info from object to dictonary.

Returns:	dictionary representing the object
Return type:	Dict[int, Dict[str, Optional[Union[str, bool, int, None]]]]

values_all() → ValuesView[_CONN]: Will be reimplemented by dict interface.