matrx-utils

Foundation utilities for the Matrx ecosystem — cloud file handling (AWS S3, Supabase Storage, local/server filesystems), a pluggable settings + request-context layer, and a set of developer helpers (fancy printing, data transforms, field-processing, code analysis).

matrx-utils is the bottom of the Matrx dependency graph. It has no sibling dependencies. Everything else (matrx-connect, matrx-orm, matrx-graph, matrx-scraper, matrx-ai) depends on it, directly or transitively.

Install

pip install matrx-utils

Python 3.13+ required.

What's in the box

Module What it does
matrx_utils.conf configure_settings(obj) + a lazy settings proxy that falls back to env vars
matrx_utils.ctx UserContext protocol, SimpleUserContext, configure_context(getter), get_active_context()
matrx_utils.fancy_prints vcprint, vclist, print_link, MatrixPrintLog, to_matrx_json
matrx_utils.data_handling DataTransformer, URL and value validators
matrx_files FileManager, FileHandler, BatchHandler, open_any_file
matrx_files.cloud_sync S3Backend, SupabaseBackend, ServerBackend, CloudSyncConfig, SyncEngine + permissions and versioning
matrx_utils.field_processing camel_to_snake, process_field_definitions, generate_complete_code
matrx_utils.code_context, matrx_utils.package_analysis, matrx_utils.react_analysis Developer utilities for scanning codebases

Usage — standalone

Out of the box, matrx-utils reads its configuration from environment variables via a lazy settings proxy, and returns a minimal SimpleUserContext when no request context is available:

from matrx_utils import vcprint, settings
from matrx_files.cloud_sync import SupabaseBackend

vcprint("hello")
vcprint(settings.SUPABASE_URL)           # read from env
backend = SupabaseBackend()              # credentials resolved from settings
backend.write("reports/today.json", b"{}")

Usage — inside a host application

A parent app (like aidream) can inject its own settings object and request-context resolver so every downstream helper picks up the right user/project/emitter automatically:

from matrx_utils import configure_settings, configure_context
from matrx_connect import try_get_app_context  # optional, only if you use matrx-connect
from myapp.settings import settings

configure_settings(settings)
configure_context(try_get_app_context)

After configure_context(...), any code that calls get_active_context() inside a request will get the caller's UserContext without that code having to accept it as a parameter. This is the "capability-within, injection-without" pattern that the other Matrx packages follow.

Standalone-friendliness

This package is designed to work with zero Matrx siblings present. It references matrx-connect in exactly one place — the PDF handler — and that import is lazy with a dict fallback, so pip install matrx-utils followed by import matrx_utils works in any Python project.

Contributing

See CLAUDE.md for package-specific rules (import rules, configuration pattern, known issues). This package lives in the aidream monorepo at github.com/AI-Matrix-Engine/aidream-current.

License

MIT.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.0.21)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for armanisadeghi from gravatar.com armanisadeghi

Credits

Author/Maintainer: Matrx

License

MIT License (MIT)

Requires

Python >=3.13

Provides Extra

dev-tools image-validation

Tags

data-transformation matrx utilities

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrx_utils-2.0.1.tar.gz (257.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

matrx_utils-2.0.1-py3-none-any.whl (281.8 kB view details)

Uploaded Python 3

File details

Details for the file matrx_utils-2.0.1.tar.gz.

File metadata

  • Download URL: matrx_utils-2.0.1.tar.gz
  • Upload date:
  • Size: 257.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for matrx_utils-2.0.1.tar.gz
Algorithm Hash digest
SHA256 0aff3d29b39c576f080b58b3f493b938612944b0c9666028837e5186bace91bd
MD5 1a30723662b41d8ac53883103466c24a
BLAKE2b-256 acf304e2191401a2f25080d2a3150dfc229d28c9a574cd1c583dd899b495381c

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_utils-2.0.1.tar.gz:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file matrx_utils-2.0.1-py3-none-any.whl.

File metadata

  • Download URL: matrx_utils-2.0.1-py3-none-any.whl
  • Upload date:
  • Size: 281.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for matrx_utils-2.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 6d02340aa174ca8f31240dcf183603f9b5a5357f197f840b4c4db5ed7f036f6f
MD5 0ebb0d784d5ca0f0488aeffd3340c171
BLAKE2b-256 cec8f4dab29ed7e22b4b72064777f13ed5ce42b8a7d7944b6935cf71c9a5add8

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_utils-2.0.1-py3-none-any.whl:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.0.21

2 files

2.0.20

2 files

2.0.19

2 files

2.0.18

2 files

2.0.17

2 files

2.0.16

2 files

2.0.15

2 files

2.0.14

2 files

2.0.13

2 files

2.0.12

2 files

2.0.11

2 files

2.0.10

2 files

2.0.9

2 files

2.0.8

2 files

2.0.7

2 files

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

This release

2.0.1 This release

2 files

2.0.0

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.19

2 files

1.0.18

2 files

1.0.17

2 files

1.0.16

2 files

1.0.14

2 files

1.0.13

2 files

1.0.12

2 files

1.0.11

2 files

1.0.10

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page