From 371584a2c0108ec0bb9827fe53f0b65c0cfa67a8 Mon Sep 17 00:00:00 2001 From: Thomas Calmant Date: Tue, 11 Aug 2026 23:30:32 +0200 Subject: [PATCH] Bumped version to 0.6.0 and documented V3 in the README Every module still said __version_info__ = (0, 4, 4) while pyproject.toml already said 0.5.0; all version declarations (module tuples, docstring fields, pyproject.toml, setup.py) now agree on 0.6.0. Also closed the biggest V3 documentation gaps: automatic Java collection to Python type conversion, catching javaobj.v3.exceptions, and the parser/writer logger names were never mentioned. Signed-off-by: Thomas Calmant --- README.md | 67 +++++++++++++++++++++++++++++++++++++- javaobj/__init__.py | 4 +-- javaobj/constants.py | 4 +-- javaobj/modifiedutf8.py | 4 +-- javaobj/utils.py | 4 +-- javaobj/v1/__init__.py | 4 +-- javaobj/v1/beans.py | 4 +-- javaobj/v1/core.py | 4 +-- javaobj/v1/marshaller.py | 4 +-- javaobj/v1/transformers.py | 2 +- javaobj/v1/unmarshaller.py | 4 +-- javaobj/v2/__init__.py | 4 +-- javaobj/v2/api.py | 4 +-- javaobj/v2/beans.py | 4 +-- javaobj/v2/core.py | 4 +-- javaobj/v2/main.py | 2 +- javaobj/v2/stream.py | 4 +-- javaobj/v2/transformers.py | 4 +-- javaobj/v3/__init__.py | 4 +-- javaobj/v3/_compat.py | 4 +-- javaobj/v3/beans.py | 4 +-- javaobj/v3/exceptions.py | 4 +-- javaobj/v3/parser.py | 4 +-- javaobj/v3/reader.py | 4 +-- javaobj/v3/transformers.py | 4 +-- javaobj/v3/writer.py | 4 +-- pyproject.toml | 2 +- setup.py | 4 +-- tests/test_v1.py | 2 +- tests/test_v2.py | 2 +- tests/test_v3.py | 2 +- 31 files changed, 120 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 78f126b..c7d086f 100644 --- 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 index ebd99ed..0caebb4 100644 --- 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 index d23f1e1..45ec4de 100644 --- 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 index d6f5181..990eae7 100644 --- 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 index e86046d..45d76d1 100644 --- 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 index db03c7a..49399d3 100644 --- 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 index d9cf1d6..0a15e86 100644 --- 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 index 489ce9e..8953442 100644 --- 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 index 87dbcd5..368b5f3 100644 --- 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 index 4b04cd1..d92fbee 100644 --- 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 index 344fe45..ad2da25 100644 --- 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 index f9591d6..56508ca 100644 --- 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 index 0792dab..f1bbf81 100644 --- 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 index 748a9d2..a89a5c3 100644 --- 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 index 82b7ede..6d89120 100644 --- 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 index 51710ab..27303c4 100644 --- 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 index 988f4d7..f8f4777 100644 --- 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 index 872ad4f..2852530 100644 --- 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 index acb5137..e5e02d5 100644 --- 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 diff --git a/javaobj/v3/_compat.py b/javaobj/v3/_compat.py index 427d3a7..926554d 100644 --- a/javaobj/v3/_compat.py +++ b/javaobj/v3/_compat.py @@ -4,7 +4,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, 5, 0) +__version_info__ = (0, 6, 0) __version__ = ".".join(str(x) for x in __version_info__) # Documentation strings format diff --git a/javaobj/v3/beans.py b/javaobj/v3/beans.py index 78f8d47..1e678c0 100644 --- a/javaobj/v3/beans.py +++ b/javaobj/v3/beans.py @@ -4,7 +4,7 @@ :authors: Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha .. @@ -36,7 +36,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 diff --git a/javaobj/v3/exceptions.py b/javaobj/v3/exceptions.py index cf61ff6..7d33c60 100644 --- a/javaobj/v3/exceptions.py +++ b/javaobj/v3/exceptions.py @@ -4,7 +4,7 @@ :authors: Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha .. @@ -27,7 +27,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 diff --git a/javaobj/v3/parser.py b/javaobj/v3/parser.py index 534eb45..be95ba4 100644 --- a/javaobj/v3/parser.py +++ b/javaobj/v3/parser.py @@ -4,7 +4,7 @@ :authors: 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, 5, 0) +__version_info__ = (0, 6, 0) __version__ = ".".join(str(x) for x in __version_info__) # Documentation strings format diff --git a/javaobj/v3/reader.py b/javaobj/v3/reader.py index 80819ae..a3cf8a0 100644 --- a/javaobj/v3/reader.py +++ b/javaobj/v3/reader.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, 5, 0) +__version_info__ = (0, 6, 0) __version__ = ".".join(str(x) for x in __version_info__) # Documentation strings format diff --git a/javaobj/v3/transformers.py b/javaobj/v3/transformers.py index 2d1c6b9..c08ca9b 100644 --- a/javaobj/v3/transformers.py +++ b/javaobj/v3/transformers.py @@ -4,7 +4,7 @@ :authors: Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha .. @@ -46,7 +46,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 diff --git a/javaobj/v3/writer.py b/javaobj/v3/writer.py index 9dbf538..17af69a 100644 --- a/javaobj/v3/writer.py +++ b/javaobj/v3/writer.py @@ -8,7 +8,7 @@ :authors: Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha .. @@ -54,7 +54,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 diff --git a/pyproject.toml b/pyproject.toml index a564a3e..bb9aa17 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ packages = ["javaobj"] [project] name = "javaobj-py3" -version = "0.5.0" +version = "0.6.0" description = "Module for serializing and de-serializing Java objects." readme = "README.md" license = "Apache-2.0" diff --git a/setup.py b/setup.py index c5052dd..b0e5b86 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ :authors: Volodymyr Buell, 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/tests/test_v1.py b/tests/test_v1.py index 4679815..4ac2305 100644 --- a/tests/test_v1.py +++ b/tests/test_v1.py @@ -8,7 +8,7 @@ :authors: Volodymyr Buell, Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha .. diff --git a/tests/test_v2.py b/tests/test_v2.py index 2a48dcb..3a86daa 100644 --- a/tests/test_v2.py +++ b/tests/test_v2.py @@ -8,7 +8,7 @@ :authors: Volodymyr Buell, Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha .. diff --git a/tests/test_v3.py b/tests/test_v3.py index 183d679..0db1c81 100644 --- a/tests/test_v3.py +++ b/tests/test_v3.py @@ -4,7 +4,7 @@ :authors: Thomas Calmant :license: Apache License 2.0 -:version: 0.5.0 +:version: 0.6.0 :status: Alpha ..