feat: add ManagedBy StrEnum for managed_by parameter (#1807)

* feat: add ManagedBy StrEnum to replace Literal type for managed_by

Define a common ManagedBy StrEnum in connectorkits/target.py and use it
across all 6 target connectors instead of scattered Literal["system", "user"]
annotations. This gives a single source of truth, better IDE support, and
clearer semantics. Also fixes pre-existing mypy errors in the SQLite target
test by adding a type annotation and using the new enum.

Closes #1806

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: import ManagedBy from target module directly instead of statediff

Since ManagedBy lives in connectorkits/target.py, connectors should
import it from there (target.ManagedBy) rather than going through
statediff. This makes the provenance clear.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: batmany13

python/cocoindex/connectorkits/statediff.py

@@ -92,7 +92,7 @@ class TrackingRecordTransition(_Generic[_TrackingRecordT], _NamedTuple):
     prev_may_be_missing: bool
 
 
-ManagedBy = _Literal["system", "user"]
+from cocoindex.connectorkits.target import ManagedBy as ManagedBy
 
 
 @_unpickle_safe

python/cocoindex/connectorkits/target.py

@@ -0,0 +1,14 @@
+"""Shared types for target connectors."""
+
+from __future__ import annotations
+
+__all__ = ["ManagedBy"]
+
+import enum as _enum
+
+
+class ManagedBy(_enum.StrEnum):
+    """Who manages the lifecycle of the target resource."""
+
+    SYSTEM = "system"
+    USER = "user"

python/cocoindex/connectors/doris/_target.py

@@ -46,7 +46,7 @@
 from typing_extensions import TypeVar
 
 import cocoindex as coco
-from cocoindex.connectorkits import statediff
+from cocoindex.connectorkits import statediff, target
 from cocoindex.connectorkits.fingerprint import fingerprint_object
 from cocoindex._internal.datatype import (
     AnyType,
@@ -942,7 +942,7 @@ class _TableKey(NamedTuple):
 @dataclass
 class _TableSpec:
     table_schema: TableSchema[Any]
-    managed_by: Literal["system", "user"] = "system"
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM
     vector_indexes: list[VectorIndexDef] | None = None
     inverted_indexes: list[InvertedIndexDef] | None = None
 
@@ -1191,7 +1191,7 @@ def table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
     vector_indexes: list[VectorIndexDef] | None = None,
     inverted_indexes: list[InvertedIndexDef] | None = None,
 ) -> coco.TargetState[_RowHandler]:
@@ -1210,7 +1210,7 @@ def declare_table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
     vector_indexes: list[VectorIndexDef] | None = None,
     inverted_indexes: list[InvertedIndexDef] | None = None,
 ) -> "DorisTableTarget[RowT, coco.PendingS]":
@@ -1232,7 +1232,7 @@ async def mount_table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
     vector_indexes: list[VectorIndexDef] | None = None,
     inverted_indexes: list[InvertedIndexDef] | None = None,
 ) -> "DorisTableTarget[RowT]":

python/cocoindex/connectors/lancedb/_target.py

@@ -37,7 +37,7 @@
 import numpy as np
 
 import cocoindex as coco
-from cocoindex.connectorkits import statediff
+from cocoindex.connectorkits import statediff, target
 from cocoindex.connectorkits.fingerprint import fingerprint_object
 from cocoindex._internal.datatype import (
     AnyType,
@@ -489,7 +489,7 @@ class _TableSpec:
     """Specification for a LanceDB table."""
 
     table_schema: TableSchema[Any]
-    managed_by: Literal["system", "user"] = "system"
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM
 
 
 @unpickle_safe
@@ -793,7 +793,7 @@ def table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> coco.TargetState[_RowHandler]:
     """
     Create a TargetState for a LanceDB table target.
@@ -823,7 +823,7 @@ def declare_table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> TableTarget[RowT, coco.PendingS]:
     """
     Create a TableTarget for writing rows to a LanceDB table.
@@ -849,7 +849,7 @@ async def mount_table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> TableTarget[RowT]:
     """
     Mount a table target and return a ready-to-use TableTarget.

python/cocoindex/connectors/postgres/_target.py

@@ -39,7 +39,7 @@
 import numpy as np
 
 import cocoindex as coco
-from cocoindex.connectorkits import statediff
+from cocoindex.connectorkits import statediff, target
 from cocoindex.connectorkits.fingerprint import fingerprint_object
 from cocoindex._internal.datatype import (
     AnyType,
@@ -783,7 +783,7 @@ class _TableSpec:
     """Specification for a PostgreSQL table."""
 
     table_schema: TableSchema[Any]
-    managed_by: Literal["system", "user"] = "system"
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM
 
 
 @unpickle_safe
@@ -1257,7 +1257,7 @@ def table_target(
     table_schema: TableSchema[RowT],
     *,
     pg_schema_name: str | None = None,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> coco.TargetState[_RowHandler]:
     """
     Create a TargetState for a PostgreSQL table target.
@@ -1293,7 +1293,7 @@ def declare_table_target(
     table_schema: TableSchema[RowT],
     *,
     pg_schema_name: str | None = None,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> TableTarget[RowT, coco.PendingS]:
     """
     Create a TableTarget for writing rows to a PostgreSQL table.
@@ -1327,7 +1327,7 @@ async def mount_table_target(
     table_schema: TableSchema[RowT],
     *,
     pg_schema_name: str | None = None,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> TableTarget[RowT]:
     """
     Mount a table target and return a ready-to-use TableTarget.

python/cocoindex/connectors/qdrant/_target.py

@@ -32,7 +32,7 @@
     ) from e
 
 import cocoindex as coco
-from cocoindex.connectorkits import statediff
+from cocoindex.connectorkits import statediff, target
 from cocoindex.connectorkits.fingerprint import fingerprint_object
 from cocoindex._internal.datatype import TypeChecker
 from cocoindex._internal.serde import unpickle_safe
@@ -271,7 +271,7 @@ class _CollectionKey(NamedTuple):
 @dataclass
 class _CollectionSpec:
     schema: CollectionSchema
-    managed_by: Literal["system", "user"] = "system"
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM
 
 
 @unpickle_safe
@@ -511,7 +511,7 @@ def collection_target(
     collection_name: str,
     schema: CollectionSchema,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> "coco.TargetState[_PointHandler]":
     """
     Create a TargetState for a Qdrant collection target.
@@ -538,7 +538,7 @@ def declare_collection_target(
     collection_name: str,
     schema: CollectionSchema,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> "CollectionTarget[coco.PendingS]":
     """Declare a Qdrant collection target.
 
@@ -562,7 +562,7 @@ async def mount_collection_target(
     collection_name: str,
     schema: CollectionSchema,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> "CollectionTarget[coco.ResolvedS]":
     """
     Mount a collection target and return a ready-to-use CollectionTarget.

python/cocoindex/connectors/sqlite/_target.py

@@ -34,7 +34,7 @@
 import numpy as np
 
 import cocoindex as coco
-from cocoindex.connectorkits import statediff
+from cocoindex.connectorkits import statediff, target
 from cocoindex.connectorkits.fingerprint import fingerprint_object
 from cocoindex._internal.rwlock import RWLock
 from cocoindex._internal.serde import unpickle_safe
@@ -586,7 +586,7 @@ class _TableSpec:
     """Specification for a SQLite table."""
 
     table_schema: TableSchema[Any]
-    managed_by: Literal["system", "user"] = "system"
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM
     virtual_table_def: Vec0TableDef | None = None
 
 
@@ -1114,7 +1114,7 @@ def table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
     virtual_table_def: Vec0TableDef | None = None,
 ) -> "coco.TargetState[_RowHandler]":
     """
@@ -1151,7 +1151,7 @@ def declare_table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
     virtual_table_def: Vec0TableDef | None = None,
 ) -> "TableTarget[RowT, coco.PendingS]":
     """
@@ -1198,7 +1198,7 @@ async def mount_table_target(
     table_name: str,
     table_schema: TableSchema[RowT],
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
     virtual_table_def: Vec0TableDef | None = None,
 ) -> "TableTarget[RowT]":
     """

python/cocoindex/connectors/surrealdb/_target.py

@@ -47,7 +47,7 @@
 import numpy as np
 
 import cocoindex as coco
-from cocoindex.connectorkits import statediff
+from cocoindex.connectorkits import statediff, target
 from cocoindex.connectorkits.fingerprint import fingerprint_object
 from cocoindex._internal.datatype import (
     AnyType,
@@ -754,7 +754,7 @@ class _TableSpec:
     is_relation: bool
     from_tables: tuple[str, ...] | None  # sorted table names for FROM clause
     to_tables: tuple[str, ...] | None  # sorted table names for TO clause
-    managed_by: Literal["system", "user"] = "system"
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM
 
 
 @dataclass(frozen=True, slots=True)
@@ -1284,7 +1284,7 @@ def table_target(
     table_name: str,
     table_schema: TableSchema[RowT] | None = None,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> coco.TargetState[_RecordHandler]:
     """Create a TargetState for a SurrealDB table."""
     _validate_identifier(table_name, "table name")
@@ -1304,7 +1304,7 @@ def declare_table_target(
     table_name: str,
     table_schema: TableSchema[RowT] | None = None,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> TableTarget[RowT, coco.PendingS]:
     """Declare a table target and return a pending TableTarget."""
     provider = coco.declare_target_state_with_child(
@@ -1318,7 +1318,7 @@ async def mount_table_target(
     table_name: str,
     table_schema: TableSchema[RowT] | None = None,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> TableTarget[RowT]:
     """Mount a table target and return a ready-to-use TableTarget."""
     provider = await coco.mount_target(
@@ -1334,7 +1334,7 @@ def relation_target(
     to_table: TableTarget[Any] | Collection[TableTarget[Any]],
     table_schema: TableSchema[RowT] | None = None,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> coco.TargetState[_RecordHandler]:
     """Create a TargetState for a SurrealDB relation table."""
     _validate_identifier(table_name, "relation table name")
@@ -1362,7 +1362,7 @@ def declare_relation_target(
     to_table: TableTarget[Any] | Collection[TableTarget[Any]],
     table_schema: TableSchema[RowT] | None = None,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> RelationTarget[RowT, coco.PendingS]:
     """Declare a relation target and return a pending RelationTarget."""
     from_names = _normalize_table_names(from_table)
@@ -1387,7 +1387,7 @@ async def mount_relation_target(
     to_table: TableTarget[Any] | Collection[TableTarget[Any]],
     table_schema: TableSchema[RowT] | None = None,
     *,
-    managed_by: Literal["system", "user"] = "system",
+    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
 ) -> RelationTarget[RowT]:
     """Mount a relation target and return a ready-to-use RelationTarget."""
     from_names = _normalize_table_names(from_table)

python/tests/connectors/test_sqlite_target.py

@@ -15,6 +15,7 @@
 
 import cocoindex as coco
 from cocoindex._internal.context_keys import ContextProvider
+from cocoindex.connectorkits import target
 from cocoindex.connectors import sqlite
 from cocoindex.resources.schema import VectorSchema
 
@@ -528,13 +529,13 @@ def test_user_managed_table(sqlite_db: tuple[sqlite.ManagedConnection, Path]) ->
     test_env = make_test_env(managed_conn, "test_user_managed_table")
 
     async def declare_user_managed_rows() -> None:
-        table = await coco.use_mount(
+        table: sqlite.TableTarget[SimpleRow] = await coco.use_mount(
             coco.component_subpath("setup", "table"),
             sqlite.declare_table_target,
             SQLITE_DB,
             "user_managed",
             await sqlite.TableSchema.from_class(SimpleRow, primary_key=["id"]),
-            managed_by="user",
+            managed_by=target.ManagedBy.USER,
         )
 
         for row in user_rows: