"""
argparse_helpers: Some convenience helpers for argparse
-Featuring
-- NonExitingParser: a subclass of ArgumentParser that does not do sys.exit(2)
- on parse error but instead raises a ArgParserWantsExit exception.
-- function existing_file which can be used as a type in add_argument() calls
+Featuring:
+ - NonExitingParser: a subclass of :py:class:`argparse.ArgumentParser`
+ that does not do *sys.exit(2)* on parse error but instead raises a
+ :py:class:`ArgParserWantsExit` exception.
+ - function existing_file/dir[_or_empty] which can be used as a type in calls to
+ :py:func:`argparse.ArgumentParser.add_argument`
.. codeauthor:: Intra2net
"""
"""
Wait for the 'generate' program to complete.
- Arguments are similar to the ones from :py:method:`wait_for_run`.
+ Arguments are similar to the ones from :py:func:`wait_for_run`.
"""
wait_for_run('generate', timeout=timeout, retries=1, vm=vm)
wait_for_run('generate_offline', timeout=timeout, retries=1, vm=vm)
:rtype: [dict]
Output varies depending on a few conditions:
- - If `root` is a list, return it right away
- - If `root` is a dict corresponding to a valid CNF value, return it wrapped
- in a list
- - If `root` is a dict with a `cnf` key containg a list (as the JSON
- returned by `get_cnf -j`), return the value
- - Otherwise, raise an error
+ - If `root` is a list, return it right away
+ - If `root` is a dict corresponding to a valid CNF value, return it wrapped
+ in a list
+ - If `root` is a dict with a `cnf` key containg a list (as the JSON
+ returned by `get_cnf -j`), return the value
+ - Otherwise, raise an error
"""
if isinstance(root, list):
return root
get_logger: factor for creating I2nLoggers
-Further ideas: ::
-* allow milliseconds in dateformat field (see test_short_level_format)
-* create own basicConfig-like function that uses our classes as default
- --> started using I2nLogger constructor and get_logger
-* try to find out module that calls I2nLogger constructor to provide a good
- default value for name (finding out the current module is a pain in the a..)
+Further ideas:
+ * allow milliseconds in dateformat field (see test_short_level_format)
+ * create own basicConfig-like function that uses our classes as default
+ --> started using I2nLogger constructor and get_logger
+ * try to find out module that calls I2nLogger constructor to provide a good
+ default value for name (finding out the current module is a pain in the a..)
.. todo:: create unittests from test_* functions at bottom
.. todo:: think about how to allow different levels per handler
* can limit the number of lines this logger will produce to prevent filling
hard drive with log file
(assumes one line per call to log/debug/info/notice/...,
- only counts calls with priority above this logger's level)
+ only counts calls with priority above this logger's level)
* provides shorter method names: dbg, note, warn, err
* adds a NullHandler if `streams` and `files` and `handlers` are all `None`
* convenience functions to add most frequently used handlers
Intended for overwriting in subclasses.
- This function is called from __iter__ for each new data that becomes
+ This function is called from `__iter__` for each new data that becomes
available. It has to provide results which are forwarded to caller.
This base implementation just yields its input, so new data is yielded
:py:data:`self.descriptions`
:param str data: Text data read from source
:param idx: Index of data source
- :returns: nothing but yields [(description, data, idx], same as input
+ :returns: nothing but yields [(description, data, idx)], same as input
"""
yield description, data, idx
If line is not complete, then buffer it.
Args: see super class method :py:meth:`IterativeReader.prepare_result`
+
:returns: list of 3-tuples `(description, line, idx)` where
`description` and `idx` are same as args, and `line` is
without trailing newline characters
Iteration returns :py:class:`re.match` result or -- if matching failed --
None. The latest unparsed line is available as `self.last_unparsed_line`.
- Usage recommendation:
+ Usage recommendation::
with open(log_file_name, 'rt') as file_handle:
parser = log_read.LogParser(file_handle, pattern=my_pattern):
Try parsing lines.
Args: see super class method :py:meth:`IterativeReader.prepare_result`
+
:returns: 3-tuples `(description, line, idx)` where `description` and
`idx` are same as input args and `line` is either a
:py:class:`re.Match` if line matched :py:data:`self.pattern`
"""
Open single file, yield LogParser. Ensures file is closed afterwards.
- This allows opening file and creation LogParser for it to one line:
+ This allows opening file and creation LogParser for it to one line::
with LogParser.create_for('/var/log/messages', SYS_LOG_PATTERN) as parser:
for _, matches, _ in parser:
Removes the SMTP envelope surrounding the email if present. Only left-over
might be a line with a '.' at end of non-multipart messages if
- `headers_only` is False.
+ `headers_only` is False.
:param str file_name: path to the file that contains the email text
:param bool headers_only: whether to parse only the email headers; set this
continue
...
- Finds the first part in message that is of type text/plain and decodes it
+ Finds the first part in message that is of type `text/plain` and decodes it
using encoding specified in mail or otherwise fallback encoding. If none
- found takes first part of type "text/*", or otherwise just the first part.
+ found takes first part of type `text/*`, or otherwise just the first part.
- If include_all_text is True, all text/* parts are included, with text/plain
+ If include_all_text is True, all `text/*` parts are included, with `text/plain`
being the first.
:param str filename: complete path of message file in filesystem
:param str fallback_encoding: Encoding of email text if none is specified
in mail.
- :param bool include_all_text: include all "text/*" parts in returned text
+ :param bool include_all_text: include all `text/*` parts in returned text
:returns: text(s) of message
:rtype: [str] if include_all_text else str
"""
:param cond: Function to call; code will wait for this to return something
other than `False`
:param interval: Time (in seconds) to sleep between each attempt at `cond`
- :returns: Pair of result and error message if appropriate or :py:value:`None`.
+ :returns: A Pair of result and error message if appropriate or `None`.
:rtype: (run_result, str | None)
"""
llog.debug("cmd_block_till: %r, %d s, %r", cmd, timeout, cond)