MatrixCtl documentation<a class="headerlink" href="#matrixctl-documentation" title="Permalink to this heading">

Parameters:

treeany: Initial a matrixctl.typehints.Config and partials of it afterwards.
depthint: The depth of the table

Returns:

None

API

Get access to the API of your homeserver.

class matrixctl.handlers.api.RequestBuilder(token, domain, path, scheme='https', subdomain='matrix', api_path='_synapse/admin', api_version='v2', data=None, json=None, content=None, method='GET', params={}, headers={}, concurrent_limit=4, timeout=5.0, success_codes=(200, 201, 202, 203, 204, 205, 206, 207, 226))[source]

Bases: object

Build the URL for an API request.

api_path: str

api_version: str

concurrent_limit: int

content: Union[str, bytes, Iterable[bytes], None]

data: Optional[dict[str, Any]]

domain: str

headers: dict[str, str]

property headers_with_auth: dict[str, str]

Get the headers with bearer token.

Parameters:

None

Returns:

headersdict [str, str]: Headers with auth. token.

json: Optional[dict[str, Any]]

method: str

params: dict[str, Union[str, int]]

path: str

scheme: str

subdomain: str

success_codes: tuple[int, ...]

timeout: float

token: str

class matrixctl.handlers.api.RequestStrategy(limit: int, step_size: int, concurrent_limit: int, offset: int, iterations: int)[source]

Bases: NamedTuple

Use this NamedTuple as request strategy data.

This NamedTuple is only used in this module.

concurrent_limit: int: Alias for field number 2

iterations: int: Alias for field number 4

limit: int: Alias for field number 0

offset: int: Alias for field number 3

step_size: int: Alias for field number 1

async matrixctl.handlers.api.async_worker(input_queue, output_queue)[source]

Use this coro as worker to make (a)synchronous request.

Return type:

Returns:

None

See also

RequestBuilder: matrixctl.handlers.api.RequestBuilder

Attributes:

input_queueasyncio.Queue: The input queue, which provides the RequestBuilder.
output_queueasyncio.Queue: The output queue, which gets the responses of there requests.

async matrixctl.handlers.api.exec_async_request(request_config)[source]

Use this coro to generate and run workers and group the responses.

Return type:

Response | list[Response]

Returns:

responseslist of httpx.Response or httpx.Response: Depending on concurrent_limit an request_config.

See also

RequestBuilder: matrixctl.handlers.api.RequestBuilder

Attributes:

request_configRequestBuilder or Generator [RequestBuilder, None, None]: An instance of an RequestBuilder or a list of RequestBuilder. If the function gets a RequestBuilder, the request will be synchronous. If it gets a Generator, the request will be asynchronous.
concurrent_limitint: The maximum of concurrent workers. (This information must be pulled from the config.)

matrixctl.handlers.api.generate_worker_configs(request_config, next_token, limit)[source]

Create workers for async requests (minus the already done sync request).

Return type:

Generator[RequestBuilder, None, None]

Yields:

request_configmatrixctl.handlers.api.RequestBuilder: Yields a fully configured RequestsBuilder for every request that has to be done to get all entries.

Notes

Warning Call-By-Reference like behavior! The param limit and the concurrent_limit in request_config will get changed in this function. Make sure to only use them after using this function!

Attributes:

request_configmatrixctl.handlers.api.RequestBuilder: An instance of an RequestBuilder from which was used for an initial synchronous request to get the first part of the data and the other two arguments from the response.
next_tokenint: The value, which defines from where to start in the next request. You get this value from the response of an initial synchronous request.
totalint: The value which defines how many entries there are. You get this value from the response of an initial synchronous request.

async matrixctl.handlers.api.group_async_results(input_size, output_queue)[source]

Use this coro to group the requests afterwards in a single list.

Return type:

list[Exception | Response]

Returns:

responseslist of httpx.Response or httpx.Response: Depending on concurrent, it is a httpx.Response if concurrent is true, otherwise it is a list of httpx.Response.

Attributes:

input_sizeint: The number of items in the queue.
output_queueasyncio.Queue: The output queue, which holds the responses of there requests.
concurrentbool: When True, make requests concurrently. When False, make requests synchronously.

matrixctl.handlers.api.preplan_request_strategy(limit, concurrent_limit, max_step_size=100)[source]

Use this functiona as helper for optimizing asynchronous requests.

Return type:

RequestStrategy

Returns:

RequestStrategymatrixctl.handlers.api.RequestStrategy: A Named tuple with the RequestStrategy values.

Attributes:

