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.0.tar.gz (255.5 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.0-py3-none-any.whl (280.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: matrx_utils-2.0.0.tar.gz
  • Upload date:
  • Size: 255.5 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.0.tar.gz
Algorithm Hash digest
SHA256 895bfdc437e70950895bf1ea09c4c65956eba9921f2733ae7d60f8cc7bc70ef3
MD5 829c2a3e351d37243b1312ad6e969ab2
BLAKE2b-256 6812a57453dcb4cd42a2e2b4eaeb58404cfa0adec15e8cb1e4067ef35c8fd503

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_utils-2.0.0.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.0-py3-none-any.whl.

File metadata

  • Download URL: matrx_utils-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 280.6 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.0-py3-none-any.whl
Algorithm Hash digest
SHA256 52330759cd9172f651711df0f182fbe8d54701c8a3e1fa6fc64fc45fb5e620d8
MD5 f2770be07b927f0b375e669d1ecff0c4
BLAKE2b-256 810c1df326094f824f95e2b174ce7de4747d5e05534f127f505f7013b455c093

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_utils-2.0.0-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

2.0.1

2 files

This release

2.0.0 This release

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