langgraph-checkpoint 2.1.2__tar.gz → 3.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/PKG-INFO +6 -4
  2. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/README.md +3 -1
  3. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/base/__init__.py +17 -18
  4. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/memory/__init__.py +14 -14
  5. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/serde/base.py +6 -11
  6. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/serde/encrypted.py +2 -8
  7. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/serde/jsonplus.py +102 -130
  8. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/serde/types.py +2 -3
  9. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/store/base/__init__.py +146 -97
  10. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/store/base/batch.py +3 -3
  11. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/store/base/embed.py +9 -2
  12. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/store/memory/__init__.py +12 -7
  13. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/pyproject.toml +15 -7
  14. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/tests/test_jsonplus.py +88 -43
  15. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/tests/test_store.py +1 -1
  16. langgraph_checkpoint-3.0.1/uv.lock +1443 -0
  17. langgraph_checkpoint-2.1.2/uv.lock +0 -1493
  18. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/.gitignore +0 -0
  19. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/LICENSE +0 -0
  20. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/Makefile +0 -0
  21. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/cache/base/__init__.py +0 -0
  22. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/cache/base/py.typed +0 -0
  23. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/cache/memory/__init__.py +0 -0
  24. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/cache/redis/__init__.py +0 -0
  25. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/base/id.py +0 -0
  26. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/base/py.typed +0 -0
  27. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/memory/py.typed +0 -0
  28. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/serde/__init__.py +0 -0
  29. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/checkpoint/serde/py.typed +0 -0
  30. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/store/base/py.typed +0 -0
  31. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/langgraph/store/memory/py.typed +0 -0
  32. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/tests/__init__.py +0 -0
  33. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/tests/embed_test_utils.py +0 -0
  34. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/tests/test_memory.py +0 -0
  35. {langgraph_checkpoint-2.1.2 → langgraph_checkpoint-3.0.1}/tests/test_redis_cache.py +0 -0
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: langgraph-checkpoint
3
- Version: 2.1.2
3
+ Version: 3.0.1
4
4
  Summary: Library with base interfaces for LangGraph checkpoint savers.
5
5
  Project-URL: Repository, https://www.github.com/langchain-ai/langgraph
6
6
  License-Expression: MIT
7
7
  License-File: LICENSE
8
- Requires-Python: >=3.9
8
+ Requires-Python: >=3.10
9
9
  Requires-Dist: langchain-core>=0.2.38
10
- Requires-Dist: ormsgpack>=1.10.0
10
+ Requires-Dist: ormsgpack>=1.12.0
11
11
  Description-Content-Type: text/markdown
12
12
 
13
13
  # LangGraph Checkpoint
@@ -50,8 +50,10 @@ Each checkpointer should conform to `langgraph.checkpoint.base.BaseCheckpointSav
50
50
  - `.put_writes` - Store intermediate writes linked to a checkpoint (i.e. pending writes).
51
51
  - `.get_tuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `checkpoint_id`).
52
52
  - `.list` - List checkpoints that match a given configuration and filter criteria.
53
+ - `.delete_thread()` - Delete all checkpoints and writes associated with a thread.
54
+ - `.get_next_version()` - Generate the next version ID for a channel.
53
55
 
54
- If the checkpointer will be used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), checkpointer must implement asynchronous versions of the above methods (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`).
56
+ If the checkpointer will be used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), checkpointer must implement asynchronous versions of the above methods (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`). Similarly, the checkpointer must implement `.adelete_thread()` if asynchronous thread cleanup is desired. The base class provides a default implementation of `.get_next_version()` that generates an integer sequence starting from 1, but this method should be overridden for custom versioning schemes.
55
57
 
56
58
  ## Usage
57
59
 
@@ -38,8 +38,10 @@ Each checkpointer should conform to `langgraph.checkpoint.base.BaseCheckpointSav
38
38
  - `.put_writes` - Store intermediate writes linked to a checkpoint (i.e. pending writes).
39
39
  - `.get_tuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `checkpoint_id`).
40
40
  - `.list` - List checkpoints that match a given configuration and filter criteria.
41
+ - `.delete_thread()` - Delete all checkpoints and writes associated with a thread.
42
+ - `.get_next_version()` - Generate the next version ID for a channel.
41
43
 