limitint: A user entered limit or total.
concurrent_limit: int: The concurrent limit from the config file.
max_step_sizeint, default=100: The maximal step size, which is a soft limit. It is usually 100, but that value might be different. Check out the API documentation. We usually take the default one.

matrixctl.handlers.api.request(request_config)[source]

Make a (a)synchronous request to the synapse API and receive a response.

Return type:

list[Response] | Response

Returns:

responsehttpx.Response: Returns the response

See also

RequestBuilder: matrixctl.handlers.api.RequestBuilder

Attributes:

request_configRequestBuilder or Generator [RequestBuilder, None, None]: An instance of an RequestBuilder or a list of RequestBuilder. If the function gets a RequestBuilder, the request will be synchronous. If it gets a Generator, the request will be asynchronous.
concurrent_limitint: The maximum of concurrent workers. (This information must be pulled from the config.)

Ansible

Run a ansible playbook with this module.

matrixctl.handlers.ansible.ansible_run(playbook, tags=None, extra_vars=None)[source]

Run an ansible playbook.

Return type:

Parameters:

playbookpathlib.Path: The path to the ansible Playbook
tagsstr, optional: The tags to use
extra_varsdict [str, str], optional: The extra_vars to use.

Returns:

None

Git (VCS)

Update and manage the synapse playbook repository with this module.

class matrixctl.handlers.vcs.VCS(path)[source]

Bases: object

Update and manage a repository.

property datetime_last_pulled_commit: datetime

Get the datetime the commit was pulled last from git.

This is used to determine which messages will be produced in the table.

Parameters:

None

Returns:

datetimedatetime.datetime: The datetime object.

log(since=None)[source]

Print a table of date, user and commit message since the last pull.

Return type:

Parameters:

sincedatetime.datetime, optional, default=None: The datetime the last commit was puled.

Returns:

None

pull()[source]

Git pull the latest commits from GH.

Return type:

Parameters:

None

Returns:

None

SSH

Run and evaluate commands on the host machine of your synapse server.

class matrixctl.handlers.ssh.SSH(address, user=None, port=22)[source]

Bases: object

Run and evaluate commands on the host machine of your synapse server.

address: str

port: int

run_cmd(cmd)[source]

Run a command on the host machine and receive a response.

Return type:

SSHResponse

Parameters:

cmdstr: The command to run.
ttybool: Request a pseudo-terminal from the server (default: False)

Returns:

responsematrixctl.handlers.ssh.SSHResponse: Receive stdin, stdout and stderr as response.

user: str

class matrixctl.handlers.ssh.SSHResponse(stdin: str | None, stdout: str | None, stderr: str | None)[source]

Bases: NamedTuple

Store the response of a SSH command as response.

stderr: Optional[str]: Alias for field number 2

stdin: Optional[str]: Alias for field number 0

stdout: Optional[str]: Alias for field number 1

Table

Use this handler to generate and print tables.

matrixctl.handlers.table.cells_to_str(part, none)[source]

Convert all cells to strings and format None values.

Return type:

list[list[str]]

Parameters:

partcollections.abc.Sequence of collections.abc.Sequence of str: Data or header, in which every cell will be to casted to to strings.
nonestr: A string, which is used to replace None with the specific string.

Returns:

partlist of list of str
The part, where every cell is of type str.

matrixctl.handlers.table.find_newlines(data)[source]

Find newlines and return a dict with positions (key) and occurrences.

Return type:

dict[int, int]

Parameters:

datalist of str: Data or headers of the table.

Returns:

posdict [int, int]: A dictionary {r: n}, where n are newlines in row r.

Notes

The function only adds an entry to the dict, if there is at least one newline in a row.

matrixctl.handlers.table.format_table_row(line, max_column_len)[source]

Format a table row into a str.

Return type:

str

Parameters:

linelist of str: A data or headers row, which will be formatted to a string.
max_column_lentuple of int: A n-tuple which describes the longest string per column. (n is the number of columns)

Returns:

row_stringstr: A formatted string, which represents a table row.

matrixctl.handlers.table.get_colum_length(data, headers)[source]

Transpose rows and find longest line.

Return type:

tuple[int, ...]

Parameters:

datalist of list of str: The data part of the table.
headersNone or list of list of str: The headers part of the table.

Returns:

column_length_tupletuple of int: A n-tuple which describes the longest string per column. (n is the number of columns)

matrixctl.handlers.table.handle_newlines(part, newlines)[source]

Update and insert new lines.

Return type:

tuple[list[list[str]], set[int]]

