matrx-orm 2.0.2__tar.gz → 2.0.4__tar.gz

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 2.0.2
+Version: 2.0.4
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching. Works with any PostgreSQL database.
 Project-URL: Homepage, https://github.com/armanisadeghi/matrx-orm
 Project-URL: Repository, https://github.com/armanisadeghi/matrx-orm
@@ -31,6 +31,7 @@ Requires-Dist: gitpython>=3.1.40
 Requires-Dist: matrx-utils>=1.0.4
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
+Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
 Requires-Dist: pytest>=9.0; extra == 'dev'

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "2.0.2"
+version = "2.0.4"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching. Works with any PostgreSQL database."
 readme = "README.md"
 license = { text = "MIT" }
@@ -45,6 +45,7 @@ dependencies = [
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
     "matrx-utils>=1.0.4",
+    "pyyaml>=6.0.3",
 ]
 
 [project.optional-dependencies]

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/release.sh

@@ -67,7 +67,7 @@ echo ""
 # ── Update pyproject.toml and amend the commit ─────────────────────────────
 
 info "Updating $PYPROJECT to version $NEW_VERSION..."
-sed -i "s/^version = \"$CURRENT_VERSION\"/version = \"$NEW_VERSION\"/" "$PYPROJECT"
+sed -i '' "s/^version = \"$CURRENT_VERSION\"/version = \"$NEW_VERSION\"/" "$PYPROJECT"
 ok "Version updated in $PYPROJECT"
 
 info "Amending last commit to include version bump..."
@@ -99,6 +99,11 @@ echo -e "${GREEN}  Released matrx-orm $NEW_VERSION${NC}"
 echo -e "${GREEN}  GitHub Actions will now build and publish to PyPI.${NC}"
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""
+echo ""
+echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo -e "  Monitor: ${CYAN}https://github.com/armanisadeghi/matrx-orm/actions${NC}"
-echo -e "  Update:  ${CYAN}uv add matrx-orm@${NEW_VERSION}${NC}"
+echo -e "  Update:  ${CYAN}uv add matrx-orm==${NEW_VERSION}${NC}"
+echo ""
+echo -e "  --> Not Available Yet?   Speed up indexing:  ${CYAN}pip index versions matrx-orm${NC}"
+echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/__init__.py

@@ -1,6 +1,7 @@
 from .core.config import (
     DatabaseProjectConfig,
     register_database,
+    register_database_from_env,
     get_database_config,
     get_connection_string,
     get_manager_config,
@@ -131,6 +132,7 @@ from .migrations import (
 __all__ = [
     "DatabaseProjectConfig",
     "register_database",
+    "register_database_from_env",
     "get_database_config",
     "get_connection_string",
     "get_manager_config",

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/client/postgres_connection.py

@@ -31,8 +31,9 @@ def init_connection_details(config_name):
                 f"Incomplete database configuration for '{config_name}'. " "Please check your environment variables or settings.")
 
         connection_string = f"{db_protocol}://{db_user}:{db_password}@{db_host}:{db_port}/{db_name}"
+        redacted = f"{db_protocol}://{db_user}:****@{db_host}:{db_port}/{db_name}"
 
-        vcprint(f"\n[Matrx ORM] Connection String:\n{connection_string}\n", color="yellow")
+        vcprint(f"\n[Matrx ORM] Connection String:\n{redacted}\n", color="yellow")
 
         connection_pools[config_name] = ConnectionPool(
             connection_string,

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/core/config.py

@@ -161,6 +161,88 @@ def register_database(config: DatabaseProjectConfig) -> None:
     registry.register(config)
 
 
+def register_database_from_env(
+    name: str,
+    env_prefix: str,
+    alias: str = "",
+    additional_schemas: list = None,
+    entity_overrides: Dict = None,
+    field_overrides: Dict = None,
+    manager_config_overrides: Dict = None,
+) -> bool:
+    """
+    Read database connection details from environment variables, validate them,
+    and register the database. Prints colored diagnostics for missing or defaulted vars.
+
+    Required env vars (using env_prefix, e.g. "PRIMARY_DB"):
+        {env_prefix}_HOST, {env_prefix}_PORT, {env_prefix}_NAME,
+        {env_prefix}_USER, {env_prefix}_PASSWORD
+
+    Optional env vars:
+        {env_prefix}_PROTOCOL  — defaults to "postgresql"
+
+    Returns True if registration succeeded, False otherwise.
+    """
+    _REQUIRED = ["HOST", "PORT", "NAME", "USER", "PASSWORD"]
+    _OPTIONAL = {"PROTOCOL": "postgresql"}
+
+    vcprint(f"[matrx-orm] Registering database '{name}'...", color="cyan")
+
+    missing: list[str] = []
+    resolved: dict[str, str] = {}
+
+    for key in _REQUIRED:
+        env_var = f"{env_prefix}_{key}"
+        val = os.environ.get(env_var, "").strip()
+        if val:
+            resolved[key] = val
+        else:
+            missing.append(env_var)
+
+    for key, default in _OPTIONAL.items():
+        env_var = f"{env_prefix}_{key}"
+        val = os.environ.get(env_var, "").strip()
+        if val:
+            resolved[key] = val
+        else:
+            resolved[key] = default
+            vcprint(
+                f"  '{env_var}' not set — using default: '{default}'",
+                color="yellow",
+            )
+
+    if missing:
+        vcprint(
+            f"  Database '{name}' NOT registered — missing required env vars:",
+            color="red",
+        )
+        for var in missing:
+            vcprint(f"    • {var}", color="red")
+        return False
+
+    try:
+        config = DatabaseProjectConfig(
+            name=name,
+            alias=alias or name,
+            host=resolved["HOST"],
+            port=resolved["PORT"],
+            protocol=resolved["PROTOCOL"],
+            database_name=resolved["NAME"],
+            user=resolved["USER"],
+            password=resolved["PASSWORD"],
+            additional_schemas=additional_schemas or [],
+            entity_overrides=entity_overrides or {},
+            field_overrides=field_overrides or {},
+            manager_config_overrides=manager_config_overrides or {},
+        )
+        registry.register(config)
+        vcprint(f"  Database '{name}' registered successfully.", color="green")
+        return True
+    except DatabaseConfigError as e:
+        vcprint(f"  Database '{name}' registration failed: {e}", color="red")
+        return False
+
+
 def get_connection_string(config_name: str) -> str:
     config = get_database_config(config_name)
     connection_string = f"{config['protocol']}://{config['user']}:{redact_string(config['password'])}@{config['host']}:{config['port']}/{config['database_name']}"

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/python_sql/db_objects.py

@@ -1,10 +1,11 @@
 from matrx_orm.client.postgres_connection import execute_sql_query
 from collections import defaultdict
 from matrx_orm.python_sql.table_typescript_relationship import get_ts_object
+from matrx_orm.schema_builder.common import DEBUG_CONFIG
 
-verbose = False
-debug = False
-info = True
+verbose = DEBUG_CONFIG["verbose"]
+debug = DEBUG_CONFIG["debug"]
+info = DEBUG_CONFIG["info"]
 
 
 def get_full_db_objects(schema, database_project):

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/python_sql/table_detailed_relationships.py

@@ -1,9 +1,9 @@
 from matrx_orm.client.postgres_connection import execute_sql_query
+from matrx_orm.schema_builder.common import DEBUG_CONFIG
 
-
-verbose = False
-debug = False
-info = True
+verbose = DEBUG_CONFIG["verbose"]
+debug = DEBUG_CONFIG["debug"]
+info = DEBUG_CONFIG["info"]
 
 
 def get_table_relationships(schema, database_project):

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/python_sql/table_typescript_relationship.py

@@ -4,9 +4,11 @@ from matrx_orm.python_sql.table_detailed_relationships import (
     analyze_relationships,
 )
 
-verbose = False
-debug = False
-info = True
+from matrx_orm.schema_builder.common import DEBUG_CONFIG
+
+verbose = DEBUG_CONFIG["verbose"]
+debug = DEBUG_CONFIG["debug"]
+info = DEBUG_CONFIG["info"]
 
 
 def transform_relationships_for_typescript(relationships_data, junction_analysis):

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/schema_builder/__init__.py

@@ -16,6 +16,9 @@ from matrx_orm.schema_builder.helpers import (
 from matrx_orm.schema_builder.schema_manager import (
     SchemaManager,
 )
+from matrx_orm.schema_builder.runner import (
+    run_schema_generation,
+)
 
 
 __all__ = [
@@ -24,6 +27,7 @@ __all__ = [
     "DEBUG_CONFIG",
     "schema_builder_verbose",
     "SchemaManager",
+    "run_schema_generation",
     "check_git_status",
     "get_schema_structure",
     "generate_dto_and_manager",

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/schema_builder/common.py

@@ -13,14 +13,14 @@ ADMIN_TS_ROOT = os.getenv("ADMIN_TS_ROOT", "")
 
 dt_utils = DataTransformer()
 
-schema_builder_save_direct = True
-
-
+# Central debug configuration for the entire schema builder.
+# Values can be overridden at runtime by run_schema_generation() from the yaml
+# debug section, or by setting env vars MATRX_DEBUG, MATRX_VERBOSE, MATRX_INFO.
 DEBUG_CONFIG = {
     "tables": [],
     "columns": [],
     "base_type": [],
-    "info": True,
-    "debug": False,
-    "verbose": False,
+    "info": os.getenv("MATRX_INFO", "").lower() in ("1", "true"),
+    "debug": os.getenv("MATRX_DEBUG", "").lower() in ("1", "true"),
+    "verbose": os.getenv("MATRX_VERBOSE", "").lower() in ("1", "true"),
 }

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/schema_builder/helpers/__init__.py

@@ -15,11 +15,8 @@ from matrx_orm.schema_builder.helpers.entity_generators import (
     generate_typescript_entity,
 )
 
-from matrx_orm.schema_builder.helpers.git_checker import (
-    ADMIN_PYTHON_ROOT,
-    ADMIN_TS_ROOT,
-    check_git_status,
-)
+from matrx_orm.schema_builder.common import ADMIN_PYTHON_ROOT, ADMIN_TS_ROOT
+from matrx_orm.schema_builder.helpers.git_checker import check_git_status
 from matrx_orm.schema_builder.helpers.base_generators import (
     generate_active_methods,
     generate_active_relation_methods,

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/schema_builder/helpers/git_checker.py

@@ -2,18 +2,24 @@ import os
 import sys
 from git import Repo, GitCommandError, InvalidGitRepositoryError
 from matrx_utils import vcprint
-from matrx_orm.schema_builder.common import ADMIN_PYTHON_ROOT, ADMIN_TS_ROOT
 
 
-def check_git_status(save_direct):
+def check_git_status(save_direct: bool, python_root: str = "", ts_root: str = "") -> bool:
     """
-    Check if ADMIN_PYTHON_ROOT and ADMIN_TS_ROOT are git repositories
-    and verify if there are any uncommitted changes.
-    Returns True if it's safe to proceed (no changes), False otherwise.
+    Check if python_root and ts_root are git repositories with no uncommitted
+    changes before allowing a save_direct write that could overwrite live files.
+
+    Falls back to ADMIN_PYTHON_ROOT / ADMIN_TS_ROOT env vars when the caller
+    doesn't supply explicit paths (backward-compat).
+
+    Returns True if safe to proceed, exits with code 1 if not.
     """
+    python_root = python_root or os.getenv("ADMIN_PYTHON_ROOT", "")
+    ts_root = ts_root or os.getenv("ADMIN_TS_ROOT", "")
+
     roots_to_check = [
-        ("Admin Python Root", ADMIN_PYTHON_ROOT),
-        ("Admin TypeScript Root", ADMIN_TS_ROOT),
+        ("Python root", python_root),
+        ("TypeScript root", ts_root),
     ]
     has_issues = False
 
@@ -25,10 +31,8 @@ def check_git_status(save_direct):
         return True
 
     vcprint("\n[MATRX GIT CHECKER] Checking git repository status...", color="yellow")
-    vcprint(
-        f"[MATRX GIT CHECKER] ADMIN_PYTHON_ROOT: {ADMIN_PYTHON_ROOT}", color="green"
-    )
-    vcprint(f"[MATRX GIT CHECKER] ADMIN_TS_ROOT: {ADMIN_TS_ROOT}", color="green")
+    vcprint(f"[MATRX GIT CHECKER] Python root:     {python_root}", color="green")
+    vcprint(f"[MATRX GIT CHECKER] TypeScript root: {ts_root}", color="green")
     print()
 
     for root_name, root_path in roots_to_check:

matrx_orm-2.0.4/src/matrx_orm/schema_builder/runner.py

@@ -0,0 +1,160 @@
+"""
+run_schema_generation() — the single entry point for yaml-driven reverse migrations.
+
+Usage:
+    from matrx_orm.schema_builder import run_schema_generation
+    run_schema_generation("matrx_orm.yaml")
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+from matrx_utils import vcprint
+
+from matrx_orm.core.config import register_database_from_env, DatabaseConfigError
+from matrx_orm.schema_builder.common import DEBUG_CONFIG
+from matrx_orm.schema_builder.helpers.git_checker import check_git_status
+from matrx_orm.schema_builder.schema_manager import SchemaManager
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError(
+            "PyYAML is required for yaml-based configuration. "
+            "Install it with: pip install pyyaml"
+        )
+    with open(path) as f:
+        return yaml.safe_load(f) or {}
+
+
+def run_schema_generation(config_path: str | Path = "matrx_orm.yaml") -> None:
+    """
+    Read a matrx_orm.yaml config file, register all databases, apply debug
+    settings, then run reverse-migration schema generation for each entry in
+    the ``generate`` list.
+
+    The config file is looked up relative to the calling script's directory
+    (i.e. the directory that contains generate.py), so users never need to
+    think about working-directory quirks.
+    """
+    # Resolve config path relative to the caller's file location
+    caller_dir = Path(sys.argv[0]).parent.resolve()
+    config_path = (caller_dir / config_path).resolve()
+
+    if not config_path.exists():
+        raise FileNotFoundError(
+            f"matrx-orm config not found: {config_path}\n"
+            f"Create a matrx_orm.yaml file next to your generate.py script."
+        )
+
+    vcprint(f"[matrx-orm] Loading config: {config_path}", color="cyan")
+
+    # Load .env from the same directory as the config file
+    env_file = config_path.parent / ".env"
+    if env_file.exists():
+        load_dotenv(env_file)
+    else:
+        load_dotenv()  # fallback to default search
+
+    cfg = _load_yaml(config_path)
+
+    # -------------------------------------------------------------------------
+    # Debug settings
+    # -------------------------------------------------------------------------
+    debug_cfg = cfg.get("debug", {})
+    DEBUG_CONFIG["info"] = bool(debug_cfg.get("info", False))
+    DEBUG_CONFIG["debug"] = bool(debug_cfg.get("debug", False))
+    DEBUG_CONFIG["verbose"] = bool(debug_cfg.get("verbose", False))
+
+    # -------------------------------------------------------------------------
+    # Output directories + save_direct
+    # -------------------------------------------------------------------------
+    output_cfg = cfg.get("output", {})
+    base = config_path.parent
+    save_direct = bool(output_cfg.get("save_direct", False))
+
+    python_root = ""
+    ts_root = ""
+
+    if "python_root" in output_cfg:
+        python_root = str((base / output_cfg["python_root"]).resolve())
+        os.environ["ADMIN_PYTHON_ROOT"] = python_root
+
+    if "typescript_root" in output_cfg:
+        ts_root = str((base / output_cfg["typescript_root"]).resolve())
+        os.environ["ADMIN_TS_ROOT"] = ts_root
+
+    # -------------------------------------------------------------------------
+    # Git safety check — must run before any generation when save_direct=True
+    # -------------------------------------------------------------------------
+    check_git_status(save_direct, python_root=python_root, ts_root=ts_root)
+
+    # -------------------------------------------------------------------------
+    # Register databases
+    # -------------------------------------------------------------------------
+    databases = cfg.get("databases", [])
+    if not databases:
+        vcprint("[matrx-orm] No databases defined in matrx_orm.yaml — nothing to do.", color="yellow")
+        return
+
+    for db in databases:
+        name = db.get("name")
+        prefix = db.get("env_prefix")
+        if not name or not prefix:
+            vcprint(f"[matrx-orm] Skipping database entry missing 'name' or 'env_prefix': {db}", color="yellow")
+            continue
+
+        register_database_from_env(
+            name=name,
+            env_prefix=prefix,
+            additional_schemas=db.get("additional_schemas", []),
+        )
+
+    # -------------------------------------------------------------------------
+    # Run generation for each configured target
+    # -------------------------------------------------------------------------
+    generate_list = cfg.get("generate", [])
+    if not generate_list:
+        vcprint("[matrx-orm] No entries in 'generate' — databases registered but nothing generated.", color="yellow")
+        return
+
+    for entry in generate_list:
+        db_name = entry.get("database")
+        schema = entry.get("schema", "public")
+
+        vcprint(
+            f"[matrx-orm] Generating schema for database='{db_name}' schema='{schema}'",
+            color="cyan",
+        )
+
+        try:
+            manager = SchemaManager(
+                schema=schema,
+                database_project=db_name,
+                save_direct=save_direct,
+            )
+            manager.initialize()
+            manager.schema.generate_schema_files()
+            manager.schema.generate_models()
+            vcprint(
+                f"[matrx-orm] Done — database='{db_name}' schema='{schema}'",
+                color="green",
+            )
+        except DatabaseConfigError as e:
+            vcprint(
+                f"[matrx-orm] Skipping '{db_name}': {e}",
+                color="red",
+            )
+        except Exception as e:
+            vcprint(
+                f"[matrx-orm] Error generating '{db_name}': {e}",
+                color="red",
+            )
+            raise

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/src/matrx_orm/schema_builder/schema_manager.py

@@ -66,6 +66,10 @@ class SchemaManager:
             set(exclude_tables) if exclude_tables is not None else None
         )
 
+        vcprint(self.schema, title=f"SCHEMA MANAGER] with schema", verbose=self.verbose, color="blue")
+        vcprint(self.database_project, title=f"SCHEMA MANAGER] with database project", verbose=self.verbose, color="blue")
+        vcprint(self.additional_schemas, title=f"SCHEMA MANAGER] with additional schemas", verbose=self.verbose, color="blue")
+
         # Propagate filter to the Schema so generate_models() can apply it at
         # write-time without touching any loading or relationship logic.
         self.schema._include_tables = self._include_tables

{matrx_orm-2.0.2 → matrx_orm-2.0.4}/tests/sample_project/.env.example

@@ -1,19 +1,24 @@
 # ============================================================
-# matrx-orm Sample Project — Environment Variable Template
+# matrx-orm Sample Project — Environment Variables
 # ============================================================
-# Copy this file to .env and fill in your real credentials.
-# The .env file is gitignored and will never be committed.
+
+BASE_DIR=enter_your_base_directory_here
+ADMIN_PYTHON_ROOT=enter_your_python_root_here
+ADMIN_TS_ROOT=enter_your_typescript_root_here
+
 
 # --- Primary database (e.g. your main Supabase project) ---
-PRIMARY_DB_HOST=db.<project-ref>.supabase.co
+PRIMARY_DB_HOST=enter_your_primary_db_host_here
 PRIMARY_DB_PORT=5432
+PRIMARY_DB_PROTOCOL=postgresql
 PRIMARY_DB_NAME=postgres
 PRIMARY_DB_USER=postgres
 PRIMARY_DB_PASSWORD=your-database-password-here
 
 # --- Secondary database (e.g. a second Supabase project or remote Postgres) ---
-SECONDARY_DB_HOST=db.<project-ref>.supabase.co
+SECONDARY_DB_HOST=enter_your_secondary_db_host_here
 SECONDARY_DB_PORT=5432
+SECONDARY_DB_PROTOCOL=postgresql
 SECONDARY_DB_NAME=postgres
 SECONDARY_DB_USER=postgres
 SECONDARY_DB_PASSWORD=your-database-password-here

matrx_orm-2.0.4/tests/sample_project/generate.py

@@ -0,0 +1,3 @@
+from matrx_orm.schema_builder import run_schema_generation
+
+run_schema_generation("matrx_orm.yaml")

matrx_orm-2.0.4/tests/sample_project/matrx_orm.yaml

@@ -0,0 +1,57 @@
+# =============================================================================
+# matrx-orm configuration
+# =============================================================================
+#
+# This file drives reverse-migration schema generation.
+# Run:  python generate.py
+#
+# Output directories for generated files.
+# Use absolute paths or paths relative to this config file.
+output:
+  python_root: generated/python
+  typescript_root: generated/typescript
+  # save_direct: false  — set to true to write directly to the roots above.
+  #                       When true, matrx-orm will refuse to run if either
+  #                       root has uncommitted git changes (safety guard).
+  save_direct: false
+
+# =============================================================================
+# Databases
+# =============================================================================
+# Add as many databases as you need. Each entry needs a unique name.
+# The env_prefix tells matrx-orm which environment variables hold the
+# connection details.  For a prefix of "PRIMARY_DB" it reads:
+#   PRIMARY_DB_HOST, PRIMARY_DB_PORT, PRIMARY_DB_NAME,
+#   PRIMARY_DB_USER, PRIMARY_DB_PASSWORD
+#   PRIMARY_DB_PROTOCOL  (optional, defaults to "postgresql")
+#
+databases:
+  - name: primary
+    env_prefix: PRIMARY_DB
+    additional_schemas:
+      - auth
+
+  - name: secondary
+    env_prefix: SECONDARY_DB
+
+# =============================================================================
+# Schema generation
+# =============================================================================
+# Each entry below triggers one reverse-migration run.
+# database must match a name defined in the databases section above.
+#
+generate:
+  - database: primary
+    schema: public
+
+  # Uncomment to also generate from the secondary database:
+  # - database: secondary
+  #   schema: public
+
+# =============================================================================
+# Debug
+# =============================================================================
+debug:
+  info: false
+  verbose: false
+  debug: false