tcalmant · tcalmant · Aug 11, 2026 · Aug 11, 2026
diff --git a/README.md b/README.md
@@ -113,7 +113,8 @@ You can find a sample usage in the *Custom Transformer* section in this file.
 * Automatic conversion of Java Collections to python ones
   (`HashMap` => `dict`, `ArrayList` => `list`, etc.)
 * Basic marshalling of simple Java objects (`v1` implementation)
-* Full marshalling of Java object streams (`v3` implementation)
+* Full un-marshalling **and** marshalling of Java object streams, with typed
+  errors and configurable safety limits (`v3` implementation)
 * Automatically uncompresses GZipped files
 
 ## Requirements
@@ -536,6 +537,24 @@ value = pobj.get_field("myField")
 value = pobj.myField
 ```
 
+### Automatic type conversion (V3)
+
+`javaobj.v3`'s default transformer converts the most common Java standard
+library classes into their natural Python equivalent:
+
+| Java class | Python type |
+|---|---|
+| `java.lang.Boolean` | `bool` |
+| `java.lang.Integer`, `java.lang.Long` | `int` |
+| `java.util.ArrayList`, `java.util.LinkedList` | `list` |
+| `java.util.HashMap`, `java.util.TreeMap`, `java.util.LinkedHashMap` | `dict` |
+| `java.util.HashSet`, `java.util.LinkedHashSet`, `java.util.TreeSet` | `set` |
+| `java.time.*` (via `java.time.Ser`) | the matching `datetime`/`date`/`time` type |
+
+Any other class falls back to a generic `JavaInstance`, accessed through
+`get_field()` as shown above. Provide your own `ObjectTransformer` (see
+"Object Transformer V3" below) to handle additional classes.
+
 ### New features in V3
 
 | Feature | V1 | V2 | V3 |
@@ -567,6 +586,41 @@ with open("untrusted.ser", "rb") as fd:
     )
 ```
 
+### Error handling (V3)
+
+`javaobj.v3.exceptions` defines a typed hierarchy so callers can catch
+exactly what they expect instead of a bare `Exception`:
+
+```python
+import javaobj.v3 as javaobj
+from javaobj.v3.exceptions import JavaObjError, ParseError, SecurityError
+
+with open("obj5.ser", "rb") as fd:
+    try:
+        pobj = javaobj.load(fd)
+    except SecurityError:
+        # A max_depth or max_array_size limit was exceeded
+        ...
+    except ParseError as e:
+        # The stream does not follow the protocol; e.offset is the byte
+        # offset in the stream where the error occurred, or -1 if unknown
+        print(e, "at offset", e.offset)
+    except JavaObjError:
+        # Catch-all base class for everything else javaobj.v3 raises
+        ...
+```
+
+* `JavaObjError` -- base class for every exception `javaobj.v3` raises.
+* `ParseError` -- the stream cannot be decoded according to the protocol;
+  carries an `.offset` attribute.
+  * `UnexpectedOpcodeError` -- a `ParseError` subclass raised when an opcode
+    byte is not among the values expected at that point; carries `.expected`
+    (a tuple of acceptable values) and `.got`.
+* `UnsupportedFeatureError` -- the stream uses a protocol feature `v3` does
+  not implement yet (for example `Externalizable` objects on read).
+* `SecurityError` -- a configured `max_depth`/`max_array_size` limit was
+  exceeded (see "Security limits" above).
+
 ### Object Transformer V3
 
 The `ObjectTransformer` base class in `v3` has the same three override points
@@ -769,6 +823,17 @@ alice = JavaInstance(
 data = javaobj.dumps(alice)
 ```
 
+### Logging (V3)
+
+The parser and the writer log through the standard `logging` module, under
+`javaobj.v3.parser` and `javaobj.v3.writer` respectively:
+
+```python
+import logging
+
+logging.getLogger("javaobj.v3").setLevel(logging.DEBUG)
+```
+
 ---
 
 ## Migration to V3

diff --git a/javaobj/__init__.py b/javaobj/__init__.py
@@ -13,7 +13,7 @@
 
 :authors: Volodymyr Buell, Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -41,7 +41,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/constants.py b/javaobj/constants.py
@@ -4,7 +4,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -38,7 +38,7 @@
 )
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/modifiedutf8.py b/javaobj/modifiedutf8.py
@@ -11,14 +11,14 @@
 
 :authors: Scott Stephens (@swstephe), @guywithface
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 """
 
 import sys
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/utils.py b/javaobj/utils.py
@@ -7,7 +7,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -43,7 +43,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v1/__init__.py b/javaobj/v1/__init__.py
@@ -4,7 +4,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -37,7 +37,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v1/beans.py b/javaobj/v1/beans.py
@@ -5,7 +5,7 @@
 
 :authors: Volodymyr Buell, Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -44,7 +44,7 @@
 )
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v1/core.py b/javaobj/v1/core.py
@@ -13,7 +13,7 @@
 
 :authors: Volodymyr Buell, Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -62,7 +62,7 @@
 )
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v1/marshaller.py b/javaobj/v1/marshaller.py
@@ -13,7 +13,7 @@
 
 :authors: Volodymyr Buell, Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -76,7 +76,7 @@
 
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v1/transformers.py b/javaobj/v1/transformers.py
@@ -5,7 +5,7 @@
 
 :authors: Volodymyr Buell, Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..

diff --git a/javaobj/v1/unmarshaller.py b/javaobj/v1/unmarshaller.py
@@ -13,7 +13,7 @@
 
 :authors: Volodymyr Buell, Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -73,7 +73,7 @@
 __all__ = ("JavaObjectUnmarshaller",)
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/__init__.py b/javaobj/v2/__init__.py
@@ -15,7 +15,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -41,7 +41,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/api.py b/javaobj/v2/api.py
@@ -4,7 +4,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -39,7 +39,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/beans.py b/javaobj/v2/beans.py
@@ -4,7 +4,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -37,7 +37,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/core.py b/javaobj/v2/core.py
@@ -5,7 +5,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -70,7 +70,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/main.py b/javaobj/v2/main.py
@@ -22,7 +22,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/stream.py b/javaobj/v2/stream.py
@@ -4,7 +4,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -35,7 +35,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v2/transformers.py b/javaobj/v2/transformers.py
@@ -4,7 +4,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -48,7 +48,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 4, 4)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format

diff --git a/javaobj/v3/__init__.py b/javaobj/v3/__init__.py
@@ -7,7 +7,7 @@
 
 :authors: Thomas Calmant
 :license: Apache License 2.0
-:version: 0.5.0
+:version: 0.6.0
 :status: Alpha
 
 ..
@@ -108,7 +108,7 @@
 # ------------------------------------------------------------------------------
 
 # Module version
-__version_info__ = (0, 5, 0)
+__version_info__ = (0, 6, 0)
 __version__ = ".".join(str(x) for x in __version_info__)
 
 # Documentation strings format