42
- If the checkpointer will be used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), checkpointer must implement asynchronous versions of the above methods (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`).
44
+ If the checkpointer will be used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), checkpointer must implement asynchronous versions of the above methods (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`). Similarly, the checkpointer must implement `.adelete_thread()` if asynchronous thread cleanup is desired. The base class provides a default implementation of `.get_next_version()` that generates an integer sequence starting from 1, but this method should be overridden for custom versioning schemes.
43
45
 
44
46
  ## Usage
45
47
 
@@ -8,7 +8,6 @@ from typing import ( # noqa: UP035
8
8
  NamedTuple,
9
9
  TypedDict,
10
10
  TypeVar,
11
- Union,
12
11
  )
13
12
 
14
13
  from langchain_core.runnables import RunnableConfig
@@ -35,17 +34,17 @@ class CheckpointMetadata(TypedDict, total=False):
35
34
  source: Literal["input", "loop", "update", "fork"]
36
35
  """The source of the checkpoint.
37
36
 
38
- - "input": The checkpoint was created from an input to invoke/stream/batch.
39
- - "loop": The checkpoint was created from inside the pregel loop.
40
- - "update": The checkpoint was created from a manual state update.
41
- - "fork": The checkpoint was created as a copy of another checkpoint.
37
+ - `"input"`: The checkpoint was created from an input to invoke/stream/batch.
38
+ - `"loop"`: The checkpoint was created from inside the pregel loop.
39
+ - `"update"`: The checkpoint was created from a manual state update.
40
+ - `"fork"`: The checkpoint was created as a copy of another checkpoint.
42
41
  """
43
42
  step: int
44
43
  """The step number of the checkpoint.
45
44
 
46
- -1 for the first "input" checkpoint.
47
- 0 for the first "loop" checkpoint.
48
- ... for the nth checkpoint afterwards.
45
+ `-1` for the first `"input"` checkpoint.
46
+ `0` for the first `"loop"` checkpoint.
47
+ `...` for the `nth` checkpoint afterwards.
49
48
  """
50
49
  parents: dict[str, str]
51
50
  """The IDs of the parent checkpoints.
@@ -54,7 +53,7 @@ class CheckpointMetadata(TypedDict, total=False):
54
53
  """
55
54
 
56
55
 
57
- ChannelVersions = dict[str, Union[str, int, float]]
56
+ ChannelVersions = dict[str, str | int | float]
58
57
 
59
58
 
60
59
  class Checkpoint(TypedDict):
@@ -148,7 +147,7 @@ class BaseCheckpointSaver(Generic[V]):
148
147
  config: Configuration specifying which checkpoint to retrieve.
149
148
 
150
149
  Returns:
151
- Optional[Checkpoint]: The requested checkpoint, or None if not found.
150
+ The requested checkpoint, or `None` if not found.
152
151
  """
153
152
  if value := self.get_tuple(config):
154
153
  return value.checkpoint
@@ -160,7 +159,7 @@ class BaseCheckpointSaver(Generic[V]):
160
159
  config: Configuration specifying which checkpoint to retrieve.
161
160
 
162
161
  Returns:
163
- Optional[CheckpointTuple]: The requested checkpoint tuple, or None if not found.
162
+ The requested checkpoint tuple, or `None` if not found.
164
163
 
165
164
  Raises:
166
165
  NotImplementedError: Implement this method in your custom checkpoint saver.
@@ -184,7 +183,7 @@ class BaseCheckpointSaver(Generic[V]):
184
183
  limit: Maximum number of checkpoints to return.
185
184
 
186
185
  Returns:
187
- Iterator[CheckpointTuple]: Iterator of matching checkpoint tuples.
186
+ Iterator of matching checkpoint tuples.
188
187
 
189
188
  Raises:
190
189
  NotImplementedError: Implement this method in your custom checkpoint saver.
@@ -252,7 +251,7 @@ class BaseCheckpointSaver(Generic[V]):
252
251
  config: Configuration specifying which checkpoint to retrieve.
253
252
 
254
253
  Returns:
255
- Optional[Checkpoint]: The requested checkpoint, or None if not found.
254
+ The requested checkpoint, or `None` if not found.
256
255
  """
