Bug: Tables with AttributeAdapter columns raise AssertionError: Declaration context is not set #1278

Activity

1. zhenruiliao

   added

   bugIndicates an unexpected problem or unintended behaviorIndicates an unexpected problem or unintended behavior

   triageIndicates issues, pull requests, or discussions need to be reviewed for the first timeIndicates issues, pull requests, or discussions need to be reviewed for the first time

   on Nov 9, 2025
2. dimitri-yatsenko

   self-assigned this

   on Nov 10, 2025
3. dimitri-yatsenko

   removed

   triageIndicates issues, pull requests, or discussions need to be reviewed for the first timeIndicates issues, pull requests, or discussions need to be reviewed for the first time

   on Dec 20, 2025
4. dimitri-yatsenko

   added this to the DataJoint 2.0 milestone on Dec 20, 2025
5. dimitri-yatsenko commented on Dec 22, 2025

   

   dimitri-yatsenko

   on Dec 22, 2025

   Member

   More actions

   Solved in #1289
6. dimitri-yatsenko commented on Jan 8, 2026

   

   dimitri-yatsenko

   on Jan 8, 2026

   Member

   More actions

   DataJoint 2.0 Solution

   This issue is resolved in DataJoint 2.0 by replacing the AttributeAdapter system entirely with a new Codec system.

   Root Cause

   The legacy AttributeAdapter required a "declaration context" (the Python module where the table was defined) to resolve custom type adapters. When DataJoint internally created FreeTable objects for dependency tracking and foreign key resolution, it failed to pass this context, causing the AssertionError.

   2.0 Architecture

   DataJoint 2.0 introduces a new Codec system that eliminates context dependencies:

   # Define a custom codec (auto-registers on subclass)
   class GraphCodec(dj.Codec):
       name = "graph"  # Used as <graph> in definitions
   
       def get_dtype(self, is_external: bool) -> str:
           return "<blob>"
   
       def encode(self, graph, *, key=None, store_name=None):
           return {'nodes': list(graph.nodes()), 'edges': list(graph.edges())}
   
       def decode(self, stored, *, key=None):
           import networkx as nx
           G = nx.Graph()
           G.add_nodes_from(stored['nodes'])
           G.add_edges_from(stored['edges'])
           return G
   
   # Use in table definitions with angle bracket syntax
   class Connectivity(dj.Manual):
       definition = '''
       id : int
       ---
       graph_data : <graph>
       '''

   Why This Fixes the Issue

   Legacy AttributeAdapter	2.0 Codec System
   Context-dependent resolution	Global codec registry
   Required module inspection	Auto-registration on subclass
   FreeTable context issues	No context dependency
   Decorator-based registration	Automatic via __init_subclass__

   The architectural flaw that caused this issue no longer exists - codecs are looked up from a global registry (_codec_registry) rather than requiring module context to be passed through the call chain.

   Migration

   Replace AttributeAdapter subclasses with Codec subclasses:

   • Implement get_dtype(), encode(), and decode() methods
   • Set the name class attribute
   • Use <name> syntax in table definitions

   See PR #1289 for the full implementation.
7. dimitri-yatsenko commented on Jan 9, 2026

   

   dimitri-yatsenko

   on Jan 9, 2026

   Member

   More actions

   Resolved in DataJoint 2.0

   The AttributeAdapter system has been replaced by the new Codec architecture in DataJoint 2.0.

   Migration path:

   AttributeAdapters should be migrated to Codecs:

   Before (AttributeAdapter):

   class MyAdapter(dj.AttributeAdapter):
       attribute_type = 'longblob'
       def put(self, obj): ...
       def get(self, value): ...

   After (Codec):

   class MyCodec(dj.Codec):
       python_type = MyClass
       dj_type = '<blob>'
       def encode(self, obj): ...
       def decode(self, value): ...

   Benefits of Codec system:

   • Automatic registration via __init_subclass__
   • No context/declaration issues
   • Codec chaining support
   • Built-in validation

   The specific bug with declaration context is not applicable to the new Codec system.

   See the migration guide for detailed migration instructions.
8. dimitri-yatsenko

   closed this as completedon Jan 9, 2026