escale.base package

This package implements the high-level logic of the project.

escale.base.essential module

class escale.base.essential.Reporter(logger=None, ui_controller=None, **ignored)

Bases: object

Base class for log- and user-interface- enabled classes.

In a feature release, logger may become a property.

logger

logger.

Type:Logger or LoggerAdapter
ui_controller

user-interface controller.

Type:DirectController or UIController
logger
ui_controller
escale.base.essential.asbytes(s)

Coerce bytes-like object to bytes (Python 3) or str (Python 2).

escale.base.essential.asstr(s)

Coerce string to str type.

In Python 2, s can be of type str or unicode. In Python 3, s can be of type bytes or str.

Parameters:s (str-like) – string.
Returns:regular string.
Return type:str
escale.base.essential.copyfile(from_file, to_file)
escale.base.essential.join(dirname, *extranames)

Combine path elements similarly to os.path.join().

Arguments are properly coerced and the extra path elements are considered relative even if they begin with a file separator.

Only slashes (/) are considered as valid file separators.

Parameters:
  • dirname (str-like) – directory name.
  • extraname (str-like) – subdirectory or file name.
Returns:

full path.
Return type:

str
escale.base.essential.quote_join(words, final=' or ', join=', ', quote="'")

Join words.

Example:

>>> quote_join(list(range(1,4)))
"'1', '2' or '3'"
Parameters:
  • words (list) – list of objects that implement __str__.
  • final (str) – connector between the two last words.
  • join (str) – connector between the first words but the last.
  • quote (str or tuple) – begin and end quotes for the words.
Returns:

formated sentence.
Return type:

str
escale.base.essential.relpath(path, start)

Call os.path.relpath and handle “OSError: [Errno 2] No such file or directory” exceptions on os.getcwd().

If the start directory is not defined, path is returned.

escale.base.exceptions module

exception escale.base.exceptions.LicenseError

Bases: exceptions.ValueError

exception escale.base.exceptions.MissingResource

Bases: exceptions.Exception

exception escale.base.exceptions.MissingSetupFeature

Bases: exceptions.ImportError

This exception helps document missing dependencies at runtime.

It is designed for setup features that select optional relay and encryption backends.

exception escale.base.exceptions.PostponeRequest

Bases: exceptions.Exception

exception escale.base.exceptions.QuotaExceeded(used_space=None, quota=None)

Bases: exceptions.EnvironmentError

args
exception escale.base.exceptions.RestartRequest

Bases: exceptions.Exception

escale.base.exceptions.format_exc(exc, expand=<type 'exceptions.Exception'>)

escale.base.timer module

class escale.base.timer.Clock(initial_delay=1, max_delay=None, timeout=None, max_count=None, count_at_max_delay=10)

Bases: object

Generate increasing time intervals.

Successive time intervals monotonically increase following a tanh function:

t_n = t_0 + (t_N - t_0) / (1 + exp(N - 2*n))

where t_0 is the initial delay, t_n is the delay at iteration n and N is one of the first iterations with maximum delay.

Clock implements the iterator interface.

count

number of time interval requests.

Type:float
max_count

maximum number of time interval requests.

Type:int or float
count_at_max_delay

N.

Type:int
initial_delay

first time interval in seconds.

Type:float
max_delay

maximum delay.

Type:float
cumulated_time

cumulated time in seconds.

Type:float
timeout

maximum cumulated time.

Type:int or float
precision

order at which time intervals are rounded.

Type:float
next()

Generate a new time interval.

Returns:time interval in seconds.
Return type:float
wait(logger=None)

Call next() and sleep during the returned duration.

escale.base.ssl module

escale.base.ssl.make_https_adapter(ssl_version_or_context)

Make a HTTPSAdapter class that inheritates from HTTPAdapter and forces a specific SSL version.

Parameters:ssl_version_or_context (int or ssl.SSLContext) – any of ssl.PROTOCOL_* codes or an SSLContext.
Returns:class, child of HTTPAdapter.
Return type:HTTPSAdapter
escale.base.ssl.parse_ssl_version(ssl_version)

Parse SSL version.

Note

support for ‘SSLv2’ and ‘SSLv3’ has been dropped by the standard ssl module and these values will be translated to ‘SSLv23’.

Parameters:ssl_version (int or str) – either any of ssl.PROTOCOL_* or any of ‘SSLv2’, ‘SSLv3’, ‘SSLv23’, ‘TLS’ (recommended), ‘TLSv1’, ‘TLSv1.1’ or ‘TLSv1.2’.
Returns:one of ssl.PROTOCOL_* codes or an SSLContext with modified options.
Return type:int or ssl.SSLContext

