Matrix Common

1.3.0 verified Fri May 01 auth: no python

Common utilities shared by Synapse, Sydent, and Sygnal. Provides helpers for version strings, regex patterns, MXC URIs, and more. Current version 1.3.0 supports Python >=3.7. Released as needed by Matrix.org services.

pip install matrix-common

Common errors

error ModuleNotFoundError: No module named 'matrix_common' ↓

cause Package not installed or installed in a different Python environment.

fix

Run 'pip install matrix-common' in the correct environment.

error ImportError: cannot import name 'MXCUri' from 'matrix_common' ↓

cause Trying to import MXCUri from the top-level package instead of matrix_common.url.

fix

Use 'from matrix_common.url import MXCUri'.

error AttributeError: module 'matrix_common' has no attribute 'regex' ↓

cause Trying to access submodule via dot notation (e.g., matrix_common.regex) without importing it first.

fix

Import explicitly: 'from matrix_common.regex import glob_to_regex'.

Warnings

breaking Version 1.2.0 moved to src layout. Imports that relied on direct access to submodules may break if not using the new package structure. ↓

fix Use absolute imports from matrix_common (e.g., from matrix_common.url import MXCUri).

deprecated Python 3.6 support dropped in v1.3.0. Code running on Python 3.6 will fail to install or import. ↓

fix Upgrade to Python 3.7 or later.

gotcha get_version_string now optionally accepts a cwd parameter (since v1.2.0). If calling without cwd, ensure the version file is discoverable from the package root. ↓

fix If using a custom working directory, pass the cwd argument explicitly.

Imports

MXCUri

wrong

from matrix_common import MXCUri

correct

from matrix_common.url import MXCUri

MXCUri is in matrix_common.url, not top-level

glob_to_regex

wrong

from matrix_common import glob_to_regex

correct

from matrix_common.regex import glob_to_regex

glob_to_regex is in matrix_common.regex

get_version_string

wrong

from matrix_common import get_version_string

correct

from matrix_common.versionstring import get_version_string

get_version_string is in matrix_common.versionstring

Quickstart

Basic usage of key utilities

from matrix_common.url import MXCUri
from matrix_common.regex import glob_to_regex
from matrix_common.versionstring import get_version_string

# Parse an MXC URI
uri = MXCUri.from_string("mxc://example.com/abc123")
print(f"Server: {uri.server}, Media ID: {uri.media_id}")

# Convert glob to regex
pattern = glob_to_regex("*.txt")
print(f"Regex: {pattern}")

# Get version string from module
version = get_version_string()
print(f"Version: {version}")