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]

ui: ConfigUi

class matrixctl.structures.ConfigServer[source]

Bases: TypedDict

Add a server to the YAML config structure.

alias: ConfigServerAlias

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.

auth_oidc: ConfigServerAPIAuthOidc

auth_token: ConfigServerAPIAuthToken

auth_type: str

concurrent_limit: int

domain: str

class matrixctl.structures.ConfigServerAPIAuthOidc[source]

Bases: TypedDict

Add auth_oidc to server.api in the YAML config structure.

auth_endpoint: str

claims: Iterable[str]

client_id: str

client_secret: str

discovery_endpoint: str

jwks_uri: str

payload: dict[str, Any]

token_endpoint: str

user_info: dict[str, Any]

userinfo_endpoint: str

class matrixctl.structures.ConfigServerAPIAuthToken[source]

Bases: TypedDict

Add auth_token to server.api in the YAML config structure.

token: str

username: str

class matrixctl.structures.ConfigServerAlias[source]

Bases: TypedDict

Add a alias to server in the YAML config structure.

room: tuple[ConfigServerAliasRoom, ...]

class matrixctl.structures.ConfigServerAliasRoom[source]

Bases: TypedDict

Add a room to server.alias in the YAML config structure.

name: str

room_id: 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

class matrixctl.structures.ConfigUi[source]

Bases: TypedDict

Add Ui to server in the YAML config structure.

image: ConfigUiImage

class matrixctl.structures.ConfigUiImage[source]

Bases: TypedDict

Add image to server in the YAML config structure.

enabled: bool

max_height_of_terminal: float

scale_factor: float

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.13.5 final\nMatrixCtl version: 0.15.2 \n'

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

Bases: Error

Use this exception class for everything else.

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

Bases: Error

The given event data is not valid.

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

Bases: Error

The parser was unable to parse the the given data correctly.

exception matrixctl.errors.QWorkerExit[source]

Bases: Exception

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

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

Bases: Error

Use this exception class for everything that should never happen.