Exscript.account module¶

Manages user accounts.

class Exscript.account.Account(name, password='', password2=None, key=None, needs_lock=True)[source]¶

Bases: future.types.newobject.newobject

This class represents a user account.

__init__(name, password='', password2=None, key=None, needs_lock=True)[source]¶

Constructor.

The authorization password is only required on hosts that separate the authentication from the authorization procedure. If an authorization password is not given, it defaults to the same value as the authentication password.

If the needs_lock argument is set to True, we ensure that no two threads can use the same account at the same time. You will want to use this setting if you are using a central authentication server that allows for only one login to happen at a time. Note that you will still be able to open multiple sessions at the time. It is only the authentication procedure that will not happen in parallel; once the login is complete, other threads can use the account again. In other words, the account is only locked during calls to protocols.Protocol.login() and the *authenticate* methods.

Warning

Setting lock to True drastically degrades performance!

Parameters:	name (str) – A username. password (str) – The authentication password. password2 (str) – The authorization password, if required. key (Exscript.PrivateKey) – A private key, if required. needs_lock (bool) – True if the account will be locked during login.

acquire(signal=True)[source]¶

Locks the account. Method has no effect if the constructor argument needs_lock wsa set to False.

Parameters:	signal (bool) – Whether to emit the acquired_event signal.

context()[source]¶: When you need a ‘with’ context for an already-acquired account.

get_authorization_password()[source]¶

Returns the authorization password of the account.

Return type:	string
Returns:	The account password.

get_key()[source]¶

Returns the key of the account, if any.

Return type:	Exscript.PrivateKey\|None
Returns:	A key object.

get_name()[source]¶

Returns the name of the account.

Return type:	string
Returns:	The account name.

get_password()[source]¶

Returns the password of the account.

Return type:	string
Returns:	The account password.

release(signal=True)[source]¶

Unlocks the account. Method has no effect if the constructor argument needs_lock wsa set to False.

Parameters:	signal (bool) – Whether to emit the released_event signal.

set_authorization_password(password)[source]¶

Changes the authorization password of the account.

Parameters:	password (string) – The new authorization password.

set_name(name)[source]¶

Changes the name of the account.

Parameters:	name (string) – The account name.

set_password(password)[source]¶

Changes the password of the account.

Parameters:	password (string) – The account password.

class Exscript.account.AccountManager[source]¶

Bases: future.types.newobject.newobject

Keeps track of available user accounts and assigns them to the worker threads.

__init__()[source]¶: Constructor.

acquire_account(account=None, owner=None)[source]¶

Acquires the given account. If no account is given, one is chosen from the default pool.

Parameters:	account (Account) – The account that is added. owner (object) – An optional descriptor for the owner.
Return type:	`Account`
Returns:	The account that was acquired.

acquire_account_for(host, owner=None)[source]¶

Acquires an account for the given host and returns it. The host is passed to each of the match functions that were passed in when adding the pool. The first pool for which the match function returns True is chosen to assign an account.

Parameters:	host (`Host`) – The host for which an account is acquired. owner (object) – An optional descriptor for the owner.
Return type:	`Account`
Returns:	The account that was acquired.

add_account(account)[source]¶

Adds the given account to the default account pool that Exscript uses to log into all hosts that have no specific Account attached.

Parameters:	account (Account) – The account that is added.

add_pool(pool, match=None)[source]¶

Adds a new account pool. If the given match argument is None, the pool the default pool. Otherwise, the match argument is a callback function that is invoked to decide whether or not the given pool should be used for a host.

When Exscript logs into a host, the account is chosen in the following order:

# Exscript checks whether an account was attached to the Host object using Host.set_account()), and uses that.

# If the Host has no account attached, Exscript walks through all pools that were passed to Queue.add_account_pool(). For each pool, it passes the Host to the function in the given match argument. If the return value is True, the account pool is used to acquire an account. (Accounts within each pool are taken in a round-robin fashion.)

# If no matching account pool is found, an account is taken from the default account pool.

# Finally, if all that fails and the default account pool contains no accounts, an error is raised.

Example usage:

def do_nothing(conn):
    conn.autoinit()

def use_this_pool(host):
    return host.get_name().startswith('foo')

default_pool = AccountPool()
default_pool.add_account(Account('default-user', 'password'))

