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)¶ 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 methos 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]])¶ 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 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
() → 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
-
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
() → 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
-
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
() → 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
-
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.
-
static