Modernize virtual schema infrastructure

Problem

The API for working with existing database schemas (when Python classes aren't available) is confusing and inconsistent:

VirtualModule and create_virtual_module are identical (alias) - confusing
spawn_missing_classes uses unusual "spawn" terminology
gc.py references schema.spawn_table() which doesn't exist
No simple way to get a single table class without creating a whole module
Context/namespace manipulation is confusing for users

Proposed Changes

1. Add `Schema.getitem` for direct table access

table_class = schema['TableName']

2. Add `Schema.iter` for iteration

for table_class in schema:
    print(table_class.full_table_name)

3. Add `Schema.get_table(name)` method

Returns a single table class. Also fixes the missing method that gc.py needs.

4. Rename `spawn_missing_classes` to `generate_classes`

Clearer terminology ("generate" vs "spawn").

5. Add `dj.virtual_schema()` function

Cleaner alternative to VirtualModule:

lab = dj.virtual_schema('my_lab_schema')
lab.Subject.fetch()

6. Deprecate `create_virtual_module`

Keep VirtualModule, deprecate the redundant alias.

Files to Modify

src/datajoint/schemas.py - Main implementation
src/datajoint/__init__.py - Exports
src/datajoint/gc.py - Update to use get_table()
tests/integration/test_virtual_module.py - Add tests

Example Usage After Changes

# Current (confusing)
module = dj.VirtualModule('lab', 'my_lab_schema')
module.Subject.fetch()

# Or
schema = dj.Schema('my_lab_schema')
schema.spawn_missing_classes(context=locals())
Subject.fetch()

# Proposed (cleaner)
schema = dj.Schema('my_lab_schema')
Subject = schema['Subject']  # get one table
Subject.fetch()

# Or iterate
for table in schema:
    print(len(table()))

# Or use virtual_schema for module-like access
lab = dj.virtual_schema('my_lab_schema')
lab.Subject.fetch()

feat: modernize virtual schema infrastructure

Implemented in the virtual-modules branch:

Changes

New API

# Direct table access
schema = dj.Schema('my_schema')
table = schema['Experiment']     # bracket notation
table = schema.get_table('experiment')  # explicit method

# Iteration
for table in schema:
    print(table.full_table_name)

# Containment check
if 'Experiment' in schema:
    ...

# Clean virtual schema function
lab = dj.virtual_schema('my_lab')
lab.Subject.fetch()

Breaking Changes

Removed create_virtual_module (use dj.virtual_schema() instead)
This is a major version release so we're cleaning up deprecated APIs

Fixed

gc.py now uses schema.get_table() instead of non-existent schema.spawn_table()

Not Changed

spawn_missing_classes retained (familiar to existing users, not confusing)

Documentation

Added virtual-schemas.md specification to datajoint-docs
Documents schema-module convention (modules == schemas, classes == tables)

Commits:

datajoint-python: feat: modernize virtual schema infrastructure
datajoint-docs: docs: add virtual-schemas specification

Navigation Menu

Repository navigation

Modernize virtual schema infrastructure #1307

Problem

Proposed Changes

1. Add `Schema.getitem` for direct table access

2. Add `Schema.iter` for iteration

3. Add `Schema.get_table(name)` method

4. Rename `spawn_missing_classes` to `generate_classes`

5. Add `dj.virtual_schema()` function

6. Deprecate `create_virtual_module`

Files to Modify

Example Usage After Changes

Changes

New API

Breaking Changes

Fixed

Not Changed

Documentation

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Modernize virtual schema infrastructure #1307

Description

Problem

Proposed Changes

1. Add Schema.__getitem__ for direct table access

2. Add Schema.__iter__ for iteration

3. Add Schema.get_table(name) method

4. Rename spawn_missing_classes to generate_classes

5. Add dj.virtual_schema() function

6. Deprecate create_virtual_module

Files to Modify

Example Usage After Changes

Activity

dimitri-yatsenko commented on Jan 8, 2026

Changes

New API

Breaking Changes

Fixed

Not Changed

Documentation

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Add `Schema.getitem` for direct table access

2. Add `Schema.iter` for iteration

3. Add `Schema.get_table(name)` method

4. Rename `spawn_missing_classes` to `generate_classes`

5. Add `dj.virtual_schema()` function

6. Deprecate `create_virtual_module`