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) orstr
(Python 2).
-
escale.base.essential.
asstr
(s)¶ Coerce string to
str
type.In Python 2, s can be of type
str
orunicode
. In Python 3, s can be of typebytes
orstr
.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 iterationn
andN
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
-
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 anSSLContext
.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
orlist
.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 anyException
, output implicitly defaults toTrue
. You can prevent this behavior by explicitly passingoutput=False
.Similarly, if output is
True
, errors are also caught and no longer appear on stdout. To prevent this, explicitly set error toFalse
.If
stdout
orstderr
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: