docs(codecs): teach context as part of the signature, not an option

Every place the library shows a codec now declares `context`, and the prose
says to declare it rather than describing it as something implementations
"may also accept". A codec written from today's documentation therefore
survives the 2.4 removal of the legacy key path without changing.

The compatibility guarantee is unchanged and stated where it belongs: the
underscore keys still work and are still populated, so codecs written before
2.3.4 keep running until 2.4.

Covers the module and class examples in codecs.py, the protocol sketches in
heading.py and spark.py, the builtin_codecs package example, and the
SchemaCodec guidance the two third-party config bugs were copied from.

Author: dimitri-yatsenko

src/datajoint/builtin_codecs/__init__.py

@@ -29,14 +29,14 @@ class GraphCodec(dj.Codec):
             def get_dtype(self, is_store: bool) -> str:
                 return "<blob>"  # Compose with blob for serialization
 
-            def encode(self, graph, *, key=None, store_name=None):
+            def encode(self, graph, *, key=None, context=None, store_name=None):
                 # Convert graph to a serializable format
                 return {
                     'nodes': list(graph.nodes(data=True)),
                     'edges': list(graph.edges(data=True)),
                 }
 
-            def decode(self, stored, *, key=None):
+            def decode(self, stored, *, key=None, context=None):
                 # Reconstruct graph from stored format
                 G = nx.Graph()
                 G.add_nodes_from(stored['nodes'])

src/datajoint/builtin_codecs/schema.py

@@ -38,10 +38,13 @@ class SchemaCodec(Codec, register=False):
     silently rather than raising.
 
     Since 2.3.4 that config arrives in an explicit ``context`` argument rather
-    than hidden among the primary key values. Accept ``context=None`` in
-    ``encode``/``decode`` and pass it to the helpers. The old underscore keys in
-    ``key`` still work and are still populated, with a ``DeprecationWarning``
-    when ``_extract_context`` has to fall back to them; they are removed in 2.4.
+    than hidden among the primary key values. **Declare ``context=None`` in
+    ``encode`` and ``decode`` and pass it to the helpers**, as the example below
+    does.
+
+    The old underscore keys in ``key`` still work and are still populated, so a
+    codec written before 2.3.4 keeps running — but reading them raises a
+    ``DeprecationWarning`` and they are removed in 2.4.
 
     Comparison with Hash-addressed:
         - **Schema-addressed** (this): Path from schema structure, no dedup

src/datajoint/codecs.py

@@ -16,10 +16,10 @@ class GraphCodec(dj.Codec):
     def get_dtype(self, is_store: bool) -> str:
         return "<blob>"
 
-    def encode(self, graph, *, key=None, store_name=None):
+    def encode(self, graph, *, key=None, context=None, store_name=None):
         return {'nodes': list(graph.nodes()), 'edges': list(graph.edges())}
 
-    def decode(self, stored, *, key=None):
+    def decode(self, stored, *, key=None, context=None):
         import networkx as nx
         G = nx.Graph()
         G.add_nodes_from(stored['nodes'])
@@ -81,10 +81,10 @@ class Codec(ABC):
     ...     def get_dtype(self, is_store: bool) -> str:
     ...         return "<blob>"
     ...
-    ...     def encode(self, graph, *, key=None, store_name=None):
+    ...     def encode(self, graph, *, key=None, context=None, store_name=None):
     ...         return {'nodes': list(graph.nodes()), 'edges': list(graph.edges())}
     ...
-    ...     def decode(self, stored, *, key=None):
+    ...     def decode(self, stored, *, key=None, context=None):
     ...         import networkx as nx
     ...         G = nx.Graph()
     ...         G.add_nodes_from(stored['nodes'])
@@ -181,10 +181,15 @@ def encode(self, value: Any, *, key: dict | None = None, store_name: str | None
 
         Notes
         -----
-        Implementations may also accept ``context`` (a dict carrying ``schema``,
-        ``table``, ``field`` and ``config``); DataJoint passes it only to codecs
-        whose signature declares it, so adding it is optional and omitting it
-        keeps a codec working unchanged. See :meth:`_codec_config`.
+        **Declare ``context`` as well**: ``encode(self, value, *, key=None,
+        context=None, store_name=None)``. It carries ``schema``, ``table``,
+        ``field`` and ``config`` — the calling connection's configuration, which
+        :meth:`_codec_config` reads and which store resolution needs.
+
+        Before 2.3.4 those four arrived inside ``key`` under underscore-prefixed
+        names. That path still works and DataJoint still populates it, so a codec
+        written against it keeps running — but it is deprecated and removed in
+        2.4. Write new codecs against ``context``.
         """
         ...
 
@@ -207,7 +212,8 @@ def decode(self, stored: Any, *, key: dict | None = None) -> Any:
 
         Notes
         -----
-        Implementations may also accept ``context``; see :meth:`encode`.
+        **Declare ``context`` as well**: ``decode(self, stored, *, key=None,
+        context=None)``. See :meth:`encode`.
         """
         ...
 

src/datajoint/heading.py

@@ -44,12 +44,12 @@ def get_dtype(self, is_store: bool) -> str:
             f"Codec <{self._codec_name}> is not registered. Define a Codec subclass with name='{self._codec_name}'."
         )
 
-    def encode(self, value, *, key=None, store_name=None):
+    def encode(self, value, *, key=None, context=None, store_name=None):
         raise DataJointError(
             f"Codec <{self._codec_name}> is not registered. Define a Codec subclass with name='{self._codec_name}'."
         )
 
-    def decode(self, stored, *, key=None):
+    def decode(self, stored, *, key=None, context=None):
         raise DataJointError(
             f"Codec <{self._codec_name}> is not registered. Define a Codec subclass with name='{self._codec_name}'."
         )

src/datajoint/spark.py

@@ -59,8 +59,8 @@ class SparkAdapter(Protocol):
         class FloatArrayCodec(dj.Codec):
             name = "float_array"
 
-            def encode(self, value, *, key=None, store_name=None): ...
-            def decode(self, stored, *, key=None) -> np.ndarray: ...
+            def encode(self, value, *, key=None, context=None, store_name=None): ...
+            def decode(self, stored, *, key=None, context=None) -> np.ndarray: ...
 
             def to_spark(self, decoded: np.ndarray, *, key=None) -> list[float]:
                 return decoded.tolist()  # → Spark ARRAY<DOUBLE>