257
256
  if value := await self.aget_tuple(config):
258
257
  return value.checkpoint
@@ -264,7 +263,7 @@ class BaseCheckpointSaver(Generic[V]):
264
263
  config: Configuration specifying which checkpoint to retrieve.
265
264
 
266
265
  Returns:
267
- Optional[CheckpointTuple]: The requested checkpoint tuple, or None if not found.
266
+ The requested checkpoint tuple, or `None` if not found.
268
267
 
269
268
  Raises:
270
269
  NotImplementedError: Implement this method in your custom checkpoint saver.
@@ -288,7 +287,7 @@ class BaseCheckpointSaver(Generic[V]):
288
287
  limit: Maximum number of checkpoints to return.
289
288
 
290
289
  Returns:
291
- AsyncIterator[CheckpointTuple]: Async iterator of matching checkpoint tuples.
290
+ Async iterator of matching checkpoint tuples.
292
291
 
293
292
  Raises:
294
293
  NotImplementedError: Implement this method in your custom checkpoint saver.
@@ -353,11 +352,11 @@ class BaseCheckpointSaver(Generic[V]):
353
352
  def get_next_version(self, current: V | None, channel: None) -> V:
354
353
  """Generate the next version ID for a channel.
355
354
 
356
- Default is to use integer versions, incrementing by 1. If you override, you can use str/int/float versions,
357
- as long as they are monotonically increasing.
355
+ Default is to use integer versions, incrementing by `1`. If you override, you can use `str`/`int`/`float`
356
+ versions, as long as they are monotonically increasing.
358
357
 
359
358
  Args:
360
- current: The current version identifier (int, float, or str).
359
+ current: The current version identifier (`int`, `float`, or `str`).
361
360
  channel: Deprecated argument, kept for backwards compatibility.
362
361
 
363
362
  Returns:
@@ -39,10 +39,10 @@ class InMemorySaver(
39
39
  Only use `InMemorySaver` for debugging or testing purposes.
40
40
  For production use cases we recommend installing [langgraph-checkpoint-postgres](https://pypi.org/project/langgraph-checkpoint-postgres/) and using `PostgresSaver` / `AsyncPostgresSaver`.
41
41
 
42
- If you are using the LangGraph Platform, no checkpointer needs to be specified. The correct managed checkpointer will be used automatically.
42
+ If you are using LangSmith Deployment, no checkpointer needs to be specified. The correct managed checkpointer will be used automatically.
43
43
 
44
44
  Args:
45
- serde: The serializer to use for serializing and deserializing checkpoints. Defaults to None.
45
+ serde: The serializer to use for serializing and deserializing checkpoints.
46
46
 
47
47
  Examples:
48
48
 
@@ -133,7 +133,7 @@ class InMemorySaver(
133
133
  """Get a checkpoint tuple from the in-memory storage.
134
134
 
135
135
  This method retrieves a checkpoint tuple from the in-memory storage based on the
136
- provided config. If the config contains a "checkpoint_id" key, the checkpoint with
136
+ provided config. If the config contains a `checkpoint_id` key, the checkpoint with
137
137
  the matching thread ID and timestamp is retrieved. Otherwise, the latest checkpoint
138
138
  for the given thread ID is retrieved.
139
139
 