Parameters:

partlist of list of str: Data or headers of the table.
newlinesdict [int, int]: A dictionary {r: n}, where n are newlines in row r.

Returns:

partlist of list of str: The part contains the supplemented and updated rows.
inhibit_sepset of int: The inhibit_sep set contains the line numbers where a separator yhould be inhibited because the lines handled by this function are belonging together.

matrixctl.handlers.table.newlines_in_row(row)[source]

Get the highest number of newlines per row.

The highest number of newlines for a row is used to determine in how many rows the row gets expanded, to get one row per newline - 1.

Return type:

Parameters:

rowlist of str: Data or headers of the table.

Returns:

max_newlinesint: The highest number of newlines ber row.

matrixctl.handlers.table.table(table_data, table_headers=None, sep=True, none='-')[source]

Create a table from data and a optional headers.

Return type:

Parameters:

table_datacollections.abc.Sequence of collections.abc.Sequence of str: Data.
table_headerscollections.abc.Sequence of str, Optional: Headers.
sepbool, default = True: True, when there should be a separator between every row of data.
nonestr, default = “-”: A string, which is used to replace None with the specific string.

Yields:

tablestr: The table (row for row).

matrixctl.handlers.table.transpose_newlines_to_rows(split, occurrences)[source]

Transpose newlines in new rows.

Return type:

Generator[list[str], None, None]

Parameters:

splitlist of list of str: A list of substring-lists, split from one row, which contains newline characters. The substing-lists are containing strings, which have been split into substings.
occurrencesint: The maximal number of newlines across the row.

Yields:

rowlist of str: A row for each occurrence.

Database

Talk to the the database.

class matrixctl.handlers.db.DBConnectionBuilder(host: str, database: str, username: str, password: str, port: int = 5432, timeout: int = 10, scheme: str = 'postgresql')[source]

Bases: NamedTuple

Build the URL for an API request.

database: str: Alias for field number 1

host: str: Alias for field number 0

password: str: Alias for field number 3

port: int: Alias for field number 4

scheme: str: Alias for field number 6

timeout: int: Alias for field number 5

username: str: Alias for field number 2

matrixctl.handlers.db.db_connect(yaml)[source]

Connect to a PostgreSQL database.

Return type:

Iterator[Connection]

Parameters:

yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Yields:

connpsycopg.Connection: A new Connection instance.

matrixctl.handlers.db.ssh_tunnel(host, username, remote_port, enabled=True, port=22)[source]

Create an SSH tunnel.

Return type:

Iterator[Optional[int]]

Parameters:

hoststr: The remote host e.g. 127.0.0.1 or host.domain.tld.
usernamestr: The username of the user.
remote_portint: The port of the application, which should be tunneled.
enabledbool, default: True: True if the tunnel should be enabled or False if not.
portint, default: 22: The ssh port
private_keyPath or str, optioal: The path to the private key (Currently Disabled)

Yields:

tunint: The remote port
NoneNone: Yields none, when the tunnel is disabled (enabled = False).

Notes

The tunnel will only be created, when it is enabled. If the tunnel is disabled (enabled = False), the function will yield None instead of the local bind port.

Examples

with ssh_tunnel("127.0.0.1", myuser, 5432) as remote_port:
    print(f"The local bind port is: {local_bind_port}")
# The local bind port is: 8765

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:

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.

Type Hints, Structures and Errors

MatrixCtl is strictly typed to avoid some bugs and help contributors in the future to easily identify what they are dealing with. They can be used by third party tools such as type checkers, IDEs, linters, etc.

In addition we make use of TypedDict to create typed structures (add type hints to e.g. the configuration).

MatrixCtl specifies some additional errors. Those errors are informing the user that, getting a traceback is a bug in this application. They are giving the person instructions, how to hand in a bug report.

Type Hints

Use this module for custom type definitions.

Structures

Use this module for structures.

class matrixctl.structures.Config[source]

Bases: TypedDict

Cast the YAML config to a typed dict.

server: ConfigServer

servers: dict[str, ConfigServer]

class matrixctl.structures.ConfigServer[source]

Bases: TypedDict

Add a server to the YAML config structure.

ansible: ConfigServerAnsible

api: ConfigServerAPI

maintenance: ConfigServerMaintenance

ssh: ConfigServerSSH

synapse: ConfigServerSynapse

class matrixctl.structures.ConfigServerAPI[source]

Bases: TypedDict

Add api to server in the YAML config structure.

concurrent_limit: int

domain: str

token: str

username: str

class matrixctl.structures.ConfigServerAnsible[source]

Bases: TypedDict

Add ansible to server in the YAML config structure.

playbook: str

class matrixctl.structures.ConfigServerMaintenance[source]

Bases: TypedDict

Add maintenance to server in the YAML config structure.

tasks: list[str]

class matrixctl.structures.ConfigServerSSH[source]

Bases: TypedDict

Add ssh to server in the YAML config structure.

address: str

port: int

user: str

class matrixctl.structures.ConfigServerSynapse[source]

Bases: TypedDict

Add synapse to server in the YAML config structure.

playbook: str

Errors

Use the exceptions of this module for the application.

exception matrixctl.errors.ConfigFileError(message=None, payload=None)[source]

Bases: Error

Use this exception class for everything related to the config file.

exception matrixctl.errors.Error(message=None, payload=None)[source]

Bases: Exception

Use this exception class as base error for the project.

BUGMSG: str = 'If you discover this message, please try updating MatrixCtl. If you see this message again, we would be glad, if you would run the same command again in debug-mode (matrixctl -d [...]) and hand in a "Bug report" at https://github.com/MichaelSasser/matrixctl/issues with the complete output.\n\nPython version: 3.10.8 final\nMatrixCtl version: 0.12.0b2 \n'

exception matrixctl.errors.ExitQWorker[source]

Bases: Exception

Use this exception when you want to exit an Queue worker.

exception matrixctl.errors.InternalResponseError(message=None, payload=None)[source]

Bases: Error

Use this exception class for everything else.

Addons

Addons are the commands listed below, e.g. adduser to create a new user on the homeserver or deploy to deploy the ansible playbook.

adduser

Use this module to add the adduser subcommand to matrixctl.

matrixctl.addons.adduser.parser.subparser_adduser(subparsers)[source]

Create a subparser for the matrixctl adduser command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the adduser subcommand to matrixctl.

matrixctl.addons.adduser.addon.addon(arg, yaml)[source]

Add a User to the synapse instance.

It runs ask_password() first. If ask_password() returns None it generates a password with gen_password(). Then it gives the user a overview of the username, password and if the new user should be generated as admin (if you added the --admin argument). Next, it asks a question, if the entered values are correct with the ask_question function.

If the ask_question function returns True, it continues. If not, it starts from the beginning.

Depending on the --ansible switch it runs the adduser command via ansible or the API

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

deluser

Use this module to add the deluser subcommand to matrixctl.

matrixctl.addons.deluser.parser.subparser_deluser(subparsers)[source]

Create a subparser for the matrixctl deluser command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the deluser subcommand to matrixctl.

matrixctl.addons.deluser.addon.addon(arg, yaml)[source]

Delete a user from the the matrix instance.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

adduser-jitsi

Use this module to add the adduser-jitsi subcommand to matrixctl.

matrixctl.addons.adduser_jitsi.parser.subparser_adduser_jitsi(subparsers)[source]

Create a subparser for the matrixctl adduser-jitsi command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the adduser-jitsi subcommand to matrixctl.

matrixctl.addons.adduser_jitsi.addon.addon(arg, yaml)[source]

Add a User to the jitsi instance.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

deluser-jitsi

Use this module to add a deluser-jitsi subcommand to matrixctl.

matrixctl.addons.deluser_jitsi.parser.subparser_deluser_jitsi(subparsers)[source]

Create a subparser for the matrixctl deluser-jitsi command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add a deluser-jitsi subcommand to matrixctl.

matrixctl.addons.deluser_jitsi.addon.addon(arg, yaml)[source]

Delete a user from the jitsi instance.

It uses the Ssh class from the ssh_handler.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

check

Use this module to add the check subcommand to matrixctl.

matrixctl.addons.check.parser.subparser_check(subparsers)[source]

Create a subparser for the matrixctl check command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the check subcommand to matrixctl.

matrixctl.addons.check.addon.addon(_, yaml)[source]

Check the deployment with andible.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

deploy

Use this module to add the deploy subcommand to matrixctl.

matrixctl.addons.deploy.parser.subparser_deploy(subparsers)[source]

Create a subparser for the matrixctl deploy command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the deploy subcommand to matrixctl.

matrixctl.addons.deploy.addon.addon(arg, yaml)[source]

Deploy the ansible playbook.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

maintenance

Use this module to add the maintenance subcommand to matrixctl.

matrixctl.addons.maintenance.parser.subparser_maintenance(subparsers)[source]

Create a subparser for the matrixctl maintenance command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the maintenance subcommand to matrixctl.

class matrixctl.addons.maintenance.addon.Task(value)[source]

Bases: Enum

Use this enum for describing the maintenance task.

Supported tasks:

tasks	Description
vacuum	Reclaims storage occupied by dead tuples.
compress_state	Compress Synapse State Tables.

COMPRESS_STATE = 'rust-synapse-compress-state'

VACUUM = 'run-postgres-vacuum'

matrixctl.addons.maintenance.addon.addon(arg, yaml)[source]

Run the maintenance procedure of the ansible playbook.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

matrixctl.addons.maintenance.addon.print_tasks()[source]

Print a list of all available tasks.

Return type:: None

start

Use this module to add the (re)start subcommand to matrixctl.

matrixctl.addons.start.parser.subparser_restart(subparsers)[source]

Create a subparser for the matrixctl restart command.

Parameters:

subparsersargparse._SubParsersAction or typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

See also

matrixctl.start.subparser_start: Subparser for matrixctl start.

Notes

This is a alias for matrixctl start

matrixctl.addons.start.parser.subparser_start(subparsers)[source]

Create a subparser for the matrixctl start command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the (re)start subcommand to matrixctl.

matrixctl.addons.start.addon.addon(_, yaml)[source]

Start/Restart the OCI containers.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

stop

Use this module to add the stop subcommand to matrixctl.

matrixctl.addons.stop.parser.subparser_stop(subparsers)[source]

Create a subparser for the matrixctl stop command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the stop subcommand to matrixctl.

matrixctl.addons.stop.addon.addon(_, yaml)[source]

Stop the OCI containers.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

update

Use this module to add the update subcommand to matrixctl.

matrixctl.addons.update.parser.subparser_update(subparsers)[source]

Create a subparser for the matrixctl update command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the update subcommand to matrixctl.

matrixctl.addons.update.addon.addon(_, yaml)[source]

Update the synapse playbook with git.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

user

Use this module to add the user subcommand to matrixctl.

matrixctl.addons.user.parser.subparser_user(subparsers)[source]

Create a subparser for the matrixctl user command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the user subcommand to matrixctl.

matrixctl.addons.user.addon.addon(arg, yaml)[source]

List information about an registered user.

It uses the admin API to get a python dictionary with the information. The generate_user_tables function makes the information human readable.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Examples

$ matrixctl user dwight
User:
+----------------------------+--------------------------------------+
| Name                       | dwight                               |
| Password Hash              | $2b$12$9DUNderm1ffL1NincPap3RC       |
|                            | ompaNY1725.slOUghAvEnu5cranT0n       |
| Guest                      | False                                |
| Admin                      | True                                 |
| Consent Version            |                                      |
| Consent Server Notice Sent |                                      |
| Appservice Id              |                                      |
| Creation Ts                | 2020-04-14 13:04:21                  |
| User Type                  |                                      |
| Deactivated                | False                                |
| Displayname                | Dwight Schrute                       |
| Avatar Url                 | mxc://dunder-mifflin.com/sCr4        |
|                            | nt0nsr4ng13rW45Cr33d                 |
+----------------------------+--------------------------------------+

Threepid:
+--------------+-----------------------------------+
| Medium       | email                             |
| Address      | dwight_schrute@dunder-mifflin.com |
| Validated At | 2020-04-14 15:30:21.123000        |
| Added At     | 2020-04-14 15:29:19.100000        |
+--------------+-----------------------------------+

If the user does not exist, the return looks like:

Use this module to add the rooms subcommand to matrixctl.

matrixctl.addons.user.to_table.generate_user_tables(user_dict, len_domain)[source]

Generate a main user table and threepid user tables.

The function gnerates first a main user table and then for every threepid a additional table from a user_dict. It renames and makes the output human readable.

Return type:

list[list[tuple[str, str]]]

Parameters:

user_dictdict [str, Any]: The line as dict, a JSON string which was converted to a Python dictionary. (This is not a Collections.UserDict)
len_domainint: The length in characters of the domain.

Returns:

err_codeint: A list in the format: [[main], threepids_0, ... ,threepids_n]

Notes

This function is a recursive function.

matrixctl.addons.user.to_table.make_human_readable(k, user_dict, len_domain)[source]

Make a key/value pair of a user (line) human readable, by modifying.

Return type:

tuple[str, str]

Parameters:

kstr: The key
user_dictdict [str, Any]: The line as dict, a JSON string which was converted to a Python dictionary. (This is not a Collections.UserDict)
len_domainint: The length in characters of the domain.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Notes