other_pool = AccountPool()
other_pool.add_account(Account('user', 'password'))

queue = Queue()
queue.account_manager.add_pool(default_pool)
queue.account_manager.add_pool(other_pool, use_this_pool)

host = Host('localhost')
queue.run(host, do_nothing)

In the example code, the host has no account attached. As a result, the queue checks whether use_this_pool() returns True. Because the hostname does not start with ‘foo’, the function returns False, and Exscript takes the ‘default-user’ account from the default pool.

Parameters:	pool (AccountPool) – The account pool that is added. match (callable) – A callback to check if the pool should be used.

get_account_from_hash(account_hash)[source]¶

Returns the account with the given hash, if it is contained in any of the pools. Returns None otherwise.

Parameters:	account_hash (str) – The hash of an account object.

release_accounts(owner)[source]¶

Releases all accounts that were acquired by the given owner.

Parameters:	owner (object) – The owner descriptor as passed to acquire_account().

reset()[source]¶: Removes all account pools.

class Exscript.account.AccountPool(accounts=None)[source]¶

Bases: future.types.newobject.newobject

This class manages a collection of available accounts.

__init__(accounts=None)[source]¶

Constructor.

Parameters:	accounts (Account\|list[Account]) – Passed to add_account()

acquire_account(account=None, owner=None)[source]¶

Waits until an account becomes available, then locks and returns it. If an account is not passed, the next available account is returned.

Parameters:	account (Account) – The account to be acquired, or None. owner (object) – An optional descriptor for the owner.
Return type:	`Account`
Returns:	The account that was acquired.

add_account(accounts)[source]¶

Adds one or more account instances to the pool.

Parameters:	accounts (Account\|list[Account]) – The account to be added.

get_account_from_hash(account_hash)[source]¶: Returns the account with the given hash, or None if no such account is included in the account pool.

get_account_from_name(name)[source]¶

Returns the account with the given name.

Parameters:	name (string) – The name of the account.

has_account(account)[source]¶

Returns True if the given account exists in the pool, returns False otherwise.

Parameters:	account (Account) – The account object.

n_accounts()[source]¶: Returns the number of accounts that are currently in the pool.

release_accounts(owner)[source]¶

Releases all accounts that were acquired by the given owner.

Parameters:	owner (object) – The owner descriptor as passed to acquire_account().

reset()[source]¶: Removes all accounts.

class Exscript.account.AccountProxy(parent)[source]¶

Bases: future.types.newobject.newobject

An object that has a 1:1 relation to an account object in another process.

__init__(parent)[source]¶

Constructor.

Parameters:	parent (multiprocessing.Connection) – A pipe to the associated account manager.

acquire()[source]¶: Locks the account. Returns True on success, False if the account is thread-local and must not be locked.

context()[source]¶: When you need a ‘with’ context for an already-acquired account.

static for_account_hash(parent, account_hash)[source]¶: Returns a new AccountProxy that acquires the account with the given hash, if such an account is known to the account manager. It is an error if the account manager does not have such an account.

static for_host(parent, host)[source]¶: Returns a new AccountProxy that has an account acquired. The account is chosen based on what the connected AccountManager selects for the given host.

static for_random_account(parent)[source]¶: Returns a new AccountProxy that has an account acquired. The account is chosen by the connected AccountManager.

get_authorization_password()[source]¶

Returns the authorization password of the account.

Return type:	string
Returns:	The account password.

get_key()[source]¶

Returns the key of the account, if any.

Return type:	Exscript.PrivateKey\|None
Returns:	A key object.

get_name()[source]¶

Returns the name of the account.

Return type:	string
Returns:	The account name.

get_password()[source]¶

Returns the password of the account.

Return type:	string
Returns:	The account password.

release()[source]¶: Unlocks the account.

class Exscript.account.LoggerProxy(parent, logger_id)[source]¶

Bases: future.types.newobject.newobject

An object that has a 1:1 relation to a Logger object in another process.

__init__(parent, logger_id)[source]¶

Constructor.

Parameters:	parent (multiprocessing.Connection) – A pipe to the associated pipe handler.

add_log(job_id, name, attempt)[source]¶

log(job_id, message)[source]¶

log_aborted(job_id, exc_info)[source]¶

log_succeeded(job_id)[source]¶