escale.base.config module

escale.base.config.actual_option(config, section, options)

Option name actually used in a configuration object.

Parameters:
  • config (ConfigParser) – config object.
  • section (str) – config section name.
  • options (str, tuple or list) – field name (see fields) or extended option description.
Returns:

option name.
Return type:

str
escale.base.config.crawl_config(fun, config=None)
escale.base.config.default_option(field, all_options=False)

Return the first option for a field declared in fields.

escale.base.config.full_address(config, section)

Parse the relay repository address.

A relay address can be either a local path or a url.

Parameters:
  • config (ConfigParser) – config object.
  • section (str) – config section name.
Returns:

relay address.
Return type:

str
escale.base.config.getlist(config, section, attr)

Getter for lists.

Parameters:
  • config (ConfigParser) – configuration object.
  • section (str) – existing configuration section.
  • attr (str) – existing configuration option.
Returns:

list of non-empty strings.
Return type:

list
escale.base.config.getnum(config, section, attr)

Getter for numbers accompanied with a unit.

A number can be formatted as [0-9]+([.,][0-9]+)? and a unit as [a-zA-Z]+.

Parameters:
  • config (ConfigParser) – configuration object.
  • section (str) – existing configuration section.
  • attr (str) – existing configuration option.
Returns:

numeric value and unit.
Return type:

(float, str)
escale.base.config.getpath(config, section, attr)

Getter for paths.

Parameters:
  • config (ConfigParser) – configuration object.
  • section (str) – existing configuration section.
  • attr (str) – existing configuration option.
Returns:

path.
Return type:

str
escale.base.config.getter(_type='str')

Config getter.

Parameters:_type (str) – either bool, int, float, str, path or list.
Returns:getter(config (ConfigParser), section (str), field (str))
Return type:function
escale.base.config.ispc()
escale.base.config.parse_cfg(cfg_file='', msgs=[], new=False)

Parse a configuration file.

Parameters:
  • cfg_file (str) – path to a configuration file.
  • msgs (list) – list of pending messages.
  • new (bool) – if True and cfg_file does not exist, create the file.
Returns:

first argument is the parsed configuration, second argument is the corresponding file path, third argument is the list of pending messages.
Return type:

(ConfigParser, str, list)
new in version 0.5: the returned ConfigParser object contains an extra
attribute filename which value equals to the second returned argument.
escale.base.config.parse_field(config, section, attrs, getters=None, logger=None)

Parse an option from a field description.

Parameters:
  • config (ConfigParser) – config object.
  • section (str) – section name.
  • attrs (tuple or list) – field description as in fields.
  • getters (list) – list of getters (callables); default is [ ConfigParser.get ].
  • logger (Logger) – logger for warning messages.
Returns:

option value.
Return type:

any
escale.base.config.parse_fields(config, section, fields_=None, logger=None)

Extract several options from a configuration object.

Parameters:
  • config (ConfigParser) – configuration object.
  • section (str) – existing section in config.
  • fields (dict) – option definition, e.g. ~escale.base.config.fields.
  • logger (Logger) – logger.
Returns:

dictionnary whose keys are borrowed from those in fields and values are the parsed option values.
Return type:

dict
escale.base.config.parse_num(value)

Parse a numeric value with option unit string.

