tablemaster 2.1.8__tar.gz → 2.1.9__tar.gz

{tablemaster-2.1.8 → tablemaster-2.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablemaster
-Version: 2.1.8
+Version: 2.1.9
 Summary: tablemaster is a Python toolkit for moving and managing tabular data across databases, Feishu/Lark, Google Sheets, and local files with one consistent API.
 Author-email: Livid <livid.su@gmail.com>
 Project-URL: Homepage, https://github.com/ilivid/tablemaster
@@ -220,6 +220,8 @@ tablemaster schema apply mydb --cfg-path ./cfg.yaml
 tablemaster schema pull mydb --cfg-path ./cfg.yaml
 ```
 
+After `tablemaster init`, each `schema/<connection>/` directory includes `_ignore_tables.yaml` by default.
+
 Example schema file:
 
 ```yaml
@@ -238,6 +240,16 @@ indexes:
     unique: true
 ```
 
+Ignore specific tables from schema diff by editing `_ignore_tables.yaml` (or `_ignore_tables.yml`) under `schema/<connection>/`:
+
+```yaml
+tables:
+  - ods_orders_archive
+  - tmp_legacy_users
+```
+
+Tables listed in this file are excluded from schema comparison, so they do not produce `plan` actions or warnings.
+
 ## CLI
 
 `tablemaster` now ships with a built-in CLI:
@@ -271,7 +283,7 @@ CLI command groups:
 - `db query <sql>`: Run SQL with `--cfg-key`; use `--limit` to control stdout preview and `--output` to export full result as CSV.
 - `local read <pattern>`: Read one local CSV/Excel match and print preview; use `--det-header/--no-det-header` to control header detection.
 - `config list`: List top-level keys from config.
-- `init`: Bootstrap `cfg.yaml` and `schema/<connection>/` scaffold in current directory.
+- `init`: Bootstrap `cfg.yaml`, `schema/<connection>/`, and `_ignore_tables.yaml` scaffold in current directory.
 - `schema plan <connection>`: Compare YAML schema and live DB, print/apply-safe plan.
 - `schema apply <connection>`: Execute DDL actions from generated or saved plan.
 - `schema pull <connection>`: Generate YAML schema files from live DB tables.

{tablemaster-2.1.8 → tablemaster-2.1.9}/README.md

@@ -185,6 +185,8 @@ tablemaster schema apply mydb --cfg-path ./cfg.yaml
 tablemaster schema pull mydb --cfg-path ./cfg.yaml
 ```
 
+After `tablemaster init`, each `schema/<connection>/` directory includes `_ignore_tables.yaml` by default.
+
 Example schema file:
 
 ```yaml
@@ -203,6 +205,16 @@ indexes:
     unique: true
 ```
 
+Ignore specific tables from schema diff by editing `_ignore_tables.yaml` (or `_ignore_tables.yml`) under `schema/<connection>/`:
+
+```yaml
+tables:
+  - ods_orders_archive
+  - tmp_legacy_users
+```
+
+Tables listed in this file are excluded from schema comparison, so they do not produce `plan` actions or warnings.
+
 ## CLI
 
 `tablemaster` now ships with a built-in CLI:
@@ -236,7 +248,7 @@ CLI command groups:
 - `db query <sql>`: Run SQL with `--cfg-key`; use `--limit` to control stdout preview and `--output` to export full result as CSV.
 - `local read <pattern>`: Read one local CSV/Excel match and print preview; use `--det-header/--no-det-header` to control header detection.
 - `config list`: List top-level keys from config.
-- `init`: Bootstrap `cfg.yaml` and `schema/<connection>/` scaffold in current directory.
+- `init`: Bootstrap `cfg.yaml`, `schema/<connection>/`, and `_ignore_tables.yaml` scaffold in current directory.
 - `schema plan <connection>`: Compare YAML schema and live DB, print/apply-safe plan.
 - `schema apply <connection>`: Execute DDL actions from generated or saved plan.
 - `schema pull <connection>`: Generate YAML schema files from live DB tables.

{tablemaster-2.1.8 → tablemaster-2.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tablemaster"
-version = "2.1.8"
+version = "2.1.9"
 description = "tablemaster is a Python toolkit for moving and managing tabular data across databases, Feishu/Lark, Google Sheets, and local files with one consistent API."
 readme = "README.md"
 requires-python = ">=3.9"

{tablemaster-2.1.8 → tablemaster-2.1.9}/tablemaster/cli.py

@@ -43,9 +43,10 @@ def _build_plan(
     from .schema.dialects import get_dialect
     from .schema.diff import generate_plan
     from .schema.introspect import introspect_tables
-    from .schema.loader import load_schema_definitions
+    from .schema.loader import load_ignored_tables, load_schema_definitions
 
     db_cfg = _load_named_cfg(cfg_path, connection)
+    ignored_tables = load_ignored_tables(connection=connection, root_dir=schema_dir)
     desired = load_schema_definitions(connection=connection, root_dir=schema_dir, table=table)
     actual = introspect_tables(
         db_cfg,
@@ -53,7 +54,13 @@ def _build_plan(
         schema_name=getattr(desired[0], 'schema_name', None) if desired else None,
     )
     dialect = get_dialect(getattr(db_cfg, 'db_type', 'mysql'))
-    plan = generate_plan(connection_name=connection, desired=desired, actual=actual, dialect=dialect)
+    plan = generate_plan(
+        connection_name=connection,
+        desired=desired,
+        actual=actual,
+        dialect=dialect,
+        ignored_tables=ignored_tables,
+    )
     return db_cfg, plan
 
 

{tablemaster-2.1.8 → tablemaster-2.1.9}/tablemaster/schema/__init__.py

@@ -2,7 +2,7 @@ from .apply import ApplyResult, apply_plan
 from .diff import generate_plan
 from .init import init_scaffold
 from .introspect import introspect_tables
-from .loader import load_schema_definitions
+from .loader import load_ignored_tables, load_schema_definitions
 from .models import (
     ActualColumn,
     ActualTable,
@@ -25,6 +25,7 @@ __all__ = [
     'Plan',
     'ApplyResult',
     'load_schema_definitions',
+    'load_ignored_tables',
     'introspect_tables',
     'generate_plan',
     'render_plan',

{tablemaster-2.1.8 → tablemaster-2.1.9}/tablemaster/schema/diff.py

@@ -58,10 +58,12 @@ def generate_plan(
     desired: list[TableDef],
     actual: list[ActualTable],
     dialect: BaseDialect,
+    ignored_tables: set[str] | None = None,
 ) -> Plan:
     plan = Plan(connection=connection_name)
-    desired_map = {t.table: t for t in desired}
-    actual_map = {t.table: t for t in actual}
+    ignored = set(ignored_tables or [])
+    desired_map = {t.table: t for t in desired if t.table not in ignored}
+    actual_map = {t.table: t for t in actual if t.table not in ignored}
 
     for table_name, table_def in desired_map.items():
         current = actual_map.get(table_name)

{tablemaster-2.1.8 → tablemaster-2.1.9}/tablemaster/schema/init.py

@@ -15,6 +15,10 @@ _CFG_TEMPLATE = """mydb:
   db_type: mysql
 """
 
+_IGNORE_TABLES_TEMPLATE = """# Tables listed here are ignored by schema plan/apply compare.
+tables: []
+"""
+
 
 def _is_db_entry(value) -> bool:
     return isinstance(value, dict) and 'host' in value and 'database' in value
@@ -67,6 +71,10 @@ def init_scaffold(
         if not keep_file.exists():
             keep_file.write_text('', encoding='utf-8')
             created_paths.append(str(keep_file))
+        ignore_file = conn_dir / '_ignore_tables.yaml'
+        if not ignore_file.exists():
+            ignore_file.write_text(_IGNORE_TABLES_TEMPLATE, encoding='utf-8')
+            created_paths.append(str(ignore_file))
 
     return {
         'cfg_path': str(cfg_file),

{tablemaster-2.1.8 → tablemaster-2.1.9}/tablemaster/schema/loader.py

@@ -7,6 +7,8 @@ import yaml
 
 from .models import ColumnDef, IndexDef, TableDef
 
+IGNORE_TABLES_FILENAMES = {'_ignore_tables.yaml', '_ignore_tables.yml'}
+
 
 def _coerce_default(value) -> Optional[str]:
     if value is None:
@@ -61,6 +63,43 @@ def parse_table_file(path: Path) -> TableDef:
     )
 
 
+def _is_ignore_tables_file(path: Path) -> bool:
+    return path.name.lower() in IGNORE_TABLES_FILENAMES
+
+
+def _parse_ignore_tables_file(path: Path) -> set[str]:
+    with path.open('r', encoding='utf-8') as f:
+        raw = yaml.safe_load(f) or {}
+
+    if isinstance(raw, dict):
+        tables = raw.get('tables', raw.get('ignore_tables', []))
+    elif isinstance(raw, list):
+        tables = raw
+    else:
+        raise ValueError(f'Ignore tables file root must be list/dict: {path}')
+
+    if not isinstance(tables, list):
+        raise ValueError(f'Ignore tables must be a list: {path}')
+    return {str(t).strip() for t in tables if str(t).strip()}
+
+
+def load_ignored_tables(
+    connection: str,
+    root_dir: str | Path = 'schema',
+) -> set[str]:
+    root = Path(root_dir).resolve()
+    conn_dir = root / connection
+    if not conn_dir.exists() or not conn_dir.is_dir():
+        raise FileNotFoundError(f'Schema directory not found: {conn_dir}')
+
+    files = sorted(conn_dir.rglob('*.yaml')) + sorted(conn_dir.rglob('*.yml'))
+    ignored: set[str] = set()
+    for file in files:
+        if _is_ignore_tables_file(file):
+            ignored.update(_parse_ignore_tables_file(file))
+    return ignored
+
+
 def load_schema_definitions(
     connection: str,
     root_dir: str | Path = 'schema',
@@ -71,12 +110,15 @@ def load_schema_definitions(
     if not conn_dir.exists() or not conn_dir.is_dir():
         raise FileNotFoundError(f'Schema directory not found: {conn_dir}')
     files = sorted(conn_dir.rglob('*.yaml')) + sorted(conn_dir.rglob('*.yml'))
+    ignore_tables = load_ignored_tables(connection=connection, root_dir=root_dir)
     defs: list[TableDef] = []
     for file in files:
+        if _is_ignore_tables_file(file):
+            continue
         parsed = parse_table_file(file)
         if table and parsed.table != table:
             continue
         defs.append(parsed)
-    if table and not defs:
+    if table and not defs and table not in ignore_tables:
         raise FileNotFoundError(f'Table schema not found under {conn_dir}: {table}')
     return defs

{tablemaster-2.1.8 → tablemaster-2.1.9}/tablemaster.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablemaster
-Version: 2.1.8
+Version: 2.1.9
 Summary: tablemaster is a Python toolkit for moving and managing tabular data across databases, Feishu/Lark, Google Sheets, and local files with one consistent API.
 Author-email: Livid <livid.su@gmail.com>
 Project-URL: Homepage, https://github.com/ilivid/tablemaster
@@ -220,6 +220,8 @@ tablemaster schema apply mydb --cfg-path ./cfg.yaml
 tablemaster schema pull mydb --cfg-path ./cfg.yaml
 ```
 
+After `tablemaster init`, each `schema/<connection>/` directory includes `_ignore_tables.yaml` by default.
+
 Example schema file:
 
 ```yaml
@@ -238,6 +240,16 @@ indexes:
     unique: true
 ```
 
+Ignore specific tables from schema diff by editing `_ignore_tables.yaml` (or `_ignore_tables.yml`) under `schema/<connection>/`:
+
+```yaml
+tables:
+  - ods_orders_archive
+  - tmp_legacy_users
+```
+
+Tables listed in this file are excluded from schema comparison, so they do not produce `plan` actions or warnings.
+
 ## CLI
 
 `tablemaster` now ships with a built-in CLI:
@@ -271,7 +283,7 @@ CLI command groups:
 - `db query <sql>`: Run SQL with `--cfg-key`; use `--limit` to control stdout preview and `--output` to export full result as CSV.
 - `local read <pattern>`: Read one local CSV/Excel match and print preview; use `--det-header/--no-det-header` to control header detection.
 - `config list`: List top-level keys from config.
-- `init`: Bootstrap `cfg.yaml` and `schema/<connection>/` scaffold in current directory.
+- `init`: Bootstrap `cfg.yaml`, `schema/<connection>/`, and `_ignore_tables.yaml` scaffold in current directory.
 - `schema plan <connection>`: Compare YAML schema and live DB, print/apply-safe plan.
 - `schema apply <connection>`: Execute DDL actions from generated or saved plan.
 - `schema pull <connection>`: Generate YAML schema files from live DB tables.

{tablemaster-2.1.8 → tablemaster-2.1.9}/tests/test_schema_core.py

@@ -5,12 +5,23 @@ import unittest
 from tablemaster.schema.dialects.mysql import MySQLDialect
 from tablemaster.schema.dialects.postgresql import PostgreSQLDialect
 from tablemaster.schema.diff import generate_plan
-from tablemaster.schema.loader import load_schema_definitions
+from tablemaster.schema.init import init_scaffold
+from tablemaster.schema.loader import load_ignored_tables, load_schema_definitions
 from tablemaster.schema.models import ActualColumn, ActualTable
 from tablemaster.schema.pull import write_pulled_schema
 
 
 class SchemaCoreTests(unittest.TestCase):
+    def test_init_creates_ignore_tables_template(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            result = init_scaffold(base_dir=root)
+            ignore_path = root / 'schema' / 'mydb' / '_ignore_tables.yaml'
+            self.assertTrue(ignore_path.exists())
+            content = ignore_path.read_text(encoding='utf-8')
+            self.assertIn('tables: []', content)
+            self.assertIn(str(ignore_path), result['created_paths'])
+
     def test_loader_reads_yaml(self):
         with TemporaryDirectory() as td:
             root = Path(td)
@@ -34,6 +45,40 @@ class SchemaCoreTests(unittest.TestCase):
             self.assertEqual('orders', tables[0].table)
             self.assertEqual('id', tables[0].columns[0].name)
 
+    def test_loader_reads_ignored_tables_file(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            schema_dir = root / 'schema' / 'mydb'
+            schema_dir.mkdir(parents=True, exist_ok=True)
+            (schema_dir / '_ignore_tables.yaml').write_text(
+                '\n'.join(
+                    [
+                        'tables:',
+                        '  - orders',
+                        '  - legacy_users',
+                    ]
+                ),
+                encoding='utf-8',
+            )
+            (schema_dir / 'orders.yaml').write_text(
+                '\n'.join(
+                    [
+                        'table: orders',
+                        'columns:',
+                        '  - name: id',
+                        '    type: BIGINT',
+                        '    primary_key: true',
+                        '    nullable: false',
+                    ]
+                ),
+                encoding='utf-8',
+            )
+            ignored = load_ignored_tables(connection='mydb', root_dir=root / 'schema')
+            tables = load_schema_definitions(connection='mydb', root_dir=root / 'schema')
+            self.assertEqual({'orders', 'legacy_users'}, ignored)
+            self.assertEqual(1, len(tables))
+            self.assertEqual('orders', tables[0].table)
+
     def test_diff_emits_add_column_and_warning(self):
         with TemporaryDirectory() as td:
             root = Path(td)
@@ -281,6 +326,60 @@ class SchemaCoreTests(unittest.TestCase):
             plan = generate_plan('mydb', desired, actual, PostgreSQLDialect())
             self.assertFalse(any(a.action == 'ALTER_COLUMN_DEFAULT' for a in plan.actions))
 
+    def test_diff_ignored_table_has_no_actions_or_warnings(self):
+        with TemporaryDirectory() as td:
+            root = Path(td)
+            schema_dir = root / 'schema' / 'mydb'
+            schema_dir.mkdir(parents=True, exist_ok=True)
+            (schema_dir / '_ignore_tables.yaml').write_text(
+                '\n'.join(
+                    [
+                        'tables:',
+                        '  - orders',
+                    ]
+                ),
+                encoding='utf-8',
+            )
+            (schema_dir / 'orders.yaml').write_text(
+                '\n'.join(
+                    [
+                        'table: orders',
+                        'columns:',
+                        '  - name: id',
+                        '    type: BIGINT',
+                        '    nullable: false',
+                    ]
+                ),
+                encoding='utf-8',
+            )
+            desired = load_schema_definitions(connection='mydb', root_dir=root / 'schema')
+            ignored = load_ignored_tables(connection='mydb', root_dir=root / 'schema')
+            actual = [
+                ActualTable(
+                    table='orders',
+                    columns=[
+                        ActualColumn(
+                            name='id',
+                            type='BIGINT',
+                            nullable=True,
+                            default=None,
+                            comment=None,
+                        ),
+                        ActualColumn(
+                            name='legacy_col',
+                            type='VARCHAR(32)',
+                            nullable=True,
+                            default=None,
+                            comment=None,
+                        ),
+                    ],
+                    indexes=[],
+                )
+            ]
+            plan = generate_plan('mydb', desired, actual, MySQLDialect(), ignored_tables=ignored)
+            self.assertEqual([], plan.actions)
+            self.assertEqual([], plan.warnings)
+
 
 if __name__ == '__main__':
     unittest.main()