about_docu.rst
cnfvar-api-ascii-art.rst
-
-Modules
--------
-(List may be incomplete, see Module index below for all modules and re-create doc if something is missing)
-
.. toctree::
+ :maxdepth: 4
+
modules.rst
"""
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
"""
# Copyright (c) 2016-2022 Intra2net AG <info@intra2net.com>
"""
-arnied_api: wrappers around the arnied varlink API.
+Wrappers around the arnied varlink API.
-Featuring
-- Arnied: stateless class with methods as exposed in the varlink API.
+Featuring:
+ - Arnied: stateless class with methods as exposed in the varlink API.
For documentation of Exceptions, methods and their arguments, refer to arnied
source code (arnied/client/arnieclient.hxx). For compatibility, argument names
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Interaction with central arnied daemon.
All functions (except :py:func:`schedule` result in calling a binary
For changes of configuration (*set_cnf*, *get_cnf*), refer to :py:mod:`pyi2ncommon.cnfvar`.
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import os
"""
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)
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-string: functionality for parsing cnfvars from strings
+Functionality for parsing cnfvars from strings.
.. codeauthor:: Intra2net
-
-contents
--------------------------------------------------------------------------------
-
This module provides read and parse functionality for the Intra2net *CNF*
format from strings and by extension cnf files.
structure that needs fixup or something like that.
.. note::
- The variable values of get_cnf seems to be encoded in latin1, and set_cnf
- seems to assume latin1-encoded values (not var names). Function
- :py:func:`read_cnf` converts this to unicode and other functions convert
- unicode back to latin1.
-
-
-notes on Python 3 conversion
--------------------------------------------------------------------------------
-
-Since the original *CNF* format assumes latin-1 encoded data pretty much
-exclusively, we preserve the original encoding while parsing the file.
-When assembling the data structures returned to the user, values are then
-converted to strings so they can be used naturally at the Python end.
-
-implementation
--------------------------------------------------------------------------------
+ Since the original *CNF* format assumes latin-1 encoded data pretty much
+ exclusively, we preserve the original encoding while parsing the file.
+ When assembling the data structures returned to the user, values are then
+ converted to strings so they can be used naturally at the Python end.
"""
import functools
: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
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-summary
-------------------------------------------------------
Module for one-step dynamic cnfvar generation from default value templates.
.. codeauthor:: Intra2net
-
-contents
--------------------------------------------------------
These templates contain the bare defaults the UI adds upon
creation of each major and frequently used cnfvar.
-
-
-interface
-------------------------------------------------------
-
"""
import time
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Representation for connd state as returned by "tell-connd --status".
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import subprocess
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Dialing, hangup, general provider online/offline state control.
Copyright: 2017 Intra2net AG
This used to be part of the sysmisc utilitiy initially which caused an include
circle with the arnied wrapper.
-
-CONTENTS
-------------------------------------------------------
-dialout
- Generic access to the system’s dialing mode. Allows for requesting manual
- or permanently online dial state.
-
-arnied_dial_permanent
- Enter permantly online dialing state.
-
-arnied_dial_do
- Enter dial on command state.
-
-arnied_dial_hangup
- Terminate uplink unconditionally.
+Contents:
+ * dialout
+ Generic access to the system’s dialing mode. Allows for requesting manual
+ or permanently online dial state.
+ * arnied_dial_permanent
+ Enter permantly online dialing state.
+ * arnied_dial_do
+ Enter dial on command state.
+ * arnied_dial_hangup
+ Terminate uplink unconditionally.
All API methods come with the optional argument ``block`` (bool) to request the
call to block until the system completes the state transition successfully. The
completion timeout is currently 10 seconds (see the definition of
``DIALTOOLS_TIMEOUT`` below).
-
-
-IMPLEMENTATION
-------------------------------------------------------
-
"""
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Connection to an IMAP mailbox
Convenience wrapper around :py:class:`imaplib.IMAP4`
* use SSL connection per default, unencrypted only as option
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import imaplib
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
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Iterative reading of log files, similar to shell command `tail -f`.
Copyright: Intra2net AG
-
-CONTENTS
-------------------------------------------------------
-
Basic Functionality (class :py:class:`IterativeReader`):
Runs stat in a loop to find out whether file size has changed. Then reads the
new data and forwards that
like date, time, module name, urgency and message.
.. todo:: auto-detect log line layout
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import os
import os.path
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:
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
-Utilities for dealing with email
+Utilities for dealing with email.
.. seealso:: :py:mod:`pyi2ncommon.mail_validator`,
:py:mod:`pyi2ncommon.imap_mailbox`
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
from base64 import b64decode
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
"""
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Class :py:class:`MailValidator`, a fully-featured email sender and checker.
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import time
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Miscellaneous system utility: Collection of various common system stuff / idioms.
Copyright: 2015 Intra2net AG
-
-CONTENTS
-------------------------------------------------------
The library exports the symbols below and some custom logging functions.
-run_cmd_with_pipe
- Wrapper for the default use case of the cumbersome "subprocess" library.
- Accepts a list of arguments that describe the command invocation. Returns
- ``True`` and the contents of ``stdout`` if the pipe returned sucessfully,
- ``False`` plus ``stderr`` and the exit status otherwise. For example::
-
- import sysmisc
- (success, output, _ret) = sysmisc.run_cmd_with_pipe([ "/usr/bin/date", "+%F" ])
- if success is True:
- print("Today is %s" % output)
- else:
- print("Failed to read date from pipe.")
-
-get_mountpoints_by_type
- Extract mount points for the given file system type from */proc/mounts*.
- Returns ``None`` if the file system is not mounted, a list of mount points
- otherwise. Raises a test error if */proc/mounts* cannot be accessed.
-
-read_linewise
- Similar to run_cmd_with_pipe but allows processing of output line-by-line
- as it becomes available. This may be necessary when the underlying binary
- creates lots of output that cannot be buffered until the process finishes.
- Example::
-
- import re
- import sysmisc
- def parse(line):
- if re.match(r'\d', line):
- print('found digits in line!')
- sysmisc.read_linewise('dump_db', parse)
-
-hash_file
- Return a hash of a file.
-
-cheat_reboot
- Replace the reboot binary with a fake one.
-
-cmd_block_till
- Run a command and wait until a condition evaluates to True.
-
-cd
- A context manager that temporarily changes the current working directory
+ * run_cmd_with_pipe
+ Wrapper for the default use case of the cumbersome "subprocess" library.
+ Accepts a list of arguments that describe the command invocation. Returns
+ ``True`` and the contents of ``stdout`` if the pipe returned sucessfully,
+ ``False`` plus ``stderr`` and the exit status otherwise. For example::
+
+ import sysmisc
+ (success, output, _ret) = sysmisc.run_cmd_with_pipe([ "/usr/bin/date", "+%F" ])
+ if success is True:
+ print("Today is %s" % output)
+ else:
+ print("Failed to read date from pipe.")
+
+ * get_mountpoints_by_type
+ Extract mount points for the given file system type from */proc/mounts*.
+ Returns ``None`` if the file system is not mounted, a list of mount points
+ otherwise. Raises a test error if */proc/mounts* cannot be accessed.
+
+ * read_linewise
+ Similar to run_cmd_with_pipe but allows processing of output line-by-line
+ as it becomes available. This may be necessary when the underlying binary
+ creates lots of output that cannot be buffered until the process finishes.
+ Example::
+
+ import re
+ import sysmisc
+ def parse(line):
+ if re.match(r'\d', line):
+ print('found digits in line!')
+ sysmisc.read_linewise('dump_db', parse)
+
+ * hash_file
+ Return a hash of a file.
+
+ * cheat_reboot
+ Replace the reboot binary with a fake one.
+
+ * cmd_block_till
+ Run a command and wait until a condition evaluates to True.
+
+ * cd
+ A context manager that temporarily changes the current working directory
The logging functions either use the format capability or play
the simple role of providing shorter names.
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import re
: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)
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Utility to customize email and other test data.
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import os
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Functions for improving textual output.
Copyright: 2015 Intra2net AG
-
-CONTENTS
-------------------------------------------------------
This module has two parts. Part 1 includes:
- head_and_tail: shows the first few and last few elements of an iterable that
could potentially be pretty long
.. seealso:: http://stackoverflow.com/questions/287871/print-in-terminal-with-colors-using-python
.. seealso:: https://en.wikipedia.org/wiki/ANSI_escape_code
.. seealso:: :py:mod:`textwrap`
-
-
-INTERFACE
-------------------------------------------------------
"""
from builtins import print as _builtin_print
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
-V4_addr_range class
+V4_addr_range class.
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
default_addr_lo = 42
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>
"""
-
-SUMMARY
-------------------------------------------------------
Utility for HTTP based interaction with the arnied web page.
Copyright: Intra2net AG
-
-
-INTERFACE
-------------------------------------------------------
-
"""
import re
git://developer.intra2net.com / pyi2ncommon / commitdiff