refactor: make dj.Schema a proper class subclassing _Schema

Rename schemas.Schema → schemas._Schema (internal) and define
dj.Schema as a class that inherits from _Schema with a thread-safety
check in __init__. This eliminates the confusing function-vs-class
duality where dj.Schema was a function wrapper and schemas.Schema
was the class.

Now dj.Schema is a real class: isinstance, hasattr, and subclass
checks all work naturally. The test for rebuild_lineage can use
dj.Schema directly instead of importing from datajoint.schemas.

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

Author: dimitri-yatsenko

src/datajoint/__init__.py

@@ -80,7 +80,7 @@
 from .instance import Instance, _ConfigProxy, _get_singleton_connection, _global_config, _check_thread_safe
 from .logging import logger
 from .objectref import ObjectRef
-from .schemas import Schema as _Schema, VirtualModule, list_schemas, virtual_schema
+from .schemas import _Schema, VirtualModule, list_schemas, virtual_schema
 from .table import FreeTable as _FreeTable, Table, ValidationResult
 from .user_tables import Computed, Imported, Lookup, Manual, Part
 from .version import __version__
@@ -166,26 +166,20 @@ def conn(
     return _get_singleton_connection()
 
 
-def Schema(
-    schema_name: str | None = None,
-    context: dict | None = None,
-    *,
-    connection: Connection | None = None,
-    create_schema: bool = True,
-    create_tables: bool | None = None,
-    add_objects: dict | None = None,
-) -> _Schema:
+class Schema(_Schema):
     """
-    Create a Schema for binding table classes to a database schema.
+    Decorator that binds table classes to a database schema.
 
     When connection is not provided, uses the singleton connection.
+    In thread-safe mode (``DJ_THREAD_SAFE=true``), a connection must be
+    provided explicitly or use ``dj.Instance().Schema()`` instead.
 
     Parameters
     ----------
     schema_name : str, optional
-        Database schema name.
+        Database schema name. If omitted, call ``activate()`` later.
     context : dict, optional
-        Namespace for foreign key lookup.
+        Namespace for foreign key lookup. None uses caller's context.
     connection : Connection, optional
         Database connection. Defaults to singleton connection.
     create_schema : bool, optional
@@ -195,29 +189,41 @@ def Schema(
     add_objects : dict, optional
         Additional objects for declaration context.
 
-    Returns
-    -------
-    Schema
-        A Schema bound to the specified connection.
-
     Raises
     ------
     ThreadSafetyError
-        If thread_safe mode is enabled and using singleton.
+        If thread_safe mode is enabled and no connection is provided.
+
+    Examples
+    --------
+    >>> schema = dj.Schema('my_schema')
+    >>> @schema
+    ... class Session(dj.Manual):
+    ...     definition = '''
+    ...     session_id : int
+    ...     '''
     """
-    if connection is None:
-        # Use singleton connection - will raise ThreadSafetyError if thread_safe=True
-        _check_thread_safe()
-        connection = _get_singleton_connection()
-
-    return _Schema(
-        schema_name,
-        context=context,
-        connection=connection,
-        create_schema=create_schema,
-        create_tables=create_tables,
-        add_objects=add_objects,
-    )
+
+    def __init__(
+        self,
+        schema_name: str | None = None,
+        context: dict | None = None,
+        *,
+        connection: Connection | None = None,
+        create_schema: bool = True,
+        create_tables: bool | None = None,
+        add_objects: dict | None = None,
+    ) -> None:
+        if connection is None:
+            _check_thread_safe()
+        super().__init__(
+            schema_name,
+            context=context,
+            connection=connection,
+            create_schema=create_schema,
+            create_tables=create_tables,
+            add_objects=add_objects,
+        )
 
 
 def FreeTable(conn_or_name, full_table_name: str | None = None) -> _FreeTable:

src/datajoint/gc.py

@@ -44,7 +44,7 @@
 from .errors import DataJointError
 
 if TYPE_CHECKING:
-    from .schemas import Schema
+    from .schemas import _Schema as Schema
 
 logger = logging.getLogger(__name__.split(".")[0])
 

src/datajoint/instance.py

@@ -15,7 +15,7 @@
 from .settings import Config, _create_config, config as _settings_config
 
 if TYPE_CHECKING:
-    from .schemas import Schema as SchemaClass
+    from .schemas import _Schema as SchemaClass
     from .table import FreeTable as FreeTableClass
 
 
@@ -140,9 +140,9 @@ def Schema(
         Schema
             A Schema using this instance's connection.
         """
-        from .schemas import Schema
+        from .schemas import _Schema
 
-        return Schema(
+        return _Schema(
             schema_name,
             context=context,
             connection=self.connection,

src/datajoint/migrate.py

@@ -39,7 +39,7 @@
     )
 
 if TYPE_CHECKING:
-    from .schemas import Schema
+    from .schemas import _Schema as Schema
 
 logger = logging.getLogger(__name__.split(".")[0])
 
@@ -653,7 +653,7 @@ def add_job_metadata_columns(target, dry_run: bool = True) -> dict:
     - Future populate() calls will fill in metadata for new rows
     - This does NOT retroactively populate metadata for existing rows
     """
-    from .schemas import Schema
+    from .schemas import _Schema
     from .table import Table
 
     result = {
@@ -664,7 +664,7 @@ def add_job_metadata_columns(target, dry_run: bool = True) -> dict:
     }
 
     # Determine tables to process
-    if isinstance(target, Schema):
+    if isinstance(target, _Schema):
         schema = target
         # Get all user tables in the schema
         tables_query = """

src/datajoint/schemas.py

@@ -53,7 +53,7 @@ def ordered_dir(class_: type) -> list[str]:
     return attr_list
 
 
-class Schema:
+class _Schema:
     """
     Decorator that binds table classes to a database schema.
 
@@ -832,7 +832,7 @@ def __init__(
             Additional objects to add to the module namespace.
         """
         super(VirtualModule, self).__init__(name=module_name)
-        _schema = Schema(
+        _schema = _Schema(
             schema_name,
             create_schema=create_schema,
             create_tables=create_tables,

tests/integration/test_semantic_matching.py

@@ -325,9 +325,7 @@ class TestRebuildLineageUtility:
 
     def test_rebuild_lineage_method_exists(self):
         """The rebuild_lineage method should exist on Schema."""
-        from datajoint.schemas import Schema as _Schema
-
-        assert hasattr(_Schema, "rebuild_lineage")
+        assert hasattr(dj.Schema, "rebuild_lineage")
 
     def test_rebuild_lineage_populates_table(self, schema_semantic):
         """schema.rebuild_lineage() should populate the ~lineage table."""