matrx-orm 2.0.7__tar.gz → 2.0.8__tar.gz

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 2.0.7
+Version: 2.0.8
 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

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "2.0.7"
+version = "2.0.8"
 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" }

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/src/matrx_orm/core/config.py

@@ -169,22 +169,26 @@ def register_database_from_env(
     entity_overrides: Dict = None,
     field_overrides: Dict = None,
     manager_config_overrides: Dict = None,
+    env_var_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"):
+    Default env var names (using env_prefix, e.g. "PRIMARY_DB"):
         {env_prefix}_HOST, {env_prefix}_PORT, {env_prefix}_NAME,
         {env_prefix}_USER, {env_prefix}_PASSWORD
+        {env_prefix}_PROTOCOL  (optional, defaults to "postgresql")
 
-    Optional env vars:
-        {env_prefix}_PROTOCOL  — defaults to "postgresql"
+    env_var_overrides lets you remap any key to a different env var name.
+    Example: {"NAME": "SUPABASE_MATRIX_DATABASE_NAME"} reads that env var
+    instead of constructing {env_prefix}_NAME.
 
     Returns True if registration succeeded, False otherwise.
     """
     _REQUIRED = ["HOST", "PORT", "NAME", "USER", "PASSWORD"]
     _OPTIONAL = {"PROTOCOL": "postgresql"}
+    _overrides = env_var_overrides or {}
 
     vcprint(name, f"\n[MATRX ORM] Registering database", color="cyan")
 
@@ -192,7 +196,7 @@ def register_database_from_env(
     resolved: dict[str, str] = {}
 
     for key in _REQUIRED:
-        env_var = f"{env_prefix}_{key}"
+        env_var = _overrides.get(key, f"{env_prefix}_{key}")
         val = os.environ.get(env_var, "").strip()
         if val:
             resolved[key] = val
@@ -200,7 +204,7 @@ def register_database_from_env(
             missing.append(env_var)
 
     for key, default in _OPTIONAL.items():
-        env_var = f"{env_prefix}_{key}"
+        env_var = _overrides.get(key, f"{env_prefix}_{key}")
         val = os.environ.get(env_var, "").strip()
         if val:
             resolved[key] = val
@@ -287,7 +291,6 @@ def get_code_config(db_project):
         # Note: import_lines are dynamically replaced by generate_models() in schema.py
         # based on the actual field types used. This is a fallback default only.
         "import_lines": [
-            "import database_registry",
             "from matrx_orm import Model, model_registry, BaseDTO, BaseManager",
             "from enum import Enum",
             "from dataclasses import dataclass"

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/src/matrx_orm/schema_builder/helpers/git_checker.py

@@ -56,17 +56,25 @@ def check_git_status(save_direct: bool, python_root: str = "", ts_root: str = ""
 
             # Check if there are uncommitted changes
             if repo.is_dirty(untracked_files=True):
-                vcprint("- Uncommitted changes detected! Details:\n", color="red")
-
-                # Show modified files
-                modified = repo.git.status("--porcelain").split("\n")
-                if any(line.strip() for line in modified):
+                modified_lines = [
+                    line.strip()
+                    for line in repo.git.status("--porcelain").split("\n")
+                    if line.strip()
+                ]
+                changed_files = [line[3:].strip() for line in modified_lines]
+
+                # Allow the sole change to be matrx_orm.yaml (config sync artifact)
+                if len(changed_files) == 1 and os.path.basename(changed_files[0]) == "matrx_orm.yaml":
+                    vcprint(
+                        f"- Only 'matrx_orm.yaml' has changes — treating as clean ✓",
+                        color="green",
+                    )
+                else:
+                    vcprint("- Uncommitted changes detected! Details:\n", color="red")
                     vcprint("  Modified files:", color="red")
-                    for line in modified:
-                        if line.strip():
-                            vcprint(f"    {line.strip()}", color="red")
-
-                has_issues = True
+                    for line in modified_lines:
+                        vcprint(f"    {line}", color="red")
+                    has_issues = True
             else:
                 vcprint("- No uncommitted changes found ✓", color="green")
 

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/src/matrx_orm/schema_builder/runner.py

@@ -56,12 +56,25 @@ def run_schema_generation(config_path: str | Path = "matrx_orm.yaml") -> None:
 
     vcprint(config_path, f"[MATRX ORM] Loading config", color="cyan")
 
-    # Load .env from the same directory as the config file
-    env_file = config_path.parent / ".env"
-    if env_file.exists():
+    # Load .env — search from the config file's directory upward, stopping at
+    # the filesystem root.  This mirrors how git, Node, and most tooling work:
+    # the .env lives at the project root, not necessarily next to generate.py.
+    env_file = None
+    search = config_path.parent
+    while True:
+        candidate = search / ".env"
+        if candidate.exists():
+            env_file = candidate
+            break
+        parent = search.parent
+        if parent == search:
+            break
+        search = parent
+
+    if env_file:
         load_dotenv(env_file)
     else:
-        load_dotenv()  # fallback to default search
+        load_dotenv()  # last-resort: let python-dotenv search from cwd
 
     cfg = _load_yaml(config_path)
 
@@ -75,21 +88,49 @@ def run_schema_generation(config_path: str | Path = "matrx_orm.yaml") -> None:
 
     # -------------------------------------------------------------------------
     # Output config — resolves paths, type flags, and save_direct
+    #
+    # Priority (highest wins):
+    #   1. .env  MATRX_PYTHON_ROOT / MATRX_TS_ROOT / MATRX_SAVE_DIRECT
+    #   2. matrx_orm.yaml  output.python_root / output.typescript_root / output.save_direct
+    #
+    # This lets developers keep machine-specific absolute paths (e.g. paths
+    # outside the project, or different per server) in their local .env without
+    # touching the yaml that gets committed to git.
     # -------------------------------------------------------------------------
     output_cfg = cfg.get("output", {})
     base = config_path.parent
 
-    python_root = ""
-    ts_root = ""
-
-    if "python_root" in output_cfg:
+    # Resolve python_root: .env wins over yaml
+    env_python_root = os.environ.get("MATRX_PYTHON_ROOT", "").strip()
+    if env_python_root:
+        python_root = env_python_root
+    elif "python_root" in output_cfg:
         python_root = str((base / output_cfg["python_root"]).resolve())
+    else:
+        python_root = ""
+
+    if python_root:
         os.environ["ADMIN_PYTHON_ROOT"] = python_root
 
-    if "typescript_root" in output_cfg:
+    # Resolve typescript_root: .env wins over yaml
+    env_ts_root = os.environ.get("MATRX_TS_ROOT", "").strip()
+    if env_ts_root:
+        ts_root = env_ts_root
+    elif "typescript_root" in output_cfg:
         ts_root = str((base / output_cfg["typescript_root"]).resolve())
+    else:
+        ts_root = ""
+
+    if ts_root:
         os.environ["ADMIN_TS_ROOT"] = ts_root
 
+    # Resolve save_direct: .env wins over yaml (yaml default is False)
+    env_save_direct = os.environ.get("MATRX_SAVE_DIRECT", "").strip().lower()
+    if env_save_direct in ("1", "true"):
+        output_cfg = {**output_cfg, "save_direct": True}
+    elif env_save_direct in ("0", "false"):
+        output_cfg = {**output_cfg, "save_direct": False}
+
     output_config = OutputConfig.from_dict(output_cfg)
 
     # -------------------------------------------------------------------------
@@ -115,7 +156,12 @@ def run_schema_generation(config_path: str | Path = "matrx_orm.yaml") -> None:
         register_database_from_env(
             name=name,
             env_prefix=prefix,
+            alias=db.get("alias", ""),
             additional_schemas=db.get("additional_schemas", []),
+            entity_overrides=db.get("entity_overrides") or {},
+            field_overrides=db.get("field_overrides") or {},
+            manager_config_overrides=db.get("manager_config_overrides") or {},
+            env_var_overrides=db.get("env_var_overrides") or {},
         )
 
     # -------------------------------------------------------------------------
@@ -130,6 +176,14 @@ def run_schema_generation(config_path: str | Path = "matrx_orm.yaml") -> None:
         db_name = entry.get("database")
         schema = entry.get("schema", "public")
 
+        # Table filters — mutually exclusive
+        include_tables = entry.get("include_tables") or None
+        exclude_tables = entry.get("exclude_tables") or None
+
+        # manager_flags: yaml-level defaults for all tables in this generation run.
+        # Per-table manager_config_overrides (from the databases section) stack on top.
+        manager_flags = entry.get("manager_flags") or None
+
         vcprint(f"[MATRX ORM] Generating schema... \n\n- Database: '{db_name}'\n- Schema: '{schema}'", verbose=DEBUG_CONFIG["verbose"], color="cyan")
 
         try:
@@ -137,6 +191,9 @@ def run_schema_generation(config_path: str | Path = "matrx_orm.yaml") -> None:
                 schema=schema,
                 database_project=db_name,
                 output_config=output_config,
+                include_tables=include_tables,
+                exclude_tables=exclude_tables,
+                manager_flags=manager_flags,
             )
             manager.initialize()
             manager.schema.generate_schema_files()

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/src/matrx_orm/schema_builder/schema.py

@@ -20,12 +20,24 @@ def format_ts_object(ts_object_str):
     return re.sub(r'"(\w+)"\s*:', r"\1:", ts_object_str)
 
 
+_MANAGER_FLAG_DEFAULTS: dict = {
+    "include_core_relations": True,
+    "include_filter_fields": True,
+    "include_active_relations": False,
+    "include_active_methods": False,
+    "include_or_not_methods": False,
+    "include_to_dict_methods": False,
+    "include_to_dict_relations": False,
+}
+
+
 class Schema:
     def __init__(
         self,
         name="public",
         database_project=None,
         output_config: OutputConfig = None,
+        manager_flags: dict | None = None,
     ):
         if output_config is None:
             output_config = OutputConfig()
@@ -44,6 +56,8 @@ class Schema:
         self.initialized = False
         self._include_tables: set[str] | None = None
         self._exclude_tables: set[str] | None = None
+        # Global manager flags — yaml-level defaults, per-table overrides stack on top
+        self.manager_flags: dict = {**_MANAGER_FLAG_DEFAULTS, **(manager_flags or {})}
 
         vcprint(
             self.to_dict(),
@@ -796,7 +810,7 @@ class Schema:
 
         for table_name in sorted_tables:
             table = self.tables[table_name]
-            py_manager_entry = table.to_python_manager_string()
+            py_manager_entry = table.to_python_manager_string(self.manager_flags)
             py_manager_structure.append(py_manager_entry)
 
             py_auto_config_entry = table.base_class_auto_config
@@ -835,7 +849,6 @@ class Schema:
         sorted_field_types = sorted(all_field_types)
         field_imports = ", ".join(sorted_field_types)
         dynamic_import_lines = [
-            "import database_registry",
             f"from matrx_orm import {field_imports}, model_registry, BaseDTO, BaseManager",
         ]
         if has_enums:

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/src/matrx_orm/schema_builder/schema_manager.py

@@ -21,6 +21,7 @@ class SchemaManager:
         save_direct=False,
         include_tables=None,
         exclude_tables=None,
+        manager_flags: dict | None = None,
     ):
         if additional_schemas is None:
             # Read from the registered database config if a project name is provided;
@@ -53,6 +54,7 @@ class SchemaManager:
             name=schema,
             database_project=database_project,
             output_config=output_config,
+            manager_flags=manager_flags,
         )
         self.additional_schemas = additional_schemas
         self.database_project = database_project

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/src/matrx_orm/schema_builder/tables.py

@@ -1138,7 +1138,7 @@ class Table:
 
         return py_structure
 
-    def to_python_manager_string(self):
+    def to_python_manager_string(self, global_manager_flags: dict | None = None):
         MANAGER_CONFIG_OVERRIDES = get_manager_config(self.database_project)
 
         relations = self.get_all_relations_list()
@@ -1150,6 +1150,12 @@ class Table:
         m2m_relations = list(m2m_config.keys()) if m2m_config else None
 
         alias = get_database_alias(self.database_project)
+
+        # Start with system defaults, apply yaml-level global flags, then per-table overrides.
+        # This gives three layers of control:
+        #   1. System defaults (hardcoded here — safe baseline)
+        #   2. global_manager_flags from matrx_orm.yaml generate[].manager_flags
+        #   3. manager_config_overrides from databases[].manager_config_overrides (per-table)
         base_config = {
             "models_module_path": f"database.{alias}.models",
             "model_pascal": self.python_model_name,
@@ -1168,7 +1174,11 @@ class Table:
             "m2m_relations": m2m_relations,
         }
 
-        # Apply overrides if they exist
+        # Layer 2: yaml generate[].manager_flags (all-table defaults for this run)
+        if global_manager_flags:
+            base_config.update(global_manager_flags)
+
+        # Layer 3: per-table manager_config_overrides from the database registration
         if self.name in MANAGER_CONFIG_OVERRIDES:
             model_overrides = MANAGER_CONFIG_OVERRIDES[self.name]
             base_config.update(model_overrides)

matrx_orm-2.0.8/tests/sample_project/.env.example

@@ -0,0 +1,45 @@
+# ============================================================
+# matrx-orm Sample Project — Environment Variables
+# ============================================================
+#
+# Copy this file to .env and fill in your values.
+# The .env file is never committed to git.
+#
+# ============================================================
+# Output path overrides  (optional)
+# ============================================================
+#
+# These override the python_root / typescript_root / save_direct
+# values in matrx_orm.yaml.  Use them to keep machine-specific
+# absolute paths (e.g. paths outside the project, or paths that
+# differ per developer / server) out of the yaml file that gets
+# committed to git.
+#
+# If these are not set, matrx-orm uses whatever is in matrx_orm.yaml.
+#
+# MATRX_PYTHON_ROOT=/absolute/path/to/python/output
+# MATRX_TS_ROOT=/absolute/path/to/typescript/output
+#
+# Override save_direct from .env (true = write directly to roots,
+# false = write to temp staging directory).
+# MATRX_SAVE_DIRECT=true
+
+# ============================================================
+# Primary database  (e.g. your main Supabase project)
+# ============================================================
+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=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.8/tests/sample_project/matrx_orm.yaml

@@ -0,0 +1,122 @@
+# =============================================================================
+# matrx-orm configuration
+# =============================================================================
+#
+# This file drives reverse-migration schema generation.
+# Run:  python generate.py
+#
+# =============================================================================
+# Output
+# =============================================================================
+#
+# python_root and typescript_root set where generated files land.
+# Use absolute paths or paths relative to this config file.
+#
+# These can also be overridden per-environment using .env variables:
+#   MATRX_PYTHON_ROOT=/absolute/path/to/python/output
+#   MATRX_TS_ROOT=/absolute/path/to/typescript/output
+#
+# .env wins over yaml — use it to keep machine-specific paths out of git.
+#
+output:
+  python_root: generated/python
+  typescript_root: generated/typescript
+
+  # save_direct: controls whether generated files overwrite your live source
+  # files or are written to a temporary staging directory instead.
+  #
+  #   false (default) — safe mode. Files go to a temp dir so you can review
+  #                     them before committing. Nothing in your project is
+  #                     touched.
+  #
+  #   true            — live mode. Files are written directly to python_root
+  #                     and typescript_root. matrx-orm will refuse to run if
+  #                     either root has uncommitted git changes (safety guard
+  #                     so you never lose hand-written work).
+  #
+  # Can also be set via .env:  MATRX_SAVE_DIRECT=true
+  #
+  save_direct: true
+
+  # Set any of these to false to skip generating that file type entirely.
+  python: true
+  typescript: true
+  json: true
+
+# =============================================================================
+# 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
+    additional_schemas:
+      - auth
+
+# =============================================================================
+# Schema generation
+# =============================================================================
+# Each entry below triggers one reverse-migration run.
+# database must match a name defined in the databases section above.
+#
+# Table filtering (mutually exclusive — use one or neither):
+#   include_tables: [table_a, table_b]   — only generate these tables
+#   exclude_tables: [table_x, table_y]   — generate everything except these
+#
+# manager_flags controls which methods are included in each generated manager
+# class. These map directly to the code-generation layer — changing them
+# affects what methods every developer gets in their generated managers.
+#
+# Defaults shown below exactly match the built-in system defaults.
+# Only override what you need to change.
+#
+generate:
+  - database: primary
+    schema: public
+    # include_tables:
+    #   - my_table
+    #   - other_table
+    # exclude_tables:
+    #   - internal_table
+    manager_flags:
+      include_core_relations: true      # FK/IFK fetch methods (load_by_*, fetch_fk, fetch_ifk)
+      include_filter_fields: true       # filter_by_* methods for indexed/common lookup fields
+      include_active_relations: false   # active-record style relation traversal
+      include_active_methods: false     # active-record create/update/delete on instance
+      include_or_not_methods: false     # load_or_create, update_or_create helpers
+      include_to_dict_methods: false    # to_dict() / to_json() serializers
+      include_to_dict_relations: false  # include related objects in to_dict() output
+
+  # Uncomment to also generate from the secondary database:
+  # - database: secondary
+  #   schema: public
+  #   manager_flags:
+  #     include_core_relations: true
+  #     include_filter_fields: true
+  #     include_active_relations: false
+  #     include_active_methods: false
+  #     include_or_not_methods: false
+  #     include_to_dict_methods: false
+  #     include_to_dict_relations: false
+
+# =============================================================================
+# Debug
+# =============================================================================
+# Controls console output during generation.
+# Can also be set per-run via env vars: MATRX_INFO, MATRX_DEBUG, MATRX_VERBOSE
+#
+debug:
+  info: true
+  debug: false
+  verbose: false

{matrx_orm-2.0.7 → matrx_orm-2.0.8}/uv.lock

@@ -266,7 +266,7 @@ wheels = [
 
 [[package]]
 name = "matrx-orm"
-version = "2.0.6"
+version = "2.0.7"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },

matrx_orm-2.0.7/tests/sample_project/.env.example

@@ -1,24 +0,0 @@
-# ============================================================
-# matrx-orm Sample Project — Environment Variables
-# ============================================================
-
-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=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=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.7/tests/sample_project/matrx_orm.yaml

@@ -1,67 +0,0 @@
-# =============================================================================
-# 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: write directly to the roots above instead of the temp dir.
-  # When true, matrx-orm will refuse to run if either root has uncommitted
-  # git changes (safety guard).
-  save_direct: true
-
-  # Set any of these to false to skip generating that file type entirely.
-  python: true
-  typescript: true
-  json: true
-
-# =============================================================================
-# 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
-    additional_schemas:
-      - auth
-
-# =============================================================================
-# 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: true
-  debug: true
-  verbose: true
-