mainsequence 4.2.1__tar.gz → 4.2.2__tar.gz

{mainsequence-4.2.1/mainsequence.egg-info → mainsequence-4.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.2.1
+Version: 4.2.2
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.2.1 → mainsequence-4.2.2}/agent_scaffold/skills/data_publishing/meta_tables/SKILL.md

@@ -95,6 +95,29 @@ For every non-trivial task, decide:
 
 ## Build Rules
 
+### 0. Creation And Deletion Are SDK-Managed
+
+Do not build custom migrations for creating or deleting MetaTables.
+
+MetaTable creation and deletion are handled through `mainsequence-sdk` and the
+Main Sequence CLI. Assistants should define the SQLAlchemy MetaTable model,
+select the SDK migration provider when schema evolution is needed, and use the
+documented `mainsequence migrations ...` commands.
+
+Do not hand-author create/delete migration files, backend migration payloads,
+manifest rows, registry rows, or low-level SDK migration requests for MetaTable
+creation or deletion.
+
+The only migration workflow to recommend is the Main Sequence CLI lifecycle:
+
+```bash
+mainsequence migrations current --provider mainsequence_migrations:migration
+mainsequence migrations revision --provider mainsequence_migrations:migration
+mainsequence migrations render --provider mainsequence_migrations:migration --to head
+mainsequence migrations upgrade --provider mainsequence_migrations:migration --to head --dry-run
+mainsequence migrations upgrade --provider mainsequence_migrations:migration --to head
+```
+
 ### 1. SQLAlchemy metadata is the authoring source
 
 Keep the application table model as the authoring source for the neutral table contract.

{mainsequence-4.2.1 → mainsequence-4.2.2}/mainsequence/client/metatables/core.py

@@ -1102,6 +1102,25 @@ class MetaTable(BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin, B
         *,
         timeout: int | float | tuple[float, float] | None = None,
     ) -> dict[str, Any]:
+        """
+        Refresh this MetaTable's physical database shape snapshot.
+
+        This calls the backend ``POST /meta_table/<uid>/introspect/`` action.
+        The backend reads the real physical table through the MetaTable's data
+        source, reflects columns, indexes, and constraints, stores that data on
+        ``MetaTable.introspection_snapshot``, and returns the full response.
+
+        This method is intended for admin, debugging, and reconciliation
+        workflows. Use it when a client needs to inspect what the database
+        currently has, diagnose catalog/physical drift, or refresh metadata
+        after an out-of-band DDL change. It is not required for normal reads,
+        writes, registration, or migration-first application startup.
+
+        Returns:
+            Backend response containing ``ok``, ``meta_table_uid``, and
+            ``introspection_snapshot``. When the snapshot is an object, this
+            instance's ``introspection_snapshot`` attribute is updated in place.
+        """
         response_json = self._post_detail_action("introspect", timeout=timeout)
         snapshot = response_json.get("introspection_snapshot")
         if isinstance(snapshot, dict):

{mainsequence-4.2.1 → mainsequence-4.2.2}/mainsequence/meta_tables/data_nodes/persist_managers.py