This function is used as helper by matrixctl.user.generate_user_tables.

matrixctl.addons.user.to_table.to_table(user_dict, len_domain)[source]

Use this function as helper to pint the room table.

Return type:

Parameters:

user_dictmatrixctl.typehints.JsonDict: The user data from the API
len_domainint: The length of the homeservers domain.

Yields:

table_linesstr: The table lines.

users

Use this module to add the users subcommand to matrixctl.

matrixctl.addons.users.parser.subparser_users(subparsers)[source]

Create a subparser for the matrixctl users command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the users subcommand to matrixctl.

matrixctl.addons.users.addon.addon(arg, yaml)[source]

Print a table/json of the matrix users.

This function generates and prints a table of users or uses json as output format.

The table can be modified. :rtype: int

If you want guests in the table use the --with-guests switch.
If you want deactivated user in the table use the --with-deactivated switch.

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Notes

Needs API version 2 (synapse 1.28 or greater) to work.
API version 1 is deprecated. If you encounter problems please upgrade to the latest synapse release.

Use this module to add the rooms subcommand to matrixctl.

matrixctl.addons.users.to_table.to_table(users_list, len_domain)[source]

Use this function as helper to pint the users table.

Return type:

Parameters:

users_listlist of matrixctl.typehints.JsonDict: A list of rooms from the API.
len_domainint: The length of the homeservers domain.

Yields:

table_linesstr: The table lines.

Examples

$ matrixctl users
+---------+-------------+---------------+-------+-------+--------------+
| Name    | Deactivated | Shadow-Banned | Admin | Guest | Display Name |
|---------+-------------+---------------+-------+-------|--------------+
| dwight  | No          | No            | Yes   | No    | Dwight       |
| pam     | No          | No            | No    | No    | Pam          |
| jim     | No          | No            | No    | No    | Jim          |
| creed   | No          | Yes           | No    | No    | Creed        |
| stanley | No          | No            | No    | No    | Stanley      |
| kevin   | No          | No            | No    | No    | Cookie       |
| angela  | No          | No            | No    | No    | Angela       |
| phyllis | No          | No            | No    | No    | Phyllis      |
| tobi    | No          | No            | No    | No    | TobiHR       |
| michael | No          | No            | Yes   | No    | Best Boss    |
| andy    | No          | No            | No    | No    | Andy         |
+---------+-------------+---------------+-------+-------+--------------+

report

Use this module to add the report subcommand to matrixctl.

matrixctl.addons.report.parser.subparser_report(subparsers)[source]

Create a subparser for the matrixctl report command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the users subcommand to matrixctl.

matrixctl.addons.report.addon.addon(arg, yaml)[source]

Print a table of the reported events.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

reports

Use this module to add the reports subcommand to matrixctl.

matrixctl.addons.reports.parser.subparser_reports(subparsers)[source]

Create a subparser for the matrixctl reports command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the reports subcommand to matrixctl.

matrixctl.addons.reports.addon.addon(arg, yaml)[source]

Print a table/json of the reported events.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Use this module to add the rooms subcommand to matrixctl.

matrixctl.addons.reports.to_table.to_table(events_raw)[source]

Use this function as helper to pint the events as table.

Return type:

Parameters:

events_rawlist of matrixctl.typehints.JsonDict: A list of events from the API.

Yields:

table_linesstr: The table lines.

Examples

$ matrixctl reports
+-----------------+----------------------------------------------+
| ID              | 2                                            |
| Date            | 2021-05-08                                   |
| Time            | 21:04:55                                     |
| Score           | -100                                         |
| Canonical Alias | -                                            |
| Room Name       | SomeRoom                                     |
| Room ID         | !AbCdEfGhIjKlMnOpQr:domain.tld               |
| Event ID        | $Q_sksd348jaidj93jf9ojwef9h329ofijewhf932h9f |
| Defendant       | @mallory:matrix.org                          |
| Plaintiff       | @alice:myhomeverver.tld                      |
| Reason          | Likes JavaScript                             |
|-----------------+----------------------------------------------|
| ID              | 1                                            |
| Date            | 2020-08-15                                   |
| Time            | 09:09:57                                     |
| Score           | -100                                         |
| Canonical Alias | -                                            |
| Room Name       | -                                            |
| Room ID         | !AbCdEfGhIjKlMnOpQr:matrix.org               |
| Event ID        | $123456789012345678901:matrix.org            |
| Defendant       | @eve:matrix.org                              |
| Plaintiff       | @bob:myhomeserver.tld                        |
| Reason          | Hates The Office (US)                        |
+-----------------+----------------------------------------------+

rooms

Use this module to add the rooms subcommand to matrixctl.

matrixctl.addons.rooms.parser.subparser_rooms(subparsers)[source]

Create a subparser for the matrixctl rooms command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the rooms subcommand to matrixctl.

matrixctl.addons.rooms.addon.addon(arg, yaml)[source]

Generate a table of the matrix rooms.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

matrixctl.addons.rooms.addon.filter_empty_rooms(rooms, local_users=True)[source]

Filter for empty rooms.

Return type:

list[dict[str, Any]]

Parameters:

roomslist of matrixctl.typehints.JsonDict: A rooms list.
local_usersbool: true: Filter, if no local user is in the room. false: Filter, if no user is in the room.

Returns:

roomslist of matrixctl.typehints.JsonDict: The filtered list.

matrixctl.addons.rooms.addon.generate_output(rooms, to_json)[source]

Use this helper to generate the output.

Return type:

Parameters:

roomslist of matrixctl.typehints.JsonDict: A list of rooms from the API.
to_jsonbool: True, when the output should be in the JSON format. False, when the output should be a table.

Returns:

None

Use this module to add the rooms subcommand to matrixctl.

matrixctl.addons.rooms.to_table.to_table(rooms_list)[source]

Use this function as helper to pint the room table.

Return type:

Parameters:

rooms_listlist of matrixctl.typehints.JsonDict: A list of rooms from the API.

Yields:

table_linesstr: The table lines.

purge-history

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.addons.purge_history.parser.subparser_purge_history(subparsers)[source]

Create a subparser for the matrixctl purge-history command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.addons.purge_history.addon.addon(arg, yaml)[source]

Purge historic message events from the Database.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.addons.purge_history.dialog.dialog_input(arg)[source]

Ask questions and sanitize them.

Return type:

Union[dict[str, str | int], NoReturn]

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().

Returns:

request_bodytyping.Dict [str, str] or NoReturn: Non-zero value indicates error code, or zero on success.

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.addons.purge_history.handler.handle_purge_status(yaml, purge_id)[source]

Check the status of the purge history request.

Return type:

Parameters:

yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.
purge_id: str: The purge id from a purge history request.

Returns:

response: matrixctl.typehints.JsonDict, optional: The response as dict, containing the status.

The purge-history command allows to purge historic events from the database.

Use this module to add the purge-histoy subcommand to matrixctl.

matrixctl.addons.purge_history.timing.check_point_in_time(event_or_timestamp)[source]

Check the the type of the point in time and set the correct body.

Return type:

Optional[dict[str, str | int]]

Parameters:

event_or_timestampstr: The event_id or timestamp (UNIX epoch, in milliseconds).

Returns:

request_body: Dict [str, str or int]: A dict, which can be merged with the request_body dict.

delroom

Use this module to add the delroom subcommand to matrixctl.

matrixctl.addons.delroom.parser.subparser_delroom(subparsers)[source]

Create a subparser for the matrixctl delroom command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the delroom subcommand to matrixctl.

matrixctl.addons.delroom.addon.addon(arg, yaml)[source]

Delete an empty room from the database.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

matrixctl.addons.delroom.addon.handle_arguments(arg)[source]

Build the parameters used for the delroom request.

Return type:

dict[str, Any]

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()

Returns:

bodymatrixctl.typehints.JsonDict: The params.

matrixctl.addons.delroom.addon.handle_status(yaml, delete_id)[source]

Handle the status of a delete room request.

Return type:

dict[str, Any]

Parameters:

yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.
delete_id: str: The delete id of a delete room request.

Returns:

response: matrixctl.typehints.JsonDict, optional: The response as dict, containing the status.

upload

Use this module to add the upload subcommand to matrixctl.

matrixctl.addons.upload.parser.subparser_upload(subparsers)[source]

Create a subparser for the matrixctl upload command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the upload subcommand to matrixctl.

matrixctl.addons.upload.addon.addon(arg, yaml)[source]

Upload a file or image to the matrix instance.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

server-notice

Use this module to add the serve-notice subcommand to matrixctl.

matrixctl.addons.server_notice.parser.subparser_server_notice(subparsers)[source]

Create a subparser for the matrixctl server-notice command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the serve-notice subcommand to matrixctl.

matrixctl.addons.server_notice.addon.addon(arg, yaml)[source]

Send a server notice to a matrix instance.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args().
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Notes

It uses the synapse admin API.
Note that “server notices” must be enabled in homeserver.yaml before this API can be used.

get-event

Use this module to get an event from the Database.

matrixctl.addons.get_event.parser.subparser_get_event(subparsers)[source]

Create a subparser for the matrixctl get-event command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to get an event from the Database.

matrixctl.addons.get_event.addon.addon(arg, yaml)[source]

Get an Event from the Server.

It connects via paramiko to the server and runs the psql command provided by the synapse playbook to run a query on the Database.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

get-events

Use this module to get an events of an user from the Database.

matrixctl.addons.get_events.parser.subparser_get_events(subparsers)[source]

Create a subparser for the matrixctl get-event command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to get an event from the Database.

matrixctl.addons.get_events.addon.addon(arg, yaml)[source]

Get Events from the Server.

It connects via paramiko to the server and runs the psql command provided by the synapse playbook to run a query on the Database.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

joinroom

Use this module to add the joinroom subcommand to matrixctl.

matrixctl.addons.joinroom.parser.subparser_deluser(subparsers)[source]

Create a subparser for the matrixctl joinroom command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the joinroom subcommand to matrixctl.

matrixctl.addons.joinroom.addon.addon(arg, yaml)[source]

Join a user to an room.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Notes

You can only modify the membership of local users.
The the token of server administrator used to authenticate against the homeserver must be in the room and must have permission to invite users.

is-admin

Use this module to add the is-admin subcommand to matrixctl.

matrixctl.addons.is_admin.parser.subparser_is_admin(subparsers)[source]

Create a subparser for the matrixctl is-admin command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to add the is-admin subcommand to matrixctl.

matrixctl.addons.is_admin.addon.addon(arg, yaml)[source]

Delete a user is an admin.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

Notes

If a user does not exist it still will return "admin": false or No.

set-admin

Use this module to add the set-admin subcommand to matrixctl.

matrixctl.addons.set_admin.parser.subparser_set_admin(subparsers)[source]

Create a subparser for the matrixctl set-admin command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to get the number of user in a Matrix room.

matrixctl.addons.set_admin.addon.addon(arg, yaml)[source]

Change whether a user is an admin or not.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

make-room-admin

Add the make-room-admin subcommand to matrixctl.

matrixctl.addons.make_room_admin.parser.subparser_make_room_admin(subparsers)[source]

Create a subparser for the matrixctl make-room-admin command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to grant a user room admin status.

Grant another user the highest power available to a local user who is in the room Matrix room.

matrixctl.addons.make_room_admin.addon.addon(arg, yaml)[source]

Grant a user room admin status.

By default the server admin (the caller) is granted power, but another user can optionally be specified.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

get-event-context

Add the get-event-context subcommand to matrixctl.

matrixctl.addons.get_event_context.parser.subparser_get_event_context(subparsers)[source]

Create a subparser for the matrixctl get-event-context command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to find the context of an event.

matrixctl.addons.get_event_context.addon.addon(arg, yaml)[source]

Find the context of an event.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

purge-remote-media

Add the purge-remote-media subcommand to matrixctl.

matrixctl.addons.purge_remote_media.parser.subparser_purge_remote_media(subparsers)[source]

Create a subparser for the matrixctl purge-remote-media command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to delete remote media.

matrixctl.addons.purge_remote_media.addon.addon(arg, yaml)[source]

Remove remote media.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

matrixctl.addons.purge_remote_media.addon.handle_timestamp(timestamp, force)[source]

Ask or generate timestamp.

Return type:

Parameters:

timestampint, optional: The timestamp
forcebool: Don’t ask any questions. All questions are answered with True.

Returns:

timestampint: The same timestamp but sanitized, or the timestamp of this exact time.

delete-local-media

Add the delete-local_media subcommand to matrixctl.

matrixctl.addons.delete_local_media.parser.subparser_delete_local_media(subparsers)[source]

Create a subparser for the matrixctl delete-local_media command.

Parameters:

subparsersargparse._SubParsersAction of typing.Any: The object which is returned by parser.add_subparsers().

Returns:

None

Use this module to delete local media.

matrixctl.addons.delete_local_media.addon.addon(arg, yaml)[source]

Delete local media.

Return type:

Parameters:

argargparse.Namespace: The Namespace object of argparse’s parse_args()
yamlmatrixctl.handlers.yaml.YAML: The configuration file handler.

Returns:

err_codeint: Non-zero value indicates error code, or zero on success.

matrixctl.addons.delete_local_media.addon.handle_timestamp(timestamp, force)[source]

Ask or generate timestamp.

Return type: