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.

Return type:

None

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.

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

Add subparsers to the (main) parser.

Return type:

ArgumentParser

Parameters:

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

Returns:

parserargparse.ArgumentParser: The parser which includes all subparsers.

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

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

Return type:

Callable[[_SubParsersAction], None]

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)

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.

Return type:

Optional[str]

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.

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"
)

Sanitizers

Use the functions of this module as printing helpers.

class matrixctl.sanitizers.MessageType(value)[source]

Bases: Enum

Use this enum for describing message types.

Supported events:

message_type	Usage
m.room.message	This event is used when sending messages in a room
m.room.name	This event sets the name of an room
m.room.topic	This events sets the room topic
m.room.avatar	This event sets the room avatar
m.room.pinned_events	This event pins events
m.room.member	Adjusts the membership state for a user in a room
m.room.join_rules	This event sets the join rules
m.room.create	This event creates a room
m.room.power_levels	This event sets a rooms power levels
m.room.redaction	This event redacts other events

M_ROOM_AVATAR = 'm.room.avatar'

M_ROOM_CREATE = 'm.room.create'

M_ROOM_JOIN_RULES = 'm.room.join_rules'

M_ROOM_MEMBER = 'm.room.member'

M_ROOM_MESSAGE = 'm.room.message'

M_ROOM_NAME = 'm.room.name'

M_ROOM_PINNED_EVENTS = 'm.room.pinned_events'

M_ROOM_POWER_LEVELS = 'm.room.power_levels'

M_ROOM_REDACTION = 'm.room.redaction'

M_ROOM_TOPIC = 'm.room.topic'

matrixctl.sanitizers.sanitize(pattern, identifier, error_message)[source]

Create a new sanitizer based on compiled RegEx expressions.

A helper function for simplifying the latter sanitize identifier specific functions.

Return type:

Union[str, Literal[False], None]

Parameters:

patterntyping.Pattern: The RegEx pattern used for the specific sanitizing
identifiertyping.Any, optional: The identifier to sanitize based on the pattern
error_messagestr: The error string used for logging errors

Returns:

resulttyping.Literal[False] or str, optional: The function returns None if identifier is None, the sanitized string, when it is valid, otherwise False

matrixctl.sanitizers.sanitize_event_identifier(event_identifier)[source]

Sanitize an event identifier.

Return type:

Union[str, Literal[False], None]

Parameters:

event_identifiertypeing.Any: The event identifier to sanitize

Returns:

resulttyping.Literal[False] or str, optional: The function returns None if event_identifier is None, the sanitized string, when it is valid, otherwise False

Examples

>>> sanitize_event_identifier(
...    "$event-abcdefghijklmH4omLrEumu7Pd01Qp-LySpK_Y"
... )
'$event-abcdefghijklmH4omLrEumu7Pd01Qp-LySpK_Y'

>>> sanitize_event_identifier(
...    " $event-abcdefghijklmH4omLrEumu7Pd01Qp-LySpK_Y "
... )
'$event-abcdefghijklmH4omLrEumu7Pd01Qp-LySpK_Y'

>>> sanitize_event_identifier("something invalid")
False

>>> sanitize_event_identifier(None)

matrixctl.sanitizers.sanitize_message_type(message_type)[source]

Sanitize an message type.

Return type:

Union[MessageType, Literal[False], None]

Parameters:

message_typetyping.Any: The event identifier to sanitize

Returns:

message_type_sanitizedtyping.Literal[False] or MessageType, optional: The function returns None if message_type is None, MessageType, if it is valid, otherwise False

Examples

>>> sanitize_message_type("m.room.message")
<MessageType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_message_type("M.RooM.MeSsAgE")
<MessageType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_message_type(" m.room.message   ")
<MessageType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_message_type(MessageType.M_ROOM_MESSAGE)
<MessageType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_message_type("something invalid")
False

>>> sanitize_message_type(None)

matrixctl.sanitizers.sanitize_room_identifier(room_identifier)[source]

Sanitize an room identifier.

Return type:

Union[str, Literal[False], None]

Parameters:

room_identifiertyping.Any: The room identifier to sanitize

Returns:

room_identifier_sanitizedtyping.Literal[False] or str, optional: The function returns None if room_identifier is None, the sanitized string, when it is valid, otherwise False

Examples

>>> sanitize_room_identifier(
...    "!room:domain.tld"
... )
'!room:domain.tld'

>>> sanitize_room_identifier(
...    " !room:domain.tld "
... )
'!room:domain.tld'

>>> sanitize_room_identifier("something invalid")
False

>>> sanitize_room_identifier(None)

matrixctl.sanitizers.sanitize_user_identifier(user_identifier)[source]

Sanitize an user identifier.

Return type:

Union[str, Literal[False], None]

Parameters:

user_identifiertyping.Any: The user identifier to sanitize

Returns:

event_identifier_sanitizedtyping.Literal[False] or str, optional: The function returns None if user_identifier is None, the sanitized string, when it is valid, otherwise False

Examples

>>> sanitize_user_identifier(
...    "@user:domain.tld"
... )
'@user:domain.tld'

>>> sanitize_user_identifier(
...    " @user:domain.tld "
... )
'@user:domain.tld'

>>> sanitize_user_identifier("something invalid")
False

>>> sanitize_user_identifier(None)

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”.

Return type:

str

Parameters:

bany: The value to “convert”.

Returns:

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

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

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

Return type:

str

Parameters:

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

Returns:

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

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.

Return type:

Union[str, NoReturn]

Parameters:

None

Returns:

passwordstr: The user entered password.

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

Asks the user a simple yes/no a question.

Return type:

bool

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

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.

Return type:

Union[str, NoReturn]

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.