Parameters:str – number as a string.
Returns:numeric value and unit.
Return type:(float, str)
escale.base.config.parse_others(config, section, exclude={'address': ['host address', 'relay address', 'remote address', 'address'], 'allow_page_deletion': ('bool', ['allow page deletion', 'page deletion']), 'certfile': ('path', ['certfile', 'cert file', 'certificate']), 'checksum': (('bool', 'str'), ['checksum', 'hash algorithm']), 'checksumcache': (('bool', 'path'), ['checksum cache']), 'clientname': ['client name', 'client'], 'count': ('int', ['puller count', 'pullers']), 'directory': ['host directory', 'relay directory', 'remote directory', 'directory', 'relay dir', 'remote dir', 'host dir', 'dir', 'host path', 'relay path', 'remote path'], 'encryption': (('bool', 'str'), ['encryption']), 'exclude': ('list', ['exclude', 'exclude files']), 'excludedirectory': ('list', ['exclude directory', 'exclude directories']), 'filetype': ('list', ['file extension', 'file type']), 'include': ('list', ['include', 'include files', 'pattern', 'filter']), 'includedirectory': ('list', ['include directory', 'include directories']), 'index': (('bool', 'str'), ['index', 'compact']), 'keyfile': ('path', ['keyfile', 'key file', 'private key']), 'locktimeout': (('bool', 'int'), ['lock timeout']), 'maintainer': ['maintainer', 'email'], 'maxpagesize': ('number_unit', ['maxpagesize', 'maxarchivesize']), 'maxpendingtransfers': ('int', ['max pending transfers']), 'minsplitsize': ('int', ['min split size', 'split size', 'split']), 'mode': ['mode', 'synchronization mode'], 'passphrase': (('path', 'str'), ['passphrase', 'key']), 'password': (('path', 'str'), ['password', 'secret', 'secret file', 'credential']), 'path': ('path', ['local path', 'path']), 'port': ['port', 'host port', 'relay port', 'remote port'], 'pull_only': ('bool', ['pull only', 'write only']), 'pulloverwrite': ('bool', ['pull overwrite']), 'push_only': ('bool', ['push only', 'read only']), 'quota': ('number_unit', ['disk quota', 'quota']), 'refresh': (('bool', 'float'), ['refresh']), 'retryonerror': ('list', ['retryonerror', 'retry on error']), 'ssl_version': ['ssl version'], 'timestamp': (('bool', 'str'), ['modification time', 'timestamp', 'mtime']), 'username': ['user', 'auth user', 'host user', 'relay user', 'remote user'], 'verbosity': ('int', ['verbosity', 'verbosity level']), 'verify_ssl': ('bool', ['verify ssl'])})

Extract options that are NOT listed in exclude.

Parameters:
  • config (ConfigParser) – configuration object.
  • section (str) – existing section in config.
  • exclude (list or dict) – option list or option definition similar to the global ~escale.base.config.fields.
Returns:

dictionnary with options as keys and the corresponding value as value.
Return type:

dict
escale.base.config.write_config(cfg_file, config)

escale.base.subprocess module

escale.base.subprocess.with_subprocess(cmd, *args, **kwargs)

Execute an external command.

Parameters:
  • cmd (str) – (path to) command free of input arguments. Input arguments to cmd are provided separately as *args.
  • output (bool) – return stdout command output (str) if stderr was silent, or otherwise (stdout, stderr) command output ((str, str). (default: False)
  • wait (bool) – wait for completion but do not return anything. (default: False)
  • error (bool or Exception) – if stderr receives input, raise an error with stderr input as __init__ argument. Default exception is RuntimeError. (default: False)
  • input (bool) – call input or raw_input and relay the user-supplied input to the command. (default: False)

input, output, wait and error can be passed only as keyword arguments.

The extra keyword arguments are passed to subprocess.Popen.

Note that if you set error to True or any Exception, output implicitly defaults to True. You can prevent this behavior by explicitly passing output=False.

Similarly, if output is True, errors are also caught and no longer appear on stdout. To prevent this, explicitly set error to False.

If stdout or stderr are set as extra keyword arguments, these explicit values prevail over those derived from the output and error arguments.

See also https://docs.python.org/2.7/library/subprocess.html.

escale.base.launcher module

escale.base.launcher.escale(config, repository, log_handler=None, ui_connector=None)

Read the section related to a repository in a loaded configuration object and runs a Manager for that repository.

Parameters:
  • config (ConfigParser) – configuration object.
  • repository (str) – configuration section name or, alternatively, client name.
  • log_handler (log handler) – input argument to addHandler().
  • ui_connector (any) – connector to user-interface controller.
escale.base.launcher.escale_launcher(cfg_file, msgs=[], verbosity=0, keep_alive=None)

Parse a configuration file, set the logger and launch the clients in separate subprocesses.

Parameters:
  • cfg_file (str) – path to a configuration file.
  • msgs (list) – list of pending messages (str or tuple).
  • verbosity (bool or int) – verbosity level.
  • keep_alive (bool or int) – if True or non-negative int, clients are ran again after they hit an unrecoverable error; multiple threads and subprocesses are started even if a single client is defined; if int, specifies default sleep time after a subprocess crashed.
escale.base.launcher.make_client(config, repository, log_handler=None, ui_connector=None)

Initialize an escale client.

The client-specific logger and a manager are set.

Parameters:
  • config (ConfigParser) – config object.
  • repository (str) – config section name.
  • log_handler (any) – passed to addHandler() (see the logging module).
  • ui_connector (tuple) – arguments passed to UIController.
Returns:

client manager.
Return type:

escale.manager.Manager or escale.manager.index.IndexManager