Helpers

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

Command

Use this module to dynamically create a commands structure.

class matrixctl.command.SubCommand(*values)

Bases: Enum

Use to enumerate possible subcommands for the command-line interface.

Each member represents a distinct subcommand that can be invoked by the user.

MEDIA = 3

MOD = 5

ROOM = 1

SELF = 6

SERVER = 4

USER = 2

static generate_commands()

Generate a dictionary of subcommands with empty lists.

Return type:

dict[SubCommand, list[Callable[[_SubParsersAction, ArgumentParser], None]]]

get_help()

Get a help string for the subcommand.

Return type:

str

matrixctl.command.create_error_handler(parser)

Create a custom error handler for each subparser to display its help.

Creates a custom error handler for an argparse subparser that prints the parser’s help message and exits with status code 2 when called.

Return type:

Callable[[str], None]

Parameters:

parserargparse.ArgumentParser

The subparser to handle errors for.

Returns:

handlerCallable[[str], None]

The error handler function.

matrixctl.command.import_commands_from(addon_directory, addon_module, parser_name)

Import commands in (global) commands.

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 commands from project root e.g. “matrixctl.commands”.

parser_namestr

The name of the module the subparser is in.

..Note:

The nothing will be imported, when the subparser is not in (global) commands. To add the subparse to commands you need to decorate the subparsers with matrixctl.addon_manager.subparser

Returns:

noneNone

The function always returns None.

matrixctl.command.setup(func)

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.command.subparser(subcommand)

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

Return type:

Callable[[Callable[[_SubParsersAction, ArgumentParser], None]], Callable[[_SubParsersAction, ArgumentParser], None]]

Parameters:

fnmatrixctl.addon_manager.SubParserType

The supparser to be wrapped.

subcommandmatrixctl.addon_manager.SubCommand

The subcommand (or category) to which the subparser belongs.

..Note:

Nothing will be imported, when the subparser is not in (global) commands. To add the subparse to commands 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)

Get the version of a Python package.

Return type:

str | None

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.EventType(*values)

Bases: Enum

Use this enum for describing message types.

Supported events:

message_type	Usage
m.room.message	This event to send messages to 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 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.reaction	This event is a reaction to another event
m.room.encrypted	This event is used for encrypted messages
m.room.history_visibility	This event sets the history visibility
m.room.guest_access	This event sets the guest access

M_REACTION = 'm.reaction'

M_ROOM_AVATAR = 'm.room.avatar'

M_ROOM_CREATE = 'm.room.create'

M_ROOM_ENCRYPTED = 'm.room.encrypted'

M_ROOM_GUEST_ACCESS = 'm.room.guest_access'

M_ROOM_HISTORY_VISIBILITY = 'm.room.history_visibility'

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'

static from_string(s)

Convert a string to a MessageType.

Return type:

EventType

Parameters:

sstr

The string to convert to a MessageType.

Returns:

message_typeMessageType

The MessageType object.

matrixctl.sanitizers.sanitize(pattern, identifier, error_message, fn_alias=None)

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

fn_aliastyping.Callable, optional

A function that can be used to convert an alias to an identifier

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, _=None)

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_event_type(event_type, _=None)

Sanitize an event type.

Return type:

Union[EventType, Literal[False], None]

Parameters:

event_typetyping.Any

The event identifier to sanitize

Returns:

event_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_event_type("m.room.message")
<EventType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_event_type("M.RooM.MeSsAgE")
<EventType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_event_type(" m.room.message   ")
<EventType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_event_type(EventType.M_ROOM_MESSAGE)
<EventType.M_ROOM_MESSAGE: 'm.room.message'>

>>> sanitize_event_type("something invalid")
False

>>> sanitize_event_type(None)

matrixctl.sanitizers.sanitize_mxc(uri, _=None)

Sanitize an room identifier.

Return type:

Union[str, Literal[False], None]

Parameters:

mxctyping.Any

The media URI to sanitize

Returns:

mxc_sanitizedtyping.Literal[False] or str, optional

The function returns None if mxc is None, the sanitized string, when it is valid, otherwise False

Examples

>>> sanitize_mxc("mxc://matrix.org/asdfDfjskksjdiIlakjidjLAjdj")
'mxc://matrix.org/asdfDfjskksjdiIlakjidjLAjdj'

>>> sanitize_mxc(" mxc://matrix.org/asdfDfjskksjdiIlakjidjLAjdj ")
'mxc://matrix.org/asdfDfjskksjdiIlakjidjLAjdj'

>>> sanitize_mxc("something invalid")
False

>>> sanitize_mxc(None)

matrixctl.sanitizers.sanitize_room_identifier(room_identifier_or_alias, fn_alias=None)

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_sequence(sanitizer, args, fn_alias=None)

Run a sanitizer against a sequence.

Return type:

Union[tuple[TypeVar(T), ...], Literal[False], None]

matrixctl.sanitizers.sanitize_user_identifier(user_identifier, _=None)

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)

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.render_image_from_mxc(uri, width, height, yaml)

Render an image from a mxc:// URI in the terminal.

Return type:

bytes | None

matrixctl.print_helpers.timestamp_to_dt(ts, sep=' ')

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

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:

str

Parameters:

None

Returns:

passwordstr

The user entered password.

matrixctl.password_helpers.ask_question(question='Is everything correct?')

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)

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:

str

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.