Helpers

Helpers or helper function are common functions used throughout the project.

Addon Manager

Use this module as addon manager.

matrixctl.addon_manager.import_addons_from(addon_directory, addon_module, parser_name)[source]

Import addons in (global) addons.

Parameters

addon_directorystr: The absolute path as string to the addon directory.
addon_modulestr: The import path (with dots . not slashes /) to the addons from project root e.g. “matrixctl.addons”.
parser_namestr: The name of the module the subparser is in.
..Note:: The nothing will be imported, when the subparser is not in (global) addons. To add the subparse to addons you need to decorate the subparsers with matrixctl.addon_manager.subparser

Returns

noneNone: The function always returns None.
:rtype:pyNone

matrixctl.addon_manager.setup(func)[source]

Add subparsers to the (main) parser.

Parameters

funcmatrixctl.addon_manager.ParserSetupType: A callback to the main parser.

Returns

parserargparse.ArgumentParser: The parser which includes all subparsers.
:rtype:pyArgumentParser

matrixctl.addon_manager.subparser(func)[source]

Decorate subparsers with, to add them to (global) addons on import.

Parameters

funcmatrixctl.addon_manager.SubParserType: A subparser.
..Note:: The nothing will be imported, when the subparser is not in (global) addons. To add the subparse to addons you need to decorate the subparsers with matrixctl.addon_manager.subparser

Returns

decorated_funcmatrixctl.addon_manager.SubParserType: The same subparser which was used as argument. (Without any changes)
:rtype:pyCallable[[_SubParsersAction], None]

Package Version

Get the packages version.

The package’s version is determined by first checking if a pyproject.toml``exists. If this is given, the version variable is searched line by line in the file using a regular expression. When a match occurs, the version is returned. If the ``pyproject.toml does not exist, e.g. because the package was installed, it uses the version stored in the package’s metadata. In any case, if the version could not be determined, it will return None.

matrixctl.package_version.get_version(name, file)[source]

Get the version of a Python package.

Parameters

namestr: The packages __name__.
filestr: The __name__ of __init__.py

Returns

versionstr or None: The package version, if the package is installed and the version of it is stored in the packages metadata.

rtype: str | None ..

Examples

# file: __init__.py

from .package_version import get_version

 __version__: str | None = get_version(__name__, __file__)

 # or
 __version__: str = get_version(__name__, __file__) or "Unknown"

 # Optional:
 if __version__ is None:
     raise ValueError("Could not find the version of the package.")

# file: conf.py (sphinx)

import sys

sys.path.insert(0, os.path.abspath("../"))
sys.path.insert(0, os.path.abspath("../.."))

from matrixctl.package_version import get_version

__version__: str = (
    get_version("matrixctl", Path(__file__).parent) or "Unknown"
)

Print

Use the functions of this module as printing helpers.

matrixctl.print_helpers.human_readable_bool(b)[source]

Use this helper function to get a “yes” or “no” string from a “bool”.

Parameters

bany: The value to “convert”.

Returns

answerstr: "Yes" if expression is True, or "False" if expression is False.
:rtype:pystr

matrixctl.print_helpers.timestamp_to_dt(ts, sep=' ')[source]

Convert a timestamp (in ms) to a datetime string.

Parameters

tsstr: The value to “convert”.
sepstr: The seperator between the date and the time.

Returns

dtstr: A datetime string (e.g. 2021-08-21 04:55:55)
:rtype:pystr

Password

Use the functions of this module as helpers for passwords.

matrixctl.password_helpers.ask_password()[source]

Ask the user to create a password.

The user will be asked twice for a password. After that the function compares the two entered passwords. If they are the same, and not empty, the function will return the password.

Parameters

None

Returns

passwordstr: The user entered password.

rtype: str | NoReturn ..

matrixctl.password_helpers.ask_question(question='Is everything correct?')[source]

Asks the user a simple yes/no a question.

Parameters

questionstr: The yes/no question the user should be asked

Returns

answerbool: True if the answer was y / j, or False if the answer was n
:rtype:pybool

Notes

The user entered value is case-insensitive.
If the user answered with an invalid answer (not y / j / n) the function asks again.

matrixctl.password_helpers.create_user(user, admin=None)[source]

Ask the user to create a password.

The user will be asked twice for a password. After that the function compares the two entered passwords. If they are the same, and not empty, the function will ask the user if the data is correct without disclosing the password.

Parameters

userstr: The username.
adminbool or none, default is None: True, if the user will be an admin, False, if the user will not have eleveted permissions. None, if the admin permissions are not an criteria. The field will be omitted in the data.

Returns

passwordstr: The user entered password.

rtype: str | NoReturn ..