@@ -108,6 +108,13 @@ def ensure_registered_storage_table(
         raise ValueError(
             f"{context} storage_table is missing TimeIndexMetaData metadata."
         )
+    from mainsequence.client.metatables import TimeIndexMetaData
+
+    if not isinstance(storage_metadata, TimeIndexMetaData):
+        raise TypeError(
+            f"{context} storage_table must bind TimeIndexMetaData metadata; "
+            f"got {type(storage_metadata).__name__}."
+        )
     if storage_table.get_meta_table_uid() in (None, ""):
         raise ValueError(f"{context} storage_table must provide a MetaTable UID.")
     if storage_table.get_data_source_uid() in (None, ""):

{mainsequence-4.2.1 → mainsequence-4.2.2}/mainsequence/meta_tables/migrations.py

@@ -18,10 +18,12 @@ from mainsequence.client.metatables import (
     MetaTableContract,
     MetaTablePhysicalContract,
     MetaTableRegistrationRequest,
+    TimeIndexMetaData,
 )
 from mainsequence.meta_tables.hashing import build_meta_table_storage_hash
 from mainsequence.meta_tables.sqlalchemy_contracts import (
     PlatformManagedMetaTable,
+    PlatformTimeIndexMetaData,
     _resolve_model_data_source_uid,
     platform_managed_migration_registration_context,
     resolve_metatable_identifier,
@@ -268,8 +270,8 @@ class AlembicMetaTableMigration:
         timeout: int | float | tuple[float, float] | None = None,
     ) -> list[Any]:
         registered: list[Any] = []
-        existing_meta_tables = _get_metatables_by_identifier(
-            [resolve_metatable_identifier(model) for model in self.metatable_models],
+        existing_meta_tables = _get_metatables_by_model_identifier(
+            self.metatable_models,
             timeout=timeout,
         )
         with platform_managed_migration_registration_context():
@@ -298,8 +300,8 @@ class AlembicMetaTableMigration:
         """
 
         resolved: list[Any] = []
-        existing_meta_tables = _get_metatables_by_identifier(
-            [resolve_metatable_identifier(model) for model in self.metatable_models],
+        existing_meta_tables = _get_metatables_by_model_identifier(
+            self.metatable_models,
             timeout=timeout,
         )
         with platform_managed_migration_registration_context():
@@ -326,7 +328,7 @@ class AlembicMetaTableMigration:
         existing_meta_table = (
             existing_meta_tables_by_identifier.get(identifier)
             if existing_meta_tables_by_identifier is not None
-            else _get_metatable_by_identifier(identifier, timeout=timeout)
+            else _get_metatable_by_model_identifier(model, timeout=timeout)
         )
         if existing_meta_table is not None:
             _bind_model_to_existing_metatable(model, existing_meta_table)
@@ -603,25 +605,77 @@ def _get_metatable_by_identifier(
     identifier: str,
     *,
     timeout: int | float | tuple[float, float] | None = None,
+    meta_table_cls: type[Any] = MetaTable,
 ) -> MetaTable | None:
-    matches = _get_metatables_by_identifier([identifier], timeout=timeout)
+    matches = _get_metatables_by_identifier(
+        [identifier],
+        timeout=timeout,
+        meta_table_cls=meta_table_cls,
+    )
     return matches.get(identifier)
 
 
+def _get_metatable_by_model_identifier(
+    model: type[Any],
+    *,
+    timeout: int | float | tuple[float, float] | None = None,
+) -> Any | None:
+    identifier = resolve_metatable_identifier(model)
+    return _get_metatable_by_identifier(
+        identifier,
+        timeout=timeout,
+        meta_table_cls=_metatable_resource_class_for_model(model),
+    )
+
+
+def _get_metatables_by_model_identifier(
+    models: Sequence[type[Any]],
+    *,
+    timeout: int | float | tuple[float, float] | None = None,
+) -> dict[str, Any]:
+    identifiers_by_resource: dict[type[Any], list[str]] = {}
+    for model in models:
+        identifiers_by_resource.setdefault(
+            _metatable_resource_class_for_model(model),
+            [],
+        ).append(resolve_metatable_identifier(model))
+
+    resolved: dict[str, Any] = {}
+    for meta_table_cls, identifiers in identifiers_by_resource.items():
+        matches = _get_metatables_by_identifier(
+            identifiers,
+            timeout=timeout,
+            meta_table_cls=meta_table_cls,
+        )
+        duplicate_identifiers = set(resolved).intersection(matches)
+        if duplicate_identifiers:
+            duplicate_list = ", ".join(sorted(duplicate_identifiers))
+            raise ValueError(
+                "MetaTable identifiers are not globally unique across provider models: "
+                f"{duplicate_list}."
+            )
+        resolved.update(matches)
+    return resolved
+
+
 def _get_metatables_by_identifier(
     identifiers: Sequence[str],
     *,
     timeout: int | float | tuple[float, float] | None = None,
-) -> dict[str, MetaTable]:
+    meta_table_cls: type[Any] = MetaTable,
+) -> dict[str, Any]:
     unique_identifiers = list(dict.fromkeys(str(identifier) for identifier in identifiers))
     if not unique_identifiers:
         return {}
 
-    matches = MetaTable.filter(identifier__in=unique_identifiers, timeout=timeout)
+    filter_kwargs: dict[str, Any] = {"identifier__in": unique_identifiers}
+    if issubclass(meta_table_cls, TimeIndexMetaData):
+        filter_kwargs["include_relations_detail"] = True
+    matches = meta_table_cls.filter(timeout=timeout, **filter_kwargs)
     if not matches:
         return {}
 
-    matched_by_identifier: dict[str, MetaTable] = {}
+    matched_by_identifier: dict[str, Any] = {}
     for meta_table in matches:
         identifier = _meta_table_identifier(meta_table)
         if identifier is None:
@@ -629,8 +683,8 @@ def _get_metatables_by_identifier(
                 identifier = unique_identifiers[0]
             else:
                 raise ValueError(
-                    "Backend returned a MetaTable row without identifier while resolving "
-                    "migration provider models by identifier__in."
+                    f"Backend returned a {meta_table_cls.__name__} row without identifier "
+                    "while resolving migration provider models by identifier__in."
                 )
         if identifier in matched_by_identifier:
             raise ValueError(
@@ -651,6 +705,12 @@ def _meta_table_identifier(meta_table: Any) -> str | None:
     return str(identifier)
 
 
+def _metatable_resource_class_for_model(model: type[Any]) -> type[Any]:
+    if _is_platform_time_index_metatable_model(model):
+        return TimeIndexMetaData
+    return MetaTable
+
+
 def _bind_model_to_existing_metatable(model: Any, meta_table: MetaTable) -> None:
     bind = getattr(model, "_bind_meta_table", None)
     if not callable(bind):
@@ -665,6 +725,10 @@ def _is_platform_managed_metatable_model(model: Any) -> bool:
     return isinstance(model, type) and issubclass(model, PlatformManagedMetaTable)
 
 
+def _is_platform_time_index_metatable_model(model: Any) -> bool:
+    return isinstance(model, type) and issubclass(model, PlatformTimeIndexMetaData)
+
+
 __all__ = [
     "AlembicMetaTableMigration",
     "AlembicVersionMetaTable",

{mainsequence-4.2.1 → mainsequence-4.2.2}/mainsequence/meta_tables/sqlalchemy_contracts.py

@@ -506,6 +506,10 @@ class PlatformTimeIndexMetaData(PlatformManagedMetaTable):
 
     @classmethod
     def _bind_meta_table(cls, meta_table: TimeIndexMetaData) -> TimeIndexMetaData:
+        from mainsequence.client.metatables import TimeIndexMetaData
+
+        if not isinstance(meta_table, TimeIndexMetaData):
+            meta_table = cls._resolve_time_index_metadata_for_bind(meta_table)
         bound = super()._bind_meta_table(meta_table)
         cls.__time_index_metadata__ = bound
         return bound
@@ -514,6 +518,19 @@ class PlatformTimeIndexMetaData(PlatformManagedMetaTable):
     def get_time_index_metadata(cls) -> TimeIndexMetaData | None:
         return getattr(cls, "__time_index_metadata__", None)
 
+    @classmethod
+    def _resolve_time_index_metadata_for_bind(cls, meta_table: Any) -> TimeIndexMetaData:
+        from mainsequence.client.metatables import TimeIndexMetaData
+
+        meta_table_uid = _meta_table_uid(meta_table)
+        if meta_table_uid not in (None, "") and _meta_table_is_time_indexed(meta_table):
+            return TimeIndexMetaData.get_by_uid(str(meta_table_uid))
+        model_name = getattr(cls, "__qualname__", cls.__name__)
+        received_type = type(meta_table).__name__
+        raise TypeError(
+            f"{model_name} requires TimeIndexMetaData binding; got {received_type}."
+        )
+
     @classmethod
     def __table_cls__(cls, *args: Any, **kwargs: Any) -> Any:
         if len(args) < 2:
@@ -1355,6 +1372,29 @@ def _meta_table_physical_table_name(meta_table: Any) -> str | None:
     return str(physical_table_name)
 
 
+def _meta_table_is_time_indexed(meta_table: Any) -> bool:
+    if isinstance(meta_table, Mapping):
+        time_indexed = meta_table.get("time_indexed")
+        table_kind = meta_table.get("table_kind")
+        table_contract = meta_table.get("table_contract")
+        time_indexed_profile = meta_table.get("time_indexed_profile")
+    else:
+        time_indexed = getattr(meta_table, "time_indexed", None)
+        table_kind = getattr(meta_table, "table_kind", None)
+        table_contract = getattr(meta_table, "table_contract", None)
+        time_indexed_profile = getattr(meta_table, "time_indexed_profile", None)
+
+    if time_indexed is True or table_kind == "time_indexed" or time_indexed_profile is not None:
+        return True
+    if isinstance(table_contract, Mapping):
+        return (
+            table_contract.get("table_kind") == "time_indexed"
+            or table_contract.get("dynamic_table") is not None
+            or table_contract.get("time_indexed") is not None
+        )
+    return False
+
+
 def _model_bound_storage_hash(model_or_table: Any) -> str | None:
     storage_hash = getattr(model_or_table, "__metatable_storage_hash__", None)
     if storage_hash not in (None, ""):

{mainsequence-4.2.1 → mainsequence-4.2.2/mainsequence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.2.1
+Version: 4.2.2
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.2.1 → mainsequence-4.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "4.2.1"
+version = "4.2.2"
 description = "Main Sequence SDK "
 readme = "README.md"
 requires-python = ">=3.11"

{mainsequence-4.2.1 → mainsequence-4.2.2}/tests/test_meta_table_migrations.py

@@ -1,16 +1,17 @@
 from __future__ import annotations
 
+import datetime
 import importlib
 import textwrap
 import types
 import uuid
 
 import pytest
-from sqlalchemy import Column, Integer, MetaData, Table, Uuid
+from sqlalchemy import Column, DateTime, Integer, MetaData, String, Table, Uuid
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
-from mainsequence.client.metatables import MetaTable
-from mainsequence.meta_tables import PlatformManagedMetaTable
+from mainsequence.client.metatables import MetaTable, TimeIndexMetaData
+from mainsequence.meta_tables import PlatformManagedMetaTable, PlatformTimeIndexMetaData
 from mainsequence.meta_tables.migrations import (
     DEFAULT_ALEMBIC_VERSION_COLUMN_NAME,
     DEFAULT_ALEMBIC_VERSION_IDENTIFIER,
@@ -404,6 +405,76 @@ def test_alembic_metatable_migration_bulk_resolves_existing_models(monkeypatch):
     assert Account.get_meta_table_uid() == "account-meta-table-uid"
 
 
+def test_alembic_metatable_migration_bulk_resolves_time_index_models_with_dynamic_client(
+    monkeypatch,
+):
+    class Base(DeclarativeBase):
+        metadata = MetaData()
+
+    class ProjectAlembicVersion(AlembicVersionMetaTable):
+        __metatable_data_source_uid__ = "data-source-uid"
+
+    class AccountHoldings(PlatformTimeIndexMetaData, Base):
+        __metatable_namespace__ = "markets"
+        __metatable_identifier__ = "markets.AccountHoldings"
+        __metatable_data_source_uid__ = "data-source-uid"
+        __time_index_name__ = "time_index"
+        __index_names__ = ["time_index", "unique_identifier"]
+
+        time_index: Mapped[datetime.datetime] = mapped_column(
+            DateTime(timezone=True),
+            nullable=False,
+        )
+        unique_identifier: Mapped[str] = mapped_column(String(255), nullable=False)
+
+    migration = AlembicMetaTableMigration(
+        package="msm",
+        migration_namespace="markets",
+        script_location="msm:alembic",
+        target_metadata=Base.metadata,
+        alembic_registry=ProjectAlembicVersion,
+        metatable_models=[AccountHoldings],
+    )
+
+    filter_calls = []
+
+    def fake_time_index_filter(**kwargs):
+        filter_calls.append(kwargs)
+        return [
+            TimeIndexMetaData.model_construct(
+                identifier="markets.AccountHoldings",
+                uid="holdings-meta-table-uid",
+                data_source_uid="data-source-uid",
+                storage_hash="holdings-storage-hash",
+                physical_table_name="mt_holdings",
+            )
+        ]
+
+    monkeypatch.setattr(
+        TimeIndexMetaData,
+        "filter",
+        staticmethod(fake_time_index_filter),
+    )
+    monkeypatch.setattr(
+        MetaTable,
+        "filter",
+        staticmethod(lambda **kwargs: (_ for _ in ()).throw(AssertionError())),
+    )
+
+    resolved = migration.resolve_or_register_metatable_models(timeout=25)
+
+    assert filter_calls == [
+        {
+            "identifier__in": ["markets.AccountHoldings"],
+            "include_relations_detail": True,
+            "timeout": 25,
+        }
+    ]
+    assert [meta_table.uid for meta_table in resolved] == ["holdings-meta-table-uid"]
+    assert AccountHoldings.get_time_index_metadata() is resolved[0]
+    assert isinstance(AccountHoldings.get_time_index_metadata(), TimeIndexMetaData)
+
+
 def test_alembic_metatable_migration_does_not_call_hook_when_model_registration_fails(
     monkeypatch,
 ):

{mainsequence-4.2.1 → mainsequence-4.2.2}/tests/test_meta_tables_sqlalchemy_contracts.py

@@ -11,7 +11,9 @@ import mainsequence.meta_tables.sqlalchemy_contracts as sqlalchemy_contracts
 from mainsequence.client.metatables import (
     DataSource,
     DynamicTableDataSource,
+    MetaTable,
     MetaTableRegistrationRequest,
+    TimeIndexMetaData,
     TimeIndexMetaTableRegistrationRequest,
 )
 from mainsequence.meta_tables import (
@@ -1256,6 +1258,56 @@ def test_time_index_metadata_register_posts_to_dynamic_table_endpoint(monkeypatc
     ]
 
 
+def test_time_index_metadata_bind_rehydrates_flagged_generic_metatable(monkeypatch):
+    class AccountHoldings(PlatformTimeIndexMetaData):
+        pass
+
+    typed_meta_table = TimeIndexMetaData.model_construct(
+        uid="aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+        data_source_uid="dddddddd-dddd-4ddd-8ddd-dddddddddddd",
+        storage_hash="holdings-storage-hash",
+        physical_table_name="mt_holdings",
+    )
+    generic_meta_table = MetaTable.model_construct(
+        uid="aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+        data_source_uid="dddddddd-dddd-4ddd-8ddd-dddddddddddd",
+        storage_hash="holdings-storage-hash",
+        management_mode="platform_managed",
+        physical_table_name="mt_holdings",
+        time_indexed=True,
+        table_kind="time_indexed",
+    )
+
+    calls = []
+
+    def fake_get_by_uid(cls, uid, timeout=None, **filters):
+        calls.append((uid, timeout, filters))
+        return typed_meta_table
+
+    monkeypatch.setattr(TimeIndexMetaData, "get_by_uid", classmethod(fake_get_by_uid))
+
+    AccountHoldings._bind_meta_table(generic_meta_table)
+
+    assert calls == [("aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", None, {})]
+    assert AccountHoldings.get_time_index_metadata() is typed_meta_table
+
+
+def test_time_index_metadata_bind_rejects_unflagged_generic_metatable():
+    class AccountHoldings(PlatformTimeIndexMetaData):
+        pass
+
+    generic_meta_table = MetaTable.model_construct(
+        uid="aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+        data_source_uid="dddddddd-dddd-4ddd-8ddd-dddddddddddd",
+        storage_hash="holdings-storage-hash",
+        management_mode="platform_managed",
+        physical_table_name="mt_holdings",
+    )
+
+    with pytest.raises(TypeError, match="requires TimeIndexMetaData binding"):
+        AccountHoldings._bind_meta_table(generic_meta_table)
+
+
 def test_ensure_registered_storage_table_rejects_unbound_storage():
     columns = [
         FakeColumn("time_index", DateTime(timezone=True), nullable=False),

{mainsequence-4.2.1 → mainsequence-4.2.2}/tests/test_run_configuration.py

@@ -58,6 +58,8 @@ def _platform_storage_model(meta_table: MetaTable) -> type[PlatformTimeIndexMeta
     class RuntimeStorageTable(PlatformTimeIndexMetaData):
         pass
 
+    if not isinstance(meta_table, TimeIndexMetaData):
+        meta_table = TimeIndexMetaData.model_construct(**meta_table.model_dump())
     RuntimeStorageTable._bind_meta_table(meta_table)
     return RuntimeStorageTable
 
@@ -370,7 +372,8 @@ def test_persist_manager_validates_storage_table_without_creating_storage():
         }
     ]
     assert manager.storage_table is storage_table
-    assert manager.storage_metadata is meta_table
+    assert manager.storage_metadata.uid == meta_table.uid
+    assert isinstance(manager.storage_metadata, TimeIndexMetaData)
 
 
 def test_persist_manager_rejects_unbound_platform_time_index_storage_table():
@@ -481,7 +484,8 @@ def test_persist_manager_preserves_storage_table_during_update_lookup():
 
     assert manager.data_node_update.data_node_storage is stale_response_storage
     assert manager.storage_table is storage_table
-    assert manager.storage_metadata is meta_table
+    assert manager.storage_metadata.uid == meta_table.uid
+    assert isinstance(manager.storage_metadata, TimeIndexMetaData)
 
 
 def test_data_node_accepts_platform_time_index_storage_table_runtime_argument():