@@ -141,7 +141,7 @@ class InMemorySaver(
141
141
  config: The config to use for retrieving the checkpoint.
142
142
 
143
143
  Returns:
144
- Optional[CheckpointTuple]: The retrieved checkpoint tuple, or None if no matching checkpoint was found.
144
+ The retrieved checkpoint tuple, or None if no matching checkpoint was found.
145
145
  """
146
146
  thread_id: str = config["configurable"]["thread_id"]
147
147
  checkpoint_ns: str = config["configurable"].get("checkpoint_ns", "")
@@ -231,7 +231,7 @@ class InMemorySaver(
231
231
  limit: Maximum number of checkpoints to return.
232
232
 
233
233
  Yields:
234
- Iterator[CheckpointTuple]: An iterator of matching checkpoint tuples.
234
+ An iterator of matching checkpoint tuples.
235
235
  """
236
236
  thread_ids = (config["configurable"]["thread_id"],) if config else self.storage
237
237
  config_checkpoint_ns = (
@@ -423,16 +423,16 @@ class InMemorySaver(
423
423
  del self.blobs[k]
424
424
 
425
425
  async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
426
- """Asynchronous version of get_tuple.
426
+ """Asynchronous version of `get_tuple`.
427
427
 
428
- This method is an asynchronous wrapper around get_tuple that runs the synchronous
428
+ This method is an asynchronous wrapper around `get_tuple` that runs the synchronous
429
429
  method in a separate thread using asyncio.
430
430
 
431
431
  Args:
432
432
  config: The config to use for retrieving the checkpoint.
433
433
 
434
434
  Returns:
435
- Optional[CheckpointTuple]: The retrieved checkpoint tuple, or None if no matching checkpoint was found.
435
+ The retrieved checkpoint tuple, or None if no matching checkpoint was found.
436
436
  """
437
437
  return self.get_tuple(config)
438
438
 
@@ -444,16 +444,16 @@ class InMemorySaver(
444
444
  before: RunnableConfig | None = None,
445
445
  limit: int | None = None,
446
446
  ) -> AsyncIterator[CheckpointTuple]:
447
- """Asynchronous version of list.
447
+ """Asynchronous version of `list`.
448
448
 
449
- This method is an asynchronous wrapper around list that runs the synchronous
449
+ This method is an asynchronous wrapper around `list` that runs the synchronous
450
450
  method in a separate thread using asyncio.
451
451
 
452
452
  Args:
453
453
  config: The config to use for listing the checkpoints.
454
454
 
455
455
  Yields:
456
- AsyncIterator[CheckpointTuple]: An asynchronous iterator of checkpoint tuples.
456
+ An asynchronous iterator of checkpoint tuples.
457
457
  """
458
458
  for item in self.list(config, filter=filter, before=before, limit=limit):
459
459
  yield item
@@ -465,7 +465,7 @@ class InMemorySaver(
465
465
  metadata: CheckpointMetadata,
466
466
  new_versions: ChannelVersions,
467
467
  ) -> RunnableConfig:
468
- """Asynchronous version of put.
468
+ """Asynchronous version of `put`.
469
469
 
470
470
  Args:
471
471
  config: The config to associate with the checkpoint.
@@ -485,9 +485,9 @@ class InMemorySaver(
485
485
  task_id: str,
486
486
  task_path: str = "",
487
487
  ) -> None:
488
- """Asynchronous version of put_writes.
488
+ """Asynchronous version of `put_writes`.
489
489
 
490
- This method is an asynchronous wrapper around put_writes that runs the synchronous
490
+ This method is an asynchronous wrapper around `put_writes` that runs the synchronous
491
491
  method in a separate thread using asyncio.
492
492
 
493
493
  Args:
@@ -1,6 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
- from typing import Any, Protocol
3
+ from typing import Any, Protocol, runtime_checkable
4
4
 
5
5
 
6
6
  class UntypedSerializerProtocol(Protocol):
@@ -11,13 +11,14 @@ class UntypedSerializerProtocol(Protocol):
11
11
  def loads(self, data: bytes) -> Any: ...
12
12
 
13
13
 
14
- class SerializerProtocol(UntypedSerializerProtocol, Protocol):
14
+ @runtime_checkable
15
+ class SerializerProtocol(Protocol):
15
16
  """Protocol for serialization and deserialization of objects.
16
17
 
17
18
  - `dumps`: Serialize an object to bytes.
18
- - `dumps_typed`: Serialize an object to a tuple (type, bytes).
19
+ - `dumps_typed`: Serialize an object to a tuple `(type, bytes)`.
19
20
  - `loads`: Deserialize an object from bytes.
20
- - `loads_typed`: Deserialize an object from a tuple (type, bytes).
21
+ - `loads_typed`: Deserialize an object from a tuple `(type, bytes)`.
21
22
 
22
23
  Valid implementations include the `pickle`, `json` and `orjson` modules.
23
24
  """
@@ -31,12 +32,6 @@ class SerializerCompat(SerializerProtocol):
31
32
  def __init__(self, serde: UntypedSerializerProtocol) -> None:
32
33
  self.serde = serde
33
34
 
34
- def dumps(self, obj: Any) -> bytes:
35
- return self.serde.dumps(obj)
36
-
37
- def loads(self, data: bytes) -> Any:
38
- return self.serde.loads(data)
39
-
40
35
  def dumps_typed(self, obj: Any) -> tuple[str, bytes]:
41
36
  return type(obj).__name__, self.serde.dumps(obj)
42
37
 
@@ -49,7 +44,7 @@ def maybe_add_typed_methods(
49
44
  ) -> SerializerProtocol:
50
45
  """Wrap serde old serde implementations in a class with loads_typed and dumps_typed for backwards compatibility."""
51
46
 
52
- if not hasattr(serde, "loads_typed") or not hasattr(serde, "dumps_typed"):
47
+ if not isinstance(serde, SerializerProtocol):
53
48
  return SerializerCompat(serde)
54
49
 
55
50
  return serde
@@ -14,14 +14,8 @@ class EncryptedSerializer(SerializerProtocol):
14
14
  self.cipher = cipher
15
15
  self.serde = serde
16
16
 
17
- def dumps(self, obj: Any) -> bytes:
18
- return self.serde.dumps(obj)
19
-
20
- def loads(self, data: bytes) -> Any:
21
- return self.serde.loads(data)
22
-
23
17
  def dumps_typed(self, obj: Any) -> tuple[str, bytes]:
24
- """Serialize an object to a tuple (type, bytes) and encrypt the bytes."""
18
+ """Serialize an object to a tuple `(type, bytes)` and encrypt the bytes."""
25
19
  # serialize data
26
20
  typ, data = self.serde.dumps_typed(obj)
27
21
  # encrypt data
@@ -45,7 +39,7 @@ class EncryptedSerializer(SerializerProtocol):
45
39
  def from_pycryptodome_aes(
46
40
  cls, serde: SerializerProtocol = JsonPlusSerializer(), **kwargs: Any
47
41
  ) -> "EncryptedSerializer":
48
- """Create an EncryptedSerializer using AES encryption."""
42
+ """Create an `EncryptedSerializer` using AES encryption."""
49
43
  try:
50
44
  from Crypto.Cipher import AES # type: ignore
51
45
  except ImportError:
@@ -4,12 +4,13 @@ import dataclasses
4
4
  import decimal
5
5
  import importlib
6
6
  import json
7
+ import logging
7
8
  import pathlib
8
9
  import pickle
9
10
  import re
10
11
  import sys
11
12
  from collections import deque
12
- from collections.abc import Sequence
13
+ from collections.abc import Callable, Sequence
13
14
  from datetime import date, datetime, time, timedelta, timezone
14
15
  from enum import Enum
15
16
  from inspect import isclass
@@ -21,13 +22,12 @@ from ipaddress import (
21
22
  IPv6Interface,
22
23
  IPv6Network,
23
24
  )
24
- from typing import Any, Callable, cast
25
+ from typing import Any, Literal
25
26
  from uuid import UUID
26
27
  from zoneinfo import ZoneInfo
27
28
 
28
29
  import ormsgpack
29
30
  from langchain_core.load.load import Reviver
30
- from langchain_core.load.serializable import Serializable
31
31
 
32
32
  from langgraph.checkpoint.serde.base import SerializerProtocol
33
33
  from langgraph.checkpoint.serde.types import SendProtocol
@@ -35,18 +35,31 @@ from langgraph.store.base import Item
35
35
 
36
36
  LC_REVIVER = Reviver()
37
37
  EMPTY_BYTES = b""
38
+ logger = logging.getLogger(__name__)
38
39
 
39
40
 
40
41
  class JsonPlusSerializer(SerializerProtocol):
41
- """Serializer that uses ormsgpack, with a fallback to extended JSON serializer."""
42
+ """Serializer that uses ormsgpack, with optional fallbacks.
43
+
44
+ Security note: this serializer is intended for use within the BaseCheckpointSaver
45
+ class and called within the Pregel loop. It should not be used on untrusted
46
+ python objects. If an attacker can write directly to your checkpoint database,
47
+ they may be able to trigger code execution when data is deserialized.
48
+ """
42
49
 
43
50
  def __init__(
44
51
  self,
45
52
  *,
46
53
  pickle_fallback: bool = False,
54
+ allowed_json_modules: Sequence[tuple[str, ...]] | Literal[True] | None = None,
47
55
  __unpack_ext_hook__: Callable[[int, bytes], Any] | None = None,
48
56
  ) -> None:
49
57
  self.pickle_fallback = pickle_fallback
58
+ self._allowed_modules = (
59
+ {mod_and_name for mod_and_name in allowed_json_modules}
60
+ if allowed_json_modules and allowed_json_modules is not True
61
+ else (allowed_json_modules if allowed_json_modules is True else None)
62
+ )
50
63
  self._unpack_ext_hook = (
51
64
  __unpack_ext_hook__
52
65
  if __unpack_ext_hook__ is not None
@@ -74,134 +87,90 @@ class JsonPlusSerializer(SerializerProtocol):
74
87
  out["kwargs"] = kwargs
75
88
  return out
76
89
 
77
- def _default(self, obj: Any) -> str | dict[str, Any]:
78
- if isinstance(obj, Serializable):
79
- return cast(dict[str, Any], obj.to_json())
80
- elif hasattr(obj, "model_dump") and callable(obj.model_dump):
81
- return self._encode_constructor_args(
82
- obj.__class__, method=(None, "model_construct"), kwargs=obj.model_dump()
83
- )
84
- elif hasattr(obj, "dict") and callable(obj.dict):
85
- return self._encode_constructor_args(
86
- obj.__class__, method=(None, "construct"), kwargs=obj.dict()
87
- )
88
- elif hasattr(obj, "_asdict") and callable(obj._asdict):
89
- return self._encode_constructor_args(obj.__class__, kwargs=obj._asdict())
90
- elif isinstance(obj, pathlib.Path):
91
- return self._encode_constructor_args(pathlib.Path, args=obj.parts)
92
- elif isinstance(obj, re.Pattern):
93
- return self._encode_constructor_args(
94
- re.compile, args=(obj.pattern, obj.flags)
95
- )
96
- elif isinstance(obj, UUID):
97
- return self._encode_constructor_args(UUID, args=(obj.hex,))
98
- elif isinstance(obj, decimal.Decimal):
99
- return self._encode_constructor_args(decimal.Decimal, args=(str(obj),))
100
- elif isinstance(obj, (set, frozenset, deque)):
101
- return self._encode_constructor_args(type(obj), args=(tuple(obj),))
102
- elif isinstance(obj, (IPv4Address, IPv4Interface, IPv4Network)):
103
- return self._encode_constructor_args(obj.__class__, args=(str(obj),))
104
- elif isinstance(obj, (IPv6Address, IPv6Interface, IPv6Network)):
105
- return self._encode_constructor_args(obj.__class__, args=(str(obj),))
106
-
107
- elif isinstance(obj, datetime):
108
- return self._encode_constructor_args(
109
- datetime, method="fromisoformat", args=(obj.isoformat(),)
110
- )
111
- elif isinstance(obj, timezone):
112
- return self._encode_constructor_args(
113
- timezone,
114
- args=obj.__getinitargs__(), # type: ignore[attr-defined]
115
- )
116
- elif isinstance(obj, ZoneInfo):
117
- return self._encode_constructor_args(ZoneInfo, args=(obj.key,))
118
- elif isinstance(obj, timedelta):
119
- return self._encode_constructor_args(
120
- timedelta, args=(obj.days, obj.seconds, obj.microseconds)
121
- )
122
- elif isinstance(obj, date):
123
- return self._encode_constructor_args(
124
- date, args=(obj.year, obj.month, obj.day)
125
- )
126
- elif isinstance(obj, time):
127
- return self._encode_constructor_args(
128
- time,
129
- args=(obj.hour, obj.minute, obj.second, obj.microsecond, obj.tzinfo),
130
- kwargs={"fold": obj.fold},
131
- )
132
- elif dataclasses.is_dataclass(obj):
133
- return self._encode_constructor_args(
134
- obj.__class__,
135
- kwargs={
136
- field.name: getattr(obj, field.name)
137
- for field in dataclasses.fields(obj)
138
- },
139
- )
140
- elif isinstance(obj, Enum):
141
- return self._encode_constructor_args(obj.__class__, args=(obj.value,))
142
- elif isinstance(obj, SendProtocol):
143
- return self._encode_constructor_args(
144
- obj.__class__, kwargs={"node": obj.node, "arg": obj.arg}
145
- )
146
- elif isinstance(obj, (bytes, bytearray)):
147
- return self._encode_constructor_args(
148
- obj.__class__, method="fromhex", args=(obj.hex(),)
149
- )
150
- elif isinstance(obj, BaseException):
151
- return repr(obj)
152
- else:
153
- raise TypeError(
154
- f"Object of type {obj.__class__.__name__} is not JSON serializable"
155
- )
156
-
157
90
  def _reviver(self, value: dict[str, Any]) -> Any:
158
- if (
91
+ if self._allowed_modules and (
159
92
  value.get("lc", None) == 2
160
93
  and value.get("type", None) == "constructor"
161
94
  and value.get("id", None) is not None
162
95
  ):
163
96
  try:
164
- # Get module and class name
165
- [*module, name] = value["id"]
166
- # Import module
167
- mod = importlib.import_module(".".join(module))
168
- # Import class
169
- cls = getattr(mod, name)
170
- # Instantiate class
171
- method = value.get("method")
172
- if isinstance(method, str):
173
- methods = [getattr(cls, method)]
174
- elif isinstance(method, list):
175
- methods = [
176
- cls if method is None else getattr(cls, method)
177
- for method in method
178
- ]
179
- else:
180
- methods = [cls]
181
- args = value.get("args")
182
- kwargs = value.get("kwargs")
183
- for method in methods:
184
- try:
185
- if isclass(method) and issubclass(method, BaseException):
186
- return None
187
- if args and kwargs:
188
- return method(*args, **kwargs)
189
- elif args:
190
- return method(*args)
191
- elif kwargs:
192
- return method(**kwargs)
193
- else:
194
- return method()
195
- except Exception:
196
- continue
197
- except Exception:
198
- return None
97
+ return self._revive_lc2(value)
98
+ except InvalidModuleError as e:
99
+ logger.warning(
100
+ "Object %s is not in the deserialization allowlist.\n%s",
101
+ value["id"],
102
+ e.message,
103
+ )
199
104
 
200
105
  return LC_REVIVER(value)
201
106
 
202
- def dumps(self, obj: Any) -> bytes:
203
- return json.dumps(obj, default=self._default, ensure_ascii=False).encode(
204
- "utf-8", "ignore"
107
+ def _revive_lc2(self, value: dict[str, Any]) -> Any:
108
+ self._check_allowed_modules(value)
109
+
110
+ [*module, name] = value["id"]
111
+ try:
112
+ mod = importlib.import_module(".".join(module))
113
+ cls = getattr(mod, name)
114
+ method = value.get("method")
115
+ if isinstance(method, str):
116
+ methods = [getattr(cls, method)]
117
+ elif isinstance(method, list):
118
+ methods = [cls if m is None else getattr(cls, m) for m in method]
119
+ else:
120
+ methods = [cls]
121
+ args = value.get("args")
122
+ kwargs = value.get("kwargs")
123
+ for method in methods:
124
+ try:
125
+ if isclass(method) and issubclass(method, BaseException):
126
+ return None
127
+ if args and kwargs:
128
+ return method(*args, **kwargs)
129
+ elif args:
130
+ return method(*args)
131
+ elif kwargs:
132
+ return method(**kwargs)
133
+ else:
134
+ return method()
135
+ except Exception:
136
+ continue
137
+ except Exception:
138
+ return None
139
+
140
+ def _check_allowed_modules(self, value: dict[str, Any]) -> None:
141
+ needed = tuple(value["id"])
142
+ method = value.get("method")
143
+ if isinstance(method, list):
144
+ method_display = ",".join(m or "<init>" for m in method)
145
+ elif isinstance(method, str):
146
+ method_display = method
147
+ else:
148
+ method_display = "<init>"
149
+
150
+ dotted = ".".join(needed)
151
+ if not self._allowed_modules:
152
+ raise InvalidModuleError(
153
+ f"Refused to deserialize JSON constructor: {dotted} (method: {method_display}). "
154
+ "No allowed_json_modules configured.\n\n"
155
+ "Unblock with ONE of:\n"
156
+ f" • JsonPlusSerializer(allowed_json_modules=[{needed!r}, ...])\n"
157
+ " • (DANGEROUS) JsonPlusSerializer(allowed_json_modules=True)\n\n"
158
+ "Note: Prefix allowlists are intentionally unsupported; prefer exact symbols "
159
+ "or plain-JSON representations revived without import-time side effects."
160
+ )
161
+
162
+ if self._allowed_modules is True:
163
+ return
164
+ if needed in self._allowed_modules:
165
+ return
166
+
167
+ raise InvalidModuleError(
168
+ f"Refused to deserialize JSON constructor: {dotted} (method: {method_display}). "
169
+ "Symbol is not in the deserialization allowlist.\n\n"
170
+ "Add exactly this symbol to unblock:\n"
171
+ f" JsonPlusSerializer(allowed_json_modules=[{needed!r}, ...])\n"
172
+ "Or, as a last resort (DANGEROUS):\n"
173
+ " JsonPlusSerializer(allowed_json_modules=True)"
205
174
  )
206
175
 
207
176
  def dumps_typed(self, obj: Any) -> tuple[str, bytes]:
@@ -215,15 +184,10 @@ class JsonPlusSerializer(SerializerProtocol):
215
184
  try:
216
185
  return "msgpack", _msgpack_enc(obj)
217
186
  except ormsgpack.MsgpackEncodeError as exc:
218
- if "valid UTF-8" in str(exc):
219
- return "json", self.dumps(obj)
220
- elif self.pickle_fallback:
187
+ if self.pickle_fallback:
221
188
  return "pickle", pickle.dumps(obj)
222
189
  raise exc
223
190
 
224
- def loads(self, data: bytes) -> Any:
225
- return json.loads(data, object_hook=self._reviver)
226
-
227
191
  def loads_typed(self, data: tuple[str, bytes]) -> Any:
228
192
  type_, data_ = data
229
193
  if type_ == "null":
@@ -233,7 +197,7 @@ class JsonPlusSerializer(SerializerProtocol):
233
197
  elif type_ == "bytearray":
234
198
  return bytearray(data_)
235
199
  elif type_ == "json":
236
- return self.loads(data_)
200
+ return json.loads(data_, object_hook=self._reviver)
237
201
  elif type_ == "msgpack":
238
202
  return ormsgpack.unpackb(
239
203
  data_, ext_hook=self._unpack_ext_hook, option=ormsgpack.OPT_NON_STR_KEYS
@@ -663,12 +627,20 @@ def _msgpack_ext_hook_to_json(code: int, data: bytes) -> Any:
663
627
  return
664
628
 
665
629
 
630
+ class InvalidModuleError(Exception):
631
+ """Exception raised when a module is not in the allowlist."""
632
+
633
+ def __init__(self, message: str):
634
+ self.message = message
635
+
636
+
666
637
  _option = (
667
638
  ormsgpack.OPT_NON_STR_KEYS
668
639
  | ormsgpack.OPT_PASSTHROUGH_DATACLASS
669
640
  | ormsgpack.OPT_PASSTHROUGH_DATETIME
670
641
  | ormsgpack.OPT_PASSTHROUGH_ENUM
671
642
  | ormsgpack.OPT_PASSTHROUGH_UUID
643
+ | ormsgpack.OPT_REPLACE_SURROGATES
672
644
  )
673
645
 
674
646
 
@@ -1,7 +1,6 @@
1
1
  from collections.abc import Sequence
2
2
  from typing import (
3
3
  Any,
4
- Optional,
5
4
  Protocol,
6
5
  TypeVar,
7
6
  runtime_checkable,
@@ -28,9 +27,9 @@ class ChannelProtocol(Protocol[Value, Update, C]):
28
27
  @property
29
28
  def UpdateType(self) -> Any: ...
30
29
 
31
- def checkpoint(self) -> Optional[C]: ...
30
+ def checkpoint(self) -> C | None: ...
32
31
 
33
- def from_checkpoint(self, checkpoint: Optional[C]) -> Self: ...
32
+ def from_checkpoint(self, checkpoint: C | None) -> Self: ...
34
33
 
35
34
  def update(self, values: Sequence[Update]) -> bool: ...
36
35