diff --git a/.flake8 b/.flake8 new file mode 100644 index 0000000..a6578a3 --- /dev/null +++ b/.flake8 @@ -0,0 +1,2 @@ +[flake8] +extend-ignore = E501 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..8e0c942 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,27 @@ +name: Tests + +on: + - push + - pull_request + +jobs: + build: + + runs-on: ubuntu-20.04 + strategy: + fail-fast: false + matrix: + python-version: ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "pypy2.7", "pypy3.9"] + + steps: + - uses: actions/checkout@v3 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install tox tox-gh-actions + - name: Test with tox + run: tox diff --git a/.gitignore b/.gitignore index 2b225f4..200d697 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ dist/ .tox/ .cache/ .pytest_cache/ +docs/_build diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..f334b70 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 0b6e534..0000000 --- a/.travis.yml +++ /dev/null @@ -1,22 +0,0 @@ -sudo: false -dist: xenial -language: python -install: pip install tox -script: tox - -matrix: - include: - - python: 2.7 - env: TOXENV=py27 - - python: 3.5 - env: TOXENV=py35 - - python: 3.6 - env: TOXENV=py36 - - python: 3.7 - env: TOXENV=py37 - - python: 3.8 - env: TOXENV=py38 - - python: pypy2.7-6.0 - env: TOXENV=pypy - - python: pypy3.5-6.0 - env: TOXENV=pypy3 diff --git a/CHANGELOG.md b/CHANGELOG.md index 355e351..3cb131b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,18 @@ +* Version 2.8.0 - 05/18/2023 + * Migrate module to package. + * Migrate documentation to Sphinx. + * Improve types and formatting in docstrings. + * Add type stubs. + +* Version 2.7.2 - 11/07/2022 + * Fix hex formatting of data bytes in Ext string representation. + * Contributors + * Stefan Ring, @Ringdingcoder - 309b1a9 + +* Version 2.7.1 - 10/24/2020 + * Add Ext type value validation to Ext class and `ext_serializable()` decorator. + * Change string formatting from `%` to `.format()` throughout codebase. + * Version 2.7.0 - 08/01/2020 * Add support for packing subclasses of `ext_serializable()` application classes. * Contributors diff --git a/LICENSE b/LICENSE index ba6591c..79056ac 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ - Copyright (c) 2013-2020 vsergeev / Ivan (Vanya) A. Sergeev + Copyright (c) 2013-2023 vsergeev / Ivan (Vanya) A. Sergeev Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index e8a6a7f..485a60b 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# u-msgpack-python [![Build Status](https://travis-ci.org/vsergeev/u-msgpack-python.svg?branch=master)](https://travis-ci.org/vsergeev/u-msgpack-python) [![GitHub release](https://img.shields.io/github/release/vsergeev/u-msgpack-python.svg?maxAge=7200)](https://github.com/vsergeev/u-msgpack-python) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/vsergeev/u-msgpack-python/blob/master/LICENSE) +# u-msgpack-python [![Tests Status](https://github.com/vsergeev/u-msgpack-python/actions/workflows/tests.yml/badge.svg)](https://github.com/vsergeev/u-msgpack-python/actions/workflows/tests.yml) [![Docs Status](https://readthedocs.org/projects/u-msgpack-python/badge/)](https://u-msgpack-python.readthedocs.io/en/latest/) [![GitHub release](https://img.shields.io/github/release/vsergeev/u-msgpack-python.svg?maxAge=7200)](https://github.com/vsergeev/u-msgpack-python) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/vsergeev/u-msgpack-python/blob/master/LICENSE) -u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, compatible with both Python 2 and 3, as well CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md). In particular, it supports the new binary, UTF-8 string, application-defined ext, and timestamp types. +u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, compatible with Python 2 and 3, as well CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md). In particular, it supports the new binary, UTF-8 string, application-defined ext, and timestamp types. -u-msgpack-python is currently distributed on [PyPI](https://pypi.python.org/pypi/u-msgpack-python) and as a single file: [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py). +u-msgpack-python is currently distributed as a package on [PyPI](https://pypi.python.org/pypi/u-msgpack-python) and as a single file module. ## Installation @@ -16,9 +16,9 @@ With easy_install: $ easy_install u-msgpack-python ``` -or simply drop [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) into your project! +or simply drop `umsgpack.py` into your project! ``` text -$ wget https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py +$ wget https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack/__init__.py -O umsgpack.py ``` ## Examples @@ -64,14 +64,14 @@ Streaming serialization with file-like objects: Serializing and deserializing a raw Ext type: ``` python ->>> # Create an Ext object with type 0x05 and data b"\x01\x02\x03" -... foo = umsgpack.Ext(0x05, b"\x01\x02\x03") +>>> # Create an Ext object with type 5 and data b"\x01\x02\x03" +... foo = umsgpack.Ext(5, b"\x01\x02\x03") >>> umsgpack.packb({u"stuff": foo, u"awesome": True}) b'\x82\xa5stuff\xc7\x03\x05\x01\x02\x03\xa7awesome\xc3' >>> >>> bar = umsgpack.unpackb(_) >>> print(bar['stuff']) -Ext Object (Type: 0x05, Data: 0x01 0x02 0x03) +Ext Object (Type: 5, Data: 0x01 0x02 0x03) >>> bar['stuff'].type 5 >>> bar['stuff'].data @@ -130,373 +130,20 @@ b'\x82\xa7compact\xc3\xa6schema\x00' >>> ``` -## Ext Serializable +## Documentation -The `ext_serializable()` decorator registers application classes for automatic -packing and unpacking with the specified Ext type. The decorator accepts the -Ext type code as an argument. The application class should implement a -`packb()` method that returns serialized bytes, and an `unpackb()` class method -or static method that accepts serialized bytes and returns an instance of the -application class. +Documentation is hosted at [https://u-msgpack-python.readthedocs.io](https://u-msgpack-python.readthedocs.io). -Example for registering, packing, and unpacking a custom class with Ext type -code 0x10: +To build documentation locally with Sphinx, run: -``` python -@umsgpack.ext_serializable(0x10) -class Point(object): - def __init__(self, x, y, z): - self.x = x - self.y = y - self.z = z - - def __str__(self): - return "Point({}, {}, {})".format(self.x, self.y, self.z) - - def packb(self): - return struct.pack(">iii", self.x, self.y, self.z) - - @staticmethod - def unpackb(data): - return Point(*struct.unpack(">iii", data)) - -# Pack -obj = Point(1,2,3) -data = umsgpack.packb(obj) - -# Unpack -obj = umsgpack.unpackb(data) -print(obj) # -> Point(1, 2, 3) -``` - -## Ext Handlers - -The packing functions accept an optional `ext_handlers` dictionary that maps -custom types to callables that pack the type into an Ext object. The callable -should accept the custom type object as an argument and return a packed -`umsgpack.Ext` object. - -Example for packing `set`, `complex`, and `decimal.Decimal` types into Ext -objects with type codes 0x20, 0x30, and 0x40, respectively: - -``` python ->>> umsgpack.packb([1, True, {"foo", 2}, complex(3, 4), decimal.Decimal("0.31")], -... ext_handlers = { -... set: lambda obj: umsgpack.Ext(0x20, umsgpack.packb(list(obj))), -... complex: lambda obj: umsgpack.Ext(0x30, struct.pack("ff", obj.real, obj.imag)), -... decimal.Decimal: lambda obj: umsgpack.Ext(0x40, str(obj).encode()), -... }) -b'\x95\x01\xc3\xc7\x06 \x92\xa3foo\x02\xd70\x00\x00@@\x00\x00\x80@\xd6@0.31' ->>> -``` -Similarly, the unpacking functions accept an optional `ext_handlers` dictionary -that maps Ext type codes to callables that unpack the Ext into a custom object. -The callable should accept a `umsgpack.Ext` object as an argument and return an -unpacked custom type object. - -Example for unpacking Ext objects with type codes 0x20, 0x30, and 0x40, into -`set`, `complex`, and `decimal.Decimal` typed objects, respectively: - -``` python ->>> umsgpack.unpackb(b'\x95\x01\xc3\xc7\x06 \x92\xa3foo\x02\xd70\x00\x00@@\x00\x00\x80@\xd6@0.31', -... ext_handlers = { -... 0x20: lambda ext: set(umsgpack.unpackb(ext.data)), -... 0x30: lambda ext: complex(*struct.unpack("ff", ext.data)), -... 0x40: lambda ext: decimal.Decimal(ext.data.decode()), -... }) -[1, True, {'foo', 2}, (3+4j), Decimal('0.31')] ->>> -``` - -Example for packing and unpacking a custom class: - -``` python -class Point(object): - def __init__(self, x, y, z): - self.x = x - self.y = y - self.z = z - - def __str__(self): - return "Point({}, {}, {})".format(self.x, self.y, self.z) - - def pack(self): - return struct.pack(">iii", self.x, self.y, self.z) - - @staticmethod - def unpack(data): - return Point(*struct.unpack(">iii", data)) - -# Pack -obj = Point(1,2,3) -data = umsgpack.packb(obj, ext_handlers = {Point: lambda obj: umsgpack.Ext(0x10, obj.pack())}) - -# Unpack -obj = umsgpack.unpackb(data, ext_handlers = {0x10: lambda ext: Point.unpack(ext.data)}) -print(obj) # -> Point(1, 2, 3) -``` - -## Streaming Serialization and Deserialization - -The streaming `pack()`/`dump()` and `unpack()`/`load()` functions allow packing and unpacking objects directly to and from a stream, respectively. Streaming may be necessary when unpacking serialized bytes whose size is unknown in advance, or it may be more convenient and efficient when working directly with stream objects (e.g. files or stream sockets). - -`pack(obj, fp)` / `dump(obj, fp)` serialize Python object `obj` to a `.write()` supporting file-like object `fp`. - -``` python ->>> class Foo: -... def write(self, data): -... # write 'data' bytes -... pass -... ->>> f = Foo() ->>> umsgpack.pack({u"compact": True, u"schema": 0}, f) ->>> -``` - -`unpack(fp)` / `load(fp)` deserialize a Python object from a `.read()` supporting file-like object `fp`. - -``` python ->>> class Bar: -... def read(self, n): -... # read and return 'n' number of bytes -... return b"\x01"*n -... ->>> f = Bar() ->>> umsgpack.unpack(f) -1 ->>> -``` - -## Options - -### Ordered Dictionaries - -The unpacking functions provide a `use_ordered_dict` option to unpack MessagePack maps into the `collections.OrderedDict` type, rather than the unordered `dict` type, to preserve the order of deserialized MessagePack maps. - -``` python ->>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00') -{'compact': True, 'schema': 0} ->>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00', use_ordered_dict=True) -OrderedDict([('compact', True), ('schema', 0)]) ->>> ``` - -## Tuples - -The unpacking functions provide a `use_tuple` option to unpack MessagePack arrays into tuples, rather than lists. - -``` python ->>> umsgpack.unpackb(b'\x93\xa1a\xc3\x92\x01\x92\x02\x03') -['a', True, [1, [2, 3]]] ->>> umsgpack.unpackb(b'\x93\xa1a\xc3\x92\x01\x92\x02\x03', use_tuple=True) -('a', True, (1, (2, 3))) ->>> +cd docs +make html ``` -### Invalid UTF-8 Strings - -The unpacking functions provide an `allow_invalid_utf8` option to unpack MessagePack strings with invalid UTF-8 into the `umsgpack.InvalidString` type, instead of throwing an exception. The `umsgpack.InvalidString` type is a subclass of `bytes`, and can be used like any other `bytes` object. - -``` python ->>> # Attempt to unpack invalid UTF-8 string -... umsgpack.unpackb(b'\xa4\x80\x01\x02\x03') -... -umsgpack.InvalidStringException: unpacked string is invalid utf-8 ->>> umsgpack.unpackb(b'\xa4\x80\x01\x02\x03', allow_invalid_utf8=True) -b'\x80\x01\x02\x03' ->>> -``` - -### Float Precision - -The packing functions provide a `force_float_precision` option to force packing of floats into the specified precision: `"single"` for IEEE-754 single-precision floats, or `"double"` for IEEE-754 double-precision floats. - -``` python ->>> # Force float packing to single-precision floats -... umsgpack.packb(2.5, force_float_precision="single") -b'\xca@ \x00\x00' ->>> # Force float packing to double-precision floats -... umsgpack.packb(2.5, force_float_precision="double") -b'\xcb@\x04\x00\x00\x00\x00\x00\x00' ->>> -``` - -### Old Specification Compatibility Mode - -The compatibility mode supports the "raw" bytes MessagePack type from the [old specification](https://github.com/msgpack/msgpack/blob/master/spec-old.md). When the module-wide `compatibility` option is enabled, both unicode strings and bytes will be serialized into the "raw" MessagePack type, and the "raw" MessagePack type will be deserialized into bytes. - -``` python ->>> umsgpack.compatibility = True ->>> ->>> umsgpack.packb([u"some string", b"some bytes"]) -b'\x92\xabsome string\xaasome bytes' ->>> umsgpack.unpackb(_) -[b'some string', b'some bytes'] ->>> -``` - -## Exceptions - -### Packing Exceptions - -If an error occurs during packing, umsgpack will raise an exception derived from `umsgpack.PackException`. All possible packing exceptions are described below. - -* `UnsupportedTypeException`: Object type not supported for packing. - - ``` python - >>> # Attempt to pack set type - ... umsgpack.packb(set([1,2,3])) - ... - umsgpack.UnsupportedTypeException: unsupported type: - >>> - - >>> # Attempt to pack > 64-bit unsigned int - ... umsgpack.packb(2**64) - ... - umsgpack.UnsupportedTypeException: huge unsigned int - >>> - ``` - -* `NotImplementedError`: Ext serializable class is missing implementation of `packb()`. - - ``` python - >>> @umsgpack.ext_serializable(0x50) - ... class Point(collections.namedtuple('Point', ['x', 'y'])): - ... pass - ... - >>> umsgpack.packb(Point(1, 2)) - ... - NotImplementedError: Ext serializable class is missing implementation of packb() - >>> - ``` - -### Unpacking Exceptions - -If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a `TypeError` exception. If an error occurs during unpacking, umsgpack will raise an exception derived from `umsgpack.UnpackException`. All possible unpacking exceptions are described below. - -* `TypeError`: Packed data is not type `str` (Python 2), or not type `bytes` (Python 3). - - ``` python - # Attempt to unpack non-str type data in Python 2 - >>> umsgpack.unpackb(u"no good") - ... - TypeError: expected packed data as type 'str' - >>> - - # Attempt to unpack non-bytes type data in Python 3 - >>> umsgpack.unpackb("no good") - ... - TypeError: expected packed data as type 'bytes' - >>> - ``` - -* `InsufficientDataException`: Insufficient data to unpack the serialized object. - - ``` python - # Attempt to unpack a cut-off serialized 32-bit unsigned int - >>> umsgpack.unpackb(b"\xce\xff\xff\xff") - ... - umsgpack.InsufficientDataException - >>> - - # Attempt to unpack an array of length 2 missing the second item - >>> umsgpack.unpackb(b"\x92\xc2") - ... - umsgpack.InsufficientDataException - >>> - - ``` -* `InvalidStringException`: Invalid UTF-8 string encountered during unpacking. - - String bytes are strictly decoded with UTF-8. This exception is thrown if - UTF-8 decoding of string bytes fails. Use the `allow_invalid_utf8` option - to unpack invalid MessagePack strings into byte strings. - - ``` python - # Attempt to unpack invalid UTF-8 string - >>> umsgpack.unpackb(b"\xa2\x80\x81") - ... - umsgpack.InvalidStringException: unpacked string is invalid utf-8 - >>> - ``` - -* `UnsupportedTimestampException`: Unsupported timestamp encountered during unpacking. - - The official timestamp extension type supports 32-bit, 64-bit and 96-bit - formats. This exception is thrown if a timestamp extension type with an - unsupported format is encountered. - - ``` python - # Attempt to unpack invalid timestamp - >>> umsgpack.unpackb(b"\xd5\xff\x01\x02") - ... - umsgpack.UnsupportedTimestampException: unsupported timestamp with data length 2 - >>> - ``` - -* `ReservedCodeException`: Reserved code encountered during unpacking. - - ``` python - # Attempt to unpack reserved code 0xc1 - >>> umsgpack.unpackb(b"\xc1") - ... - umsgpack.ReservedCodeException: reserved code encountered: 0xc1 - >>> - ``` - -* `UnhashableKeyException`: Unhashable key encountered during map unpacking. The packed map cannot be unpacked into a Python dictionary. - - Python dictionaries only support keys that are instances of `collections.Hashable`, so while the map `{ { u'abc': True } : 5 }` has a MessagePack serialization, it cannot be unpacked into a valid Python dictionary. - - ``` python - # Attempt to unpack { {} : False } - >>> umsgpack.unpackb(b"\x82\x80\xc2") - ... - umsgpack.UnhashableKeyException: encountered unhashable key type: {}, - >>> - ``` - -* `DuplicateKeyException`: Duplicate key encountered during map unpacking. - - Python dictionaries do not support duplicate keys, but MessagePack maps may be serialized with duplicate keys. - - ``` python - # Attempt to unpack { 1: True, 1: False } - >>> umsgpack.unpackb(b"\x82\x01\xc3\x01\xc2") - ... - umsgpack.DuplicateKeyException: encountered duplicate key: 1, - >>> - ``` - -* `NotImplementedError`: Ext serializable class is missing implementation of `unpackb()`. - - ``` python - >>> @umsgpack.ext_serializable(0x50) - ... class Point(collections.namedtuple('Point', ['x', 'y'])): - ... pass - ... - >>> umsgpack.unpackb(b'\xd7\x50\x00\x00\x00\x01\x00\x00\x00\x02') - ... - NotImplementedError: Ext serializable class is missing implementation of unpackb() - >>> - ``` - -## Behavior Notes +Sphinx will produce the HTML documentation in `docs/_build/html/`. -* Python 2 - * `unicode` type objects are packed into, and unpacked from, the msgpack `string` format - * `str` type objects are packed into, and unpacked from, the msgpack `binary` format -* Python 3 - * `str` type objects are packed into, and unpacked from, the msgpack `string` format - * `bytes` type objects are packed into, and unpacked from, the msgpack `binary` format -* The msgpack string format is strictly decoded with UTF-8 — an exception is thrown if the string bytes cannot be decoded into a valid UTF-8 string, unless the `allow_invalid_utf8` option is enabled -* The msgpack array format is unpacked into a Python list, unless it is the key of a map, in which case it is unpacked into a Python tuple -* Python tuples and lists are both packed into the msgpack array format -* Python float types are packed into the msgpack float32 or float64 format depending on the system's `sys.float_info` -* The Python `datetime.datetime` type is packed into, and unpacked from, the msgpack `timestamp` format - * Note that this Python type only supports microsecond resolution, while the msgpack `timestamp` format supports nanosecond resolution. Timestamps with finer than microsecond resolution will lose precision during unpacking. Users may override the packing and unpacking of the msgpack `timestamp` format with a custom type for alternate behavior. - * Both naive and aware timestamp are supported. Naive timestamps are packed as if they are in the UTC timezone. Timestamps are always unpacked as aware `datetime.datetime` objects in the UTC timezone. -* Ext type handlers specified in the optional `ext_handlers` dictionary will override `ext_serializable()` classes during packing and unpacking +Run `make help` to see other output targets (LaTeX, man, text, etc.). ## Testing diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..d53f6d4 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,105 @@ +# API + +## Packing + +```{eval-rst} +.. autofunction:: umsgpack.packb + +Also available under the ``umsgpack.dumps()`` alias. +``` + +```{eval-rst} +.. autofunction:: umsgpack.pack + +Also available under the ``umsgpack.dump()`` alias. +``` + +## Unpacking + +```{eval-rst} +.. autofunction:: umsgpack.unpackb + +Also available under the ``umsgpack.loads()`` alias. +``` + +```{eval-rst} +.. autofunction:: umsgpack.unpack + +Also available under the ``umsgpack.load()`` alias. +``` + +## Packing Exceptions + +```{eval-rst} +.. autoexception:: umsgpack.PackException +``` + +```{eval-rst} +.. autoexception:: umsgpack.UnsupportedTypeException +``` + +## Unpacking Exceptions + +```{eval-rst} +.. autoexception:: umsgpack.UnpackException +``` + +```{eval-rst} +.. autoexception:: umsgpack.InsufficientDataException +``` + +```{eval-rst} +.. autoexception:: umsgpack.InvalidStringException +``` + +```{eval-rst} +.. autoexception:: umsgpack.UnsupportedTimestampException +``` + +```{eval-rst} +.. autoexception:: umsgpack.ReservedCodeException +``` + +```{eval-rst} +.. autoexception:: umsgpack.UnhashableKeyException +``` + +```{eval-rst} +.. autoexception:: umsgpack.DuplicateKeyException +``` + +## Ext Class + +```{eval-rst} +.. autoclass:: umsgpack.Ext + :member-order: bysource + :special-members: __init__, __eq__, __ne__, __str__, __hash__ +``` + +## Ext Serializable Decorator + +```{eval-rst} +.. autodecorator:: umsgpack.ext_serializable +``` + +## Invalid String Class + +```{eval-rst} +.. autoclass:: umsgpack.InvalidString +``` + +## Attributes + +```{eval-rst} +.. autodata:: umsgpack.compatibility +``` + +## Constants + +```{eval-rst} +.. autodata:: umsgpack.version +``` + +```{eval-rst} +.. autodata:: umsgpack.__version__ +``` diff --git a/docs/behavior-notes.md b/docs/behavior-notes.md new file mode 100644 index 0000000..25474ee --- /dev/null +++ b/docs/behavior-notes.md @@ -0,0 +1,33 @@ +# Behavior Notes + +* Python 2 + * `unicode` type objects are packed into, and unpacked from, the MessagePack + `string` format + * `str` type objects are packed into, and unpacked from, the MessagePack + `binary` format +* Python 3 + * `str` type objects are packed into, and unpacked from, the MessagePack + `string` format + * `bytes` type objects are packed into, and unpacked from, the MessagePack + `binary` format +* The MessagePack string format is strictly decoded with UTF-8 — an exception + is thrown if the string bytes cannot be decoded into a valid UTF-8 string, + unless the `allow_invalid_utf8` option is enabled +* The MessagePack array format is unpacked into a Python list, unless it is the + key of a map, in which case it is unpacked into a Python tuple +* Python tuples and lists are both packed into the MessagePack array format +* Python float types are packed into the MessagePack float32 or float64 format + depending on the system's `sys.float_info` +* The Python `datetime.datetime` type is packed into, and unpacked from, the + MessagePack `timestamp` format + * Note that the Python `datetime.datetime` type only supports microsecond + resolution, while the MessagePack `timestamp` format supports nanosecond + resolution. Timestamps with finer than microsecond resolution will lose + precision during unpacking. Users may override the packing and unpacking + of the MessagePack `timestamp` format with a custom type for alternate + behavior. + * Both naive and aware timestamp are supported. Naive timestamps are packed + as if they are in the UTC timezone. Timestamps are always unpacked as + aware `datetime.datetime` objects in the UTC timezone. +* Ext type handlers specified in the optional `ext_handlers` dictionary will + override `ext_serializable()` classes during packing and unpacking diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..6958620 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,47 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys +sys.path.insert(0, os.path.abspath('..')) + +import umsgpack + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'u-msgpack-python' +copyright = '2013-2023, Vanya A. Sergeev' +author = 'Vanya A. Sergeev' +release = '2.8.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx_rtd_theme', + 'myst_parser', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build'] + +pygments_style = 'sphinx' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] +html_show_sourcelink = False diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..6d63f8c --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,117 @@ +# Examples + +Basic Example: + +``` python +>>> import umsgpack +>>> umsgpack.packb({u"compact": True, u"schema": 0}) +b'\x82\xa7compact\xc3\xa6schema\x00' +>>> umsgpack.unpackb(_) +{u'compact': True, u'schema': 0} +>>> +``` + +A more complicated example: + +``` python +>>> umsgpack.packb([1, True, False, 0xffffffff, {u"foo": b"\x80\x01\x02", \ +... u"bar": [1,2,3, {u"a": [1,2,3,{}]}]}, -1, 2.12345]) +b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3foo\xc4\x03\x80\x01\ +\x02\xa3bar\x94\x01\x02\x03\x81\xa1a\x94\x01\x02\x03\x80\xff\xcb\ +@\x00\xfc\xd3Z\x85\x87\x94' +>>> umsgpack.unpackb(_) +[1, True, False, 4294967295, {u'foo': b'\x80\x01\x02', \ + u'bar': [1, 2, 3, {u'a': [1, 2, 3, {}]}]}, -1, 2.12345] +>>> +``` + +Streaming serialization with file-like objects: + +``` python +>>> f = open('test.bin', 'wb') +>>> umsgpack.pack({u"compact": True, u"schema": 0}, f) +>>> umsgpack.pack([1,2,3], f) +>>> f.close() +>>> +>>> f = open('test.bin', 'rb') +>>> umsgpack.unpack(f) +{u'compact': True, u'schema': 0} +>>> umsgpack.unpack(f) +[1, 2, 3] +>>> f.close() +>>> +``` + +Serializing and deserializing a raw Ext type: + +``` python +>>> # Create an Ext object with type 5 and data b"\x01\x02\x03" +... foo = umsgpack.Ext(5, b"\x01\x02\x03") +>>> umsgpack.packb({u"stuff": foo, u"awesome": True}) +b'\x82\xa5stuff\xc7\x03\x05\x01\x02\x03\xa7awesome\xc3' +>>> +>>> bar = umsgpack.unpackb(_) +>>> print(bar['stuff']) +Ext Object (Type: 5, Data: 0x01 0x02 0x03) +>>> bar['stuff'].type +5 +>>> bar['stuff'].data +b'\x01\x02\x03' +>>> +``` + +Serializing and deserializing application-defined types with + +`ext_serializable()`: +``` python +>>> @umsgpack.ext_serializable(0x50) +... class Point(collections.namedtuple('Point', ['x', 'y'])): +... def packb(self): +... return struct.pack(">ii", self.x, self.y) +... @staticmethod +... def unpackb(data): +... return Point(*struct.unpack(">ii", data)) +... +>>> umsgpack.packb(Point(1, 2)) +b'\xd7P\x00\x00\x00\x01\x00\x00\x00\x02' +>>> umsgpack.unpackb(_) +Point(x=1, y=2) +>>> +``` + +Serializing and deserializing application-defined types with Ext handlers: + +``` python +>>> umsgpack.packb([complex(1,2), decimal.Decimal("0.31")], +... ext_handlers = { +... complex: lambda obj: umsgpack.Ext(0x30, struct.pack("ff", obj.real, obj.imag)), +... decimal.Decimal: lambda obj: umsgpack.Ext(0x40, str(obj).encode()), +... }) +b'\x92\xd70\x00\x00\x80?\x00\x00\x00@\xd6@0.31' +>>> umsgpack.unpackb(_, +... ext_handlers = { +... 0x30: lambda ext: complex(*struct.unpack("ff", ext.data)), +... 0x40: lambda ext: decimal.Decimal(ext.data.decode()), +... }) +[(1+2j), Decimal('0.31')] +>>> +``` + +Python standard library style names `dump`, `dumps`, `load`, `loads` are also +available: + +``` python +>>> umsgpack.dumps({u"compact": True, u"schema": 0}) +b'\x82\xa7compact\xc3\xa6schema\x00' +>>> umsgpack.loads(_) +{u'compact': True, u'schema': 0} +>>> +>>> f = open('test.bin', 'wb') +>>> umsgpack.dump({u"compact": True, u"schema": 0}, f) +>>> f.close() +>>> +>>> f = open('test.bin', 'rb') +>>> umsgpack.load(f) +{u'compact': True, u'schema': 0} +>>> +``` diff --git a/docs/extension.md b/docs/extension.md new file mode 100644 index 0000000..c967809 --- /dev/null +++ b/docs/extension.md @@ -0,0 +1,111 @@ +# Extension Types + +u-msgpack-python supports two mechanisms for packing and unpacking MessagePack +Ext types: the `ext_handlers` keyword option, and the `ext_serializable()` +decorator. + +## Ext Handlers + +The packing functions accept an optional `ext_handlers` dictionary that maps +custom types to callables that pack the type into an Ext object. The callable +should accept the custom type object as an argument and return a packed +`umsgpack.Ext` object. + +Example for packing `set`, `complex`, and `decimal.Decimal` types into Ext +objects with type codes 0x20, 0x30, and 0x40, respectively: + +``` python +>>> umsgpack.packb([1, True, {"foo", 2}, complex(3, 4), decimal.Decimal("0.31")], +... ext_handlers = { +... set: lambda obj: umsgpack.Ext(0x20, umsgpack.packb(list(obj))), +... complex: lambda obj: umsgpack.Ext(0x30, struct.pack("ff", obj.real, obj.imag)), +... decimal.Decimal: lambda obj: umsgpack.Ext(0x40, str(obj).encode()), +... }) +b'\x95\x01\xc3\xc7\x06 \x92\xa3foo\x02\xd70\x00\x00@@\x00\x00\x80@\xd6@0.31' +>>> +``` +Similarly, the unpacking functions accept an optional `ext_handlers` dictionary +that maps Ext type codes to callables that unpack the Ext into a custom object. +The callable should accept a `umsgpack.Ext` object as an argument and return an +unpacked custom type object. + +Example for unpacking Ext objects with type codes 0x20, 0x30, and 0x40, into +`set`, `complex`, and `decimal.Decimal` typed objects, respectively: + +``` python +>>> umsgpack.unpackb(b'\x95\x01\xc3\xc7\x06 \x92\xa3foo\x02\xd70\x00\x00@@\x00\x00\x80@\xd6@0.31', +... ext_handlers = { +... 0x20: lambda ext: set(umsgpack.unpackb(ext.data)), +... 0x30: lambda ext: complex(*struct.unpack("ff", ext.data)), +... 0x40: lambda ext: decimal.Decimal(ext.data.decode()), +... }) +[1, True, {'foo', 2}, (3+4j), Decimal('0.31')] +>>> +``` + +Example for packing and unpacking a custom class: + +``` python +class Point(object): + def __init__(self, x, y, z): + self.x = x + self.y = y + self.z = z + + def __str__(self): + return "Point({}, {}, {})".format(self.x, self.y, self.z) + + def pack(self): + return struct.pack(">iii", self.x, self.y, self.z) + + @staticmethod + def unpack(data): + return Point(*struct.unpack(">iii", data)) + +# Pack +obj = Point(1,2,3) +data = umsgpack.packb(obj, ext_handlers = {Point: lambda obj: umsgpack.Ext(0x10, obj.pack())}) + +# Unpack +obj = umsgpack.unpackb(data, ext_handlers = {0x10: lambda ext: Point.unpack(ext.data)}) +print(obj) # -> Point(1, 2, 3) +``` + +## Ext Serializable + +The `ext_serializable()` decorator registers application classes for automatic +packing and unpacking with the specified Ext type. The decorator accepts the +Ext type code as an argument. The application class should implement a +`packb()` method that returns serialized bytes, and an `unpackb()` class method +or static method that accepts serialized bytes and returns an instance of the +application class. + +Example for registering, packing, and unpacking a custom class with Ext type +code 0x10: + +``` python +@umsgpack.ext_serializable(0x10) +class Point(object): + def __init__(self, x, y, z): + self.x = x + self.y = y + self.z = z + + def __str__(self): + return "Point({}, {}, {})".format(self.x, self.y, self.z) + + def packb(self): + return struct.pack(">iii", self.x, self.y, self.z) + + @staticmethod + def unpackb(data): + return Point(*struct.unpack(">iii", data)) + +# Pack +obj = Point(1,2,3) +data = umsgpack.packb(obj) + +# Unpack +obj = umsgpack.unpackb(data) +print(obj) # -> Point(1, 2, 3) +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f18f8ff --- /dev/null +++ b/docs/index.md @@ -0,0 +1,28 @@ +# Welcome to u-msgpack-python's documentation! + +[u-msgpack-python](https://github.com/vsergeev/u-msgpack-python) is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, compatible with Python 2 and 3, as well CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md). In particular, it supports the new binary, UTF-8 string, application-defined ext, and timestamp types. + +u-msgpack-python is currently distributed as a package on [PyPI](https://pypi.python.org/pypi/u-msgpack-python) and as a single file module. + +## Contents + + +```{toctree} +:maxdepth: 1 + +Home +installation.md +examples.md +packing.md +unpacking.md +streaming.md +extension.md +api.md +behavior-notes.md +license.md +``` + +## Indices and tables + +* [](genindex) +* [](search) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..8651fd6 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,19 @@ +# Installation + +Install with pip: + +``` text +$ pip install u-msgpack-python +``` + +Install with easy_install: + +``` text +$ easy_install u-msgpack-python +``` + +or simply drop `umsgpack.py` into your project! + +``` text +$ wget https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack/__init__.py -O umsgpack.py +``` diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..9594f3e --- /dev/null +++ b/docs/license.md @@ -0,0 +1,3 @@ +# License + +u-msgpack-python is MIT licensed. See the included [`LICENSE`](https://raw.github.com/vsergeev/u-msgpack-python/master/LICENSE) file for more details. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/packing.md b/docs/packing.md new file mode 100644 index 0000000..b5293db --- /dev/null +++ b/docs/packing.md @@ -0,0 +1,103 @@ +# Packing + +## Example + +``` python +>>> umsgpack.packb([1, True, False, 0xffffffff, {'foo': b'\x80\x01\x02', \ +... 'bar': [1,2,3, {'a': [1,2,3,{}]}]}, -1, 2.12345]) +b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3foo\xc4\x03\x80\x01\ +\x02\xa3bar\x94\x01\x02\x03\x81\xa1a\x94\x01\x02\x03\x80\xff\xcb\ +@\x00\xfc\xd3Z\x85\x87\x94' +>>> +``` + +## API + +```{eval-rst} +.. autofunction:: umsgpack.packb + :noindex: + +Also available under the ``umsgpack.dumps()`` alias. +``` + +## Options + +### Ext Handlers + +See the [Extension Types](extension.md) section. + +### Float Precision + +The packing functions provide a `force_float_precision` option to force packing +of floats into the specified precision: `"single"` for IEEE-754 +single-precision floats, or `"double"` for IEEE-754 double-precision floats. + +``` python +>>> # Force float packing to single-precision floats +... umsgpack.packb(2.5, force_float_precision="single") +b'\xca@ \x00\x00' +>>> # Force float packing to double-precision floats +... umsgpack.packb(2.5, force_float_precision="double") +b'\xcb@\x04\x00\x00\x00\x00\x00\x00' +>>> +``` + +### Old Specification Compatibility Mode + +The compatibility mode supports the "raw" bytes MessagePack type from the [old +specification](https://github.com/msgpack/msgpack/blob/master/spec-old.md). +When the module-wide `compatibility` attribute is enabled, both unicode strings +and bytes will be serialized into the "raw" MessagePack type, and the "raw" +MessagePack type will be deserialized into bytes. + +``` python +>>> umsgpack.compatibility = True +>>> +>>> umsgpack.packb([u"some string", b"some bytes"]) +b'\x92\xabsome string\xaasome bytes' +>>> umsgpack.unpackb(_) +[b'some string', b'some bytes'] +>>> +``` + +## Exceptions + +If an error occurs during packing, u-msgpack-python will raise an exception +derived from `umsgpack.PackException`. Possible packing exceptions are +described below. + +### UnsupportedTypeException + +```{eval-rst} +.. autoexception:: umsgpack.UnsupportedTypeException + :noindex: +``` + +``` python +>>> # Attempt to pack set type +... umsgpack.packb(set([1,2,3])) +... +umsgpack.UnsupportedTypeException: unsupported type: +>>> + +>>> # Attempt to pack > 64-bit unsigned int +... umsgpack.packb(2**64) +... +umsgpack.UnsupportedTypeException: huge unsigned int +>>> +``` + +### NotImplementedError + +Ext serializable class is missing implementation of `packb()`. + +``` python +>>> @umsgpack.ext_serializable(0x50) +... class Point(collections.namedtuple('Point', ['x', 'y'])): +... pass +... +>>> umsgpack.packb(Point(1, 2)) +... +NotImplementedError: Ext serializable class is missing implementation of packb() +>>> +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..7c98d98 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx-rtd-theme>=1.2.0 +myst-parser diff --git a/docs/streaming.md b/docs/streaming.md new file mode 100644 index 0000000..2e30fdc --- /dev/null +++ b/docs/streaming.md @@ -0,0 +1,54 @@ +# Streaming + +The streaming `pack()` and `unpack()` functions allow packing and unpacking +objects directly to and from a stream, respectively. Streaming may be necessary +when unpacking serialized bytes whose size is unknown in advance, or it may be +more convenient and efficient when working directly with stream objects (e.g. +files or stream sockets). + +## Packing + +`pack(obj, fp)` serializes Python object `obj` to a `.write()` supporting +file-like object `fp`. + +``` python +>>> class Foo: +... def write(self, data): +... # write 'data' bytes +... pass +... +>>> f = Foo() +>>> umsgpack.pack({u"compact": True, u"schema": 0}, f) +>>> +``` + +```{eval-rst} +.. autofunction:: umsgpack.pack + :noindex: + +Also available under the ``umsgpack.dump()`` alias. +``` + +## Unpacking + +`unpack(fp)` deserializes a Python object from a `.read()` supporting file-like +object `fp`. + +``` python +>>> class Bar: +... def read(self, n): +... # read and return 'n' number of bytes +... return b"\x01"*n +... +>>> f = Bar() +>>> umsgpack.unpack(f) +1 +>>> +``` + +```{eval-rst} +.. autofunction:: umsgpack.unpack + :noindex: + +Also available under the ``umsgpack.load()`` alias. +``` diff --git a/docs/unpacking.md b/docs/unpacking.md new file mode 100644 index 0000000..43ccf94 --- /dev/null +++ b/docs/unpacking.md @@ -0,0 +1,225 @@ +# Unpacking + +## Example + +``` python +>>> umsgpack.unpackb(b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3\ +foo\xc4\x03\x80\x01\x02\xa3bar\x94\x01\x02\x03\x81\xa1a\x94\x01\x02\ +\x03\x80\xff\xcb@\x00\xfc\xd3Z\x85\x87\x94') +[1, True, False, 4294967295, {'foo': b'\x80\x01\x02', \ + 'bar': [1, 2, 3, {u'a': [1, 2, 3, {}]}]}, -1, 2.12345] +>>> +``` + +## API + +```{eval-rst} +.. autofunction:: umsgpack.unpackb + :noindex: + +Also available under the ``umsgpack.loads()`` alias. +``` + +## Options + +### Ext Handlers + +See the [Extension Types](extension.md) section. + +### Ordered Dictionaries + +The unpacking functions provide a `use_ordered_dict` option to unpack +MessagePack maps into the `collections.OrderedDict` type, rather than the +unordered `dict` type, to preserve the order of deserialized MessagePack maps. +Note that as of Python 3.6, dictionaries are insertion ordered by default. + +``` python +>>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00') +{'compact': True, 'schema': 0} +>>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00', use_ordered_dict=True) +OrderedDict([('compact', True), ('schema', 0)]) +>>> +``` + +### Tuples + +The unpacking functions provide a `use_tuple` option to unpack MessagePack +arrays into tuples, rather than lists. + +``` python +>>> umsgpack.unpackb(b'\x93\xa1a\xc3\x92\x01\x92\x02\x03') +['a', True, [1, [2, 3]]] +>>> umsgpack.unpackb(b'\x93\xa1a\xc3\x92\x01\x92\x02\x03', use_tuple=True) +('a', True, (1, (2, 3))) +>>> +``` + +### Invalid UTF-8 Strings + +The unpacking functions provide an `allow_invalid_utf8` option to unpack +MessagePack strings with invalid UTF-8 into the `umsgpack.InvalidString` type, +instead of throwing an exception. The `umsgpack.InvalidString` type is a +subclass of `bytes`, and can be used like any other `bytes` object. + +``` python +>>> # Attempt to unpack invalid UTF-8 string +... umsgpack.unpackb(b'\xa4\x80\x01\x02\x03') +... +umsgpack.InvalidStringException: unpacked string is invalid utf-8 +>>> umsgpack.unpackb(b'\xa4\x80\x01\x02\x03', allow_invalid_utf8=True) +b'\x80\x01\x02\x03' +>>> +``` + +## Exceptions + +If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise +a `TypeError` exception. If an error occurs during unpacking, u-msgpack-python +will raise an exception derived from `umsgpack.UnpackException`. Possible +unpacking exceptions are described below. + + +### TypeError + +Packed data is not type `str` (Python 2), or not type `bytes` (Python 3). + +``` python +# Attempt to unpack non-str type data in Python 2 +>>> umsgpack.unpackb(u"no good") +... +TypeError: expected packed data as type 'str' +>>> + +# Attempt to unpack non-bytes type data in Python 3 +>>> umsgpack.unpackb("no good") +... +TypeError: expected packed data as type 'bytes' +>>> +``` + +### InsufficientDataException + +```{eval-rst} +.. autoexception:: umsgpack.InsufficientDataException + :noindex: +``` + +``` python +# Attempt to unpack a cut-off serialized 32-bit unsigned int +>>> umsgpack.unpackb(b"\xce\xff\xff\xff") +... +umsgpack.InsufficientDataException +>>> + +# Attempt to unpack an array of length 2 missing the second item +>>> umsgpack.unpackb(b"\x92\xc2") +... +umsgpack.InsufficientDataException +>>> +``` + +### InvalidStringException + +```{eval-rst} +.. autoexception:: umsgpack.InvalidStringException + :noindex: +``` + +String bytes are strictly decoded with UTF-8. This exception is thrown if UTF-8 +decoding of string bytes fails. Use the `allow_invalid_utf8` option to unpack +invalid MessagePack strings into byte strings. + +``` python +# Attempt to unpack invalid UTF-8 string +>>> umsgpack.unpackb(b"\xa2\x80\x81") +... +umsgpack.InvalidStringException: unpacked string is invalid utf-8 +>>> +``` + +### UnsupportedTimestampException + +```{eval-rst} +.. autoexception:: umsgpack.UnsupportedTimestampException + :noindex: +``` + +The official timestamp extension type supports 32-bit, 64-bit and 96-bit +formats. This exception is thrown if a timestamp extension type with an +unsupported format is encountered. + +``` python +# Attempt to unpack invalid timestamp +>>> umsgpack.unpackb(b"\xd5\xff\x01\x02") +... +umsgpack.UnsupportedTimestampException: unsupported timestamp with data length 2 +>>> +``` + +### ReservedCodeException + +```{eval-rst} +.. autoexception:: umsgpack.ReservedCodeException + :noindex: +``` + +``` python +# Attempt to unpack reserved code 0xc1 +>>> umsgpack.unpackb(b"\xc1") +... +umsgpack.ReservedCodeException: reserved code encountered: 0xc1 +>>> +``` + +### UnhashableKeyException + +```{eval-rst} +.. autoexception:: umsgpack.UnhashableKeyException + :noindex: +``` + +Python dictionaries only support keys that are instances of +`collections.Hashable`, so while the map `{ { u'abc': True } : 5 }` has a +MessagePack serialization, it cannot be unpacked into a valid Python +dictionary. + +``` python +# Attempt to unpack { {} : False } +>>> umsgpack.unpackb(b"\x82\x80\xc2") +... +umsgpack.UnhashableKeyException: encountered unhashable key type: {}, +>>> +``` + +### DuplicateKeyException + +```{eval-rst} +.. autoexception:: umsgpack.DuplicateKeyException + :noindex: +``` + +Python dictionaries do not support duplicate keys, but MessagePack maps may be +serialized with duplicate keys. + +``` python +# Attempt to unpack { 1: True, 1: False } +>>> umsgpack.unpackb(b"\x82\x01\xc3\x01\xc2") +... +umsgpack.DuplicateKeyException: encountered duplicate key: 1, +>>> +``` + +### NotImplementedError + +Ext serializable class is missing implementation of `unpackb()`. + +``` python +>>> @umsgpack.ext_serializable(0x50) +... class Point(collections.namedtuple('Point', ['x', 'y'])): +... pass +... +>>> umsgpack.unpackb(b'\xd7\x50\x00\x00\x00\x01\x00\x00\x00\x02') +... +NotImplementedError: Ext serializable class is missing implementation of unpackb() +>>> +``` diff --git a/msgpack.org.md b/msgpack.org.md index 227c7ea..d508bf0 100644 --- a/msgpack.org.md +++ b/msgpack.org.md @@ -1,8 +1,8 @@ -# u-msgpack-python [![Build Status](https://travis-ci.org/vsergeev/u-msgpack-python.svg?branch=master)](https://travis-ci.org/vsergeev/u-msgpack-python) [![GitHub release](https://img.shields.io/github/release/vsergeev/u-msgpack-python.svg?maxAge=7200)](https://github.com/vsergeev/u-msgpack-python) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/vsergeev/u-msgpack-python/blob/master/LICENSE) +# u-msgpack-python [![Build Status](https://app.travis-ci.com/vsergeev/u-msgpack-python.svg?branch=master)](https://app.travis-ci.com/github/vsergeev/u-msgpack-python) [![GitHub release](https://img.shields.io/github/release/vsergeev/u-msgpack-python.svg?maxAge=7200)](https://github.com/vsergeev/u-msgpack-python) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/vsergeev/u-msgpack-python/blob/master/LICENSE) -u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, compatible with both Python 2 and 3, as well CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md). +u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, compatible with Python 2 and 3, as well CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md). -u-msgpack-python is currently distributed on PyPI: https://pypi.python.org/pypi/u-msgpack-python and as a single file: [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) +u-msgpack-python is currently distributed as a package on PyPI: https://pypi.python.org/pypi/u-msgpack-python and as a single file module. ## Installation @@ -16,9 +16,9 @@ With easy_install: $ easy_install u-msgpack-python ``` -or simply drop [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) into your project! +or simply drop `umsgpack.py` into your project! ``` text -$ wget https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py +$ wget https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack/__init__.py -O umsgpack.py ``` ## Examples @@ -65,14 +65,14 @@ Streaming serialization with file-like objects: Serializing and deserializing a raw Ext type: ``` python ->>> # Create an Ext object with type 0x05 and data b"\x01\x02\x03" -... foo = umsgpack.Ext(0x05, b"\x01\x02\x03") +>>> # Create an Ext object with type 5 and data b"\x01\x02\x03" +... foo = umsgpack.Ext(5, b"\x01\x02\x03") >>> umsgpack.packb({u"stuff": foo, u"awesome": True}) b'\x82\xa5stuff\xc7\x03\x05\x01\x02\x03\xa7awesome\xc3' >>> >>> bar = umsgpack.unpackb(_) >>> print(bar['stuff']) -Ext Object (Type: 0x05, Data: 0x01 0x02 0x03) +Ext Object (Type: 5, Data: 0x01 0x02 0x03) >>> bar['stuff'].type 5 >>> bar['stuff'].data diff --git a/setup.cfg b/setup.cfg index 768d2bc..689fa54 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [metadata] -description-file = README.md +description_file = README.md [bdist_wheel] universal = True diff --git a/setup.py b/setup.py index 7fdafa4..1cf6809 100644 --- a/setup.py +++ b/setup.py @@ -5,12 +5,13 @@ setup( name='u-msgpack-python', - version='2.7.0', + version='2.8.0', description='A portable, lightweight MessagePack serializer and deserializer written in pure Python.', author='vsergeev', author_email='v@sergeev.io', url='https://github.com/vsergeev/u-msgpack-python', - py_modules=['umsgpack'], + packages=['umsgpack'], + package_data={'umsgpack': ['*.pyi', 'py.typed']}, long_description="""u-msgpack-python is a lightweight `MessagePack `_ serializer and deserializer module written in pure Python, compatible with both Python 2 and Python 3, as well as CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest `MessagePack specification `_. In particular, it supports the new binary, UTF-8 string, and application-defined ext types. See https://github.com/vsergeev/u-msgpack-python for more information.""", classifiers=[ "Development Status :: 5 - Production/Stable", diff --git a/test_umsgpack.py b/test_umsgpack.py index 2f53dde..1652d60 100644 --- a/test_umsgpack.py +++ b/test_umsgpack.py @@ -404,24 +404,24 @@ class TestUmsgpack(unittest.TestCase): def test_pack_single(self): for (name, obj, data) in single_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) self.assertEqual(umsgpack.packb(obj), data) def test_pack_composite(self): for (name, obj, data) in composite_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) self.assertEqual(umsgpack.packb(obj), data) def test_pack_exceptions(self): for (name, obj, exception) in pack_exception_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) with self.assertRaises(exception): umsgpack.packb(obj) @@ -429,8 +429,8 @@ def test_pack_exceptions(self): def test_unpack_single(self): for (name, obj, data) in single_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) unpacked = umsgpack.unpackb(data) @@ -452,14 +452,14 @@ def test_unpack_single(self): def test_unpack_composite(self): for (name, obj, data) in composite_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) self.assertEqual(umsgpack.unpackb(data), obj) def test_unpack_exceptions(self): for (name, data, exception) in unpack_exception_test_vectors: - print("\tTesting %s" % name) + print("\tTesting {:s}".format(name)) with self.assertRaises(exception): umsgpack.unpackb(data) @@ -469,8 +469,8 @@ def test_pack_compatibility(self): for (name, obj, data) in compatibility_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) self.assertEqual(umsgpack.packb(obj), data) @@ -481,8 +481,8 @@ def test_unpack_compatibility(self): for (name, obj, data) in compatibility_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) unpacked = umsgpack.unpackb(data) @@ -539,17 +539,25 @@ def test_unpack_tuple(self): self.assertEqual(umsgpack.unpackb(data, use_tuple=True), obj_tuple) def test_ext_exceptions(self): + # Test invalid Ext type type with self.assertRaises(TypeError): _ = umsgpack.Ext(5.0, b"") + # Test invalid data type with self.assertRaises(TypeError): _ = umsgpack.Ext(0, u"unicode string") + # Test out of range Ext type value + with self.assertRaises(ValueError): + _ = umsgpack.Ext(-129, b"data") + with self.assertRaises(ValueError): + _ = umsgpack.Ext(128, b"data") + def test_pack_ext_handler(self): for (name, obj, data) in ext_handlers_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) packed = umsgpack.packb(obj, ext_handlers=ext_handlers) self.assertEqual(packed, data) @@ -557,8 +565,8 @@ def test_pack_ext_handler(self): def test_unpack_ext_handler(self): for (name, obj, data) in ext_handlers_test_vectors: obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) unpacked = umsgpack.unpackb(data, ext_handlers=ext_handlers) self.assertEqual(unpacked, obj) @@ -566,8 +574,8 @@ def test_unpack_ext_handler(self): def test_pack_force_float_precision(self): for ((name, obj, data), precision) in zip(float_precision_test_vectors, ["single", "double"]): obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) packed = umsgpack.packb(obj, force_float_precision=precision) self.assertEqual(packed, data) @@ -575,8 +583,8 @@ def test_pack_force_float_precision(self): def test_pack_naive_timestamp(self): for (name, obj, data, _) in naive_timestamp_test_vectors: obj_repr = repr(obj) - print("\t Testing %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) packed = umsgpack.packb(obj) self.assertEqual(packed, data) @@ -584,8 +592,8 @@ def test_pack_naive_timestamp(self): def test_unpack_naive_timestamp(self): for (name, _, data, obj) in naive_timestamp_test_vectors: obj_repr = repr(obj) - print("\t Testing %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) unpacked = umsgpack.unpackb(data) self.assertEqual(unpacked, obj) @@ -594,8 +602,8 @@ def test_pack_ext_override(self): # Test overridden packing of datetime.datetime (name, obj, data) = override_ext_handlers_test_vectors[0] obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) packed = umsgpack.packb(obj, ext_handlers=override_ext_handlers) self.assertEqual(packed, data) @@ -604,8 +612,8 @@ def test_unpack_ext_override(self): # Test overridden unpacking of Ext type -1 (name, obj, data) = override_ext_handlers_test_vectors[1] obj_repr = repr(obj) - print("\tTesting %s: object %s" % - (name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) + print("\tTesting {:s}: object {:s}".format( + name, obj_repr if len(obj_repr) < 24 else obj_repr[0:24] + "...")) unpacked = umsgpack.unpackb(data, ext_handlers=override_ext_handlers) self.assertEqual(unpacked, obj) @@ -681,6 +689,16 @@ def unpackb(cls, data): class DummyClass: pass + # Test out of range Ext type value + with self.assertRaises(ValueError): + @umsgpack.ext_serializable(-129) + class DummyClass2: + pass + with self.assertRaises(ValueError): + @umsgpack.ext_serializable(128) + class DummyClass3: + pass + # Register class with missing packb() and unpackb() @umsgpack.ext_serializable(0x21) class IncompleteClass: @@ -748,11 +766,10 @@ def test_streaming_reader(self): def test_namespacing(self): # Get a list of global variables from umsgpack module - exported_vars = list(filter(lambda x: not x.startswith("_"), - dir(umsgpack))) + exported_vars = list([x for x in dir(umsgpack) if not x.startswith("_")]) # Ignore imports - exported_vars = list(filter(lambda x: x != "struct" and x != "collections" and x != "datetime" and x != - "sys" and x != "io" and x != "xrange" and x != "Hashable", exported_vars)) + exported_vars = list([x for x in exported_vars if x != "struct" and x != "collections" and x != "datetime" and x != + "sys" and x != "io" and x != "xrange" and x != "Hashable"]) self.assertTrue(len(exported_vars) == len(exported_vars_test_vector)) for var in exported_vars_test_vector: diff --git a/tox.ini b/tox.ini index 73d8b30..7047fd8 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,24 @@ [tox] -envlist = py27, py35, py36, py37, py38, pypy, pypy3 +envlist = py27, py35, py36, py37, py38, py39, py310, py311, pypy2, pypy3, mypy skip_missing_interpreters=true + +[gh-actions] +python = + 2.7: py27 + 3.5: py35 + 3.6: py36, mypy + 3.7: py37, mypy + 3.8: py38, mypy + 3.9: py39, mypy + 3.10: py310, mypy + 3.11: py311, mypy + pypy-2: pypy2 + pypy-3: pypy3 + [testenv] deps = pytest commands = pytest + +[testenv:mypy] +deps = mypy +commands = mypy umsgpack diff --git a/umsgpack.py b/umsgpack/__init__.py similarity index 85% rename from umsgpack.py rename to umsgpack/__init__.py index ff53036..e7e194f 100644 --- a/umsgpack.py +++ b/umsgpack/__init__.py @@ -1,4 +1,4 @@ -# u-msgpack-python v2.7.0 - v at sergeev.io +# u-msgpack-python v2.8.0 - v at sergeev.io # https://github.com/vsergeev/u-msgpack-python # # u-msgpack-python is a lightweight MessagePack serializer and deserializer @@ -10,7 +10,7 @@ # # MIT License # -# Copyright (c) 2013-2020 vsergeev / Ivan (Vanya) A. Sergeev +# Copyright (c) 2013-2023 vsergeev / Ivan (Vanya) A. Sergeev # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal @@ -31,7 +31,7 @@ # THE SOFTWARE. # """ -u-msgpack-python v2.7.0 - v at sergeev.io +u-msgpack-python v2.8.0 - v at sergeev.io https://github.com/vsergeev/u-msgpack-python u-msgpack-python is a lightweight MessagePack serializer and deserializer @@ -54,10 +54,10 @@ else: from collections import Hashable -__version__ = "2.7.0" +__version__ = "2.8.0" "Module version string" -version = (2, 7, 0) +version = (2, 8, 0) "Module version tuple" @@ -77,26 +77,36 @@ def __init__(self, type, data): Construct a new Ext object. Args: - type: application-defined type integer - data: application-defined data byte array + type (int): application-defined type integer + data (bytes): application-defined data byte array + + Raises: + TypeError: + Type is not an integer. + ValueError: + Type is out of range of -128 to 127. + TypeError: + Data is not type 'bytes' (Python 3) or not type 'str' (Python 2). Example: - >>> foo = umsgpack.Ext(0x05, b"\x01\x02\x03") - >>> umsgpack.packb({u"special stuff": foo, u"awesome": True}) - '\x82\xa7awesome\xc3\xadspecial stuff\xc7\x03\x05\x01\x02\x03' - >>> bar = umsgpack.unpackb(_) - >>> print(bar["special stuff"]) - Ext Object (Type: 0x05, Data: 01 02 03) - >>> + >>> foo = umsgpack.Ext(5, b"\\x01\\x02\\x03") + >>> umsgpack.packb({u"special stuff": foo, u"awesome": True}) + '\\x82\\xa7awesome\\xc3\\xadspecial stuff\\xc7\\x03\\x05\\x01\\x02\\x03' + >>> bar = umsgpack.unpackb(_) + >>> print(bar["special stuff"]) + Ext Object (Type: 5, Data: 01 02 03) """ - # Check type is type int + # Check type is type int and in range if not isinstance(type, int): raise TypeError("ext type is not type integer") - # Check data is type bytes + elif not (-2**7 <= type <= 2**7 - 1): + raise ValueError("ext type value {:d} is out of range (-128 to 127)".format(type)) + # Check data is type bytes or str elif sys.version_info[0] == 3 and not isinstance(data, bytes): raise TypeError("ext data is not type \'bytes\'") elif sys.version_info[0] == 2 and not isinstance(data, str): raise TypeError("ext data is not type \'str\'") + self.type = type self.data = data @@ -117,8 +127,8 @@ def __str__(self): """ String representation of this Ext object. """ - s = "Ext Object (Type: 0x%02x, Data: " % self.type - s += " ".join(["0x%02x" % ord(self.data[i:i + 1]) + s = "Ext Object (Type: {:d}, Data: ".format(self.type) + s += " ".join(["0x{:02x}".format(ord(self.data[i:i + 1])) for i in xrange(min(len(self.data), 8))]) if len(self.data) > 8: s += " ..." @@ -153,17 +163,25 @@ def ext_serializable(ext_type): instance of the application class. Args: - ext_type: application-defined Ext type code + ext_type (int): application-defined Ext type code Raises: + TypeError: + Ext type is not an integer. + ValueError: + Ext type is out of range of -128 to 127. ValueError: Ext type or class already registered. """ def wrapper(cls): - if ext_type in _ext_type_to_class: - raise ValueError("Ext type 0x{:02x} already registered with class {:s}".format(ext_type, repr(_ext_type_to_class[ext_type]))) + if not isinstance(ext_type, int): + raise TypeError("Ext type is not type integer") + elif not (-2**7 <= ext_type <= 2**7 - 1): + raise ValueError("Ext type value {:d} is out of range of -128 to 127".format(ext_type)) + elif ext_type in _ext_type_to_class: + raise ValueError("Ext type {:d} already registered with class {:s}".format(ext_type, repr(_ext_type_to_class[ext_type]))) elif cls in _ext_class_to_type: - raise ValueError("Class {:s} already registered with Ext type 0x{:02x}".format(repr(cls), ext_type)) + raise ValueError("Class {:s} already registered with Ext type {:d}".format(repr(cls), ext_type)) _ext_type_to_class[ext_type] = cls _ext_class_to_type[cls] = ext_type @@ -248,13 +266,11 @@ class DuplicateKeyException(UnpackException): old MessagePack specification. Example: ->>> umsgpack.compatibility = True ->>> ->>> umsgpack.packb([u"some string", b"some bytes"]) -b'\x92\xabsome string\xaasome bytes' ->>> umsgpack.unpackb(_) -[b'some string', b'some bytes'] ->>> + >>> umsgpack.compatibility = True + >>> umsgpack.packb([u"some string", b"some bytes"]) + b'\\x92\\xabsome string\\xaasome bytes' + >>> umsgpack.unpackb(_) + [b'some string', b'some bytes'] """ ############################################################################## @@ -444,26 +460,25 @@ def _pack2(obj, fp, **options): obj: a Python object fp: a .write()-supporting file-like object - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping a custom type to a callable that packs an instance of the type into an Ext object force_float_precision (str): "single" to force packing floats as IEEE-754 single-precision floats, "double" to force packing floats as - IEEE-754 double-precision floats. + IEEE-754 double-precision floats Returns: - None. + None Raises: - UnsupportedType(PackException): + UnsupportedTypeException(PackException): Object type not supported for packing. Example: - >>> f = open('test.bin', 'wb') - >>> umsgpack.pack({u"compact": True, u"schema": 0}, f) - >>> + >>> f = open('test.bin', 'wb') + >>> umsgpack.pack({u"compact": True, u"schema": 0}, f) """ global compatibility @@ -480,15 +495,15 @@ def _pack2(obj, fp, **options): raise NotImplementedError("Ext serializable class {:s} is missing implementation of packb()".format(repr(obj.__class__))) elif isinstance(obj, bool): _pack_boolean(obj, fp, options) - elif isinstance(obj, (int, long)): + elif isinstance(obj, (int, long)): # noqa: F821 _pack_integer(obj, fp, options) elif isinstance(obj, float): _pack_float(obj, fp, options) - elif compatibility and isinstance(obj, unicode): + elif compatibility and isinstance(obj, unicode): # noqa: F821 _pack_oldspec_raw(bytes(obj), fp, options) elif compatibility and isinstance(obj, bytes): _pack_oldspec_raw(obj, fp, options) - elif isinstance(obj, unicode): + elif isinstance(obj, unicode): # noqa: F821 _pack_string(obj, fp, options) elif isinstance(obj, str): _pack_binary(obj, fp, options) @@ -507,7 +522,7 @@ def _pack2(obj, fp, **options): _pack_ext(ext_handlers[t](obj), fp, options) else: raise UnsupportedTypeException( - "unsupported type: %s" % str(type(obj))) + "unsupported type: {:s}".format(str(type(obj)))) elif _ext_class_to_type: # Linear search for superclass t = next((t for t in _ext_class_to_type if isinstance(obj, t)), None) @@ -517,9 +532,9 @@ def _pack2(obj, fp, **options): except AttributeError: raise NotImplementedError("Ext serializable class {:s} is missing implementation of packb()".format(repr(t))) else: - raise UnsupportedTypeException("unsupported type: %s" % str(type(obj))) + raise UnsupportedTypeException("unsupported type: {:s}".format(str(type(obj)))) else: - raise UnsupportedTypeException("unsupported type: %s" % str(type(obj))) + raise UnsupportedTypeException("unsupported type: {:s}".format(str(type(obj)))) # Pack for Python 3, with unicode 'str' type, 'bytes' type, and no 'long' type @@ -531,26 +546,25 @@ def _pack3(obj, fp, **options): obj: a Python object fp: a .write()-supporting file-like object - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping a custom type to a callable that packs an instance of the type into an Ext object force_float_precision (str): "single" to force packing floats as IEEE-754 single-precision floats, "double" to force packing floats as - IEEE-754 double-precision floats. + IEEE-754 double-precision floats Returns: - None. + None Raises: - UnsupportedType(PackException): + UnsupportedTypeException(PackException): Object type not supported for packing. Example: - >>> f = open('test.bin', 'wb') - >>> umsgpack.pack({u"compact": True, u"schema": 0}, f) - >>> + >>> f = open('test.bin', 'wb') + >>> umsgpack.pack({u"compact": True, u"schema": 0}, f) """ global compatibility @@ -594,7 +608,7 @@ def _pack3(obj, fp, **options): _pack_ext(ext_handlers[t](obj), fp, options) else: raise UnsupportedTypeException( - "unsupported type: %s" % str(type(obj))) + "unsupported type: {:s}".format(str(type(obj)))) elif _ext_class_to_type: # Linear search for superclass t = next((t for t in _ext_class_to_type if isinstance(obj, t)), None) @@ -604,10 +618,10 @@ def _pack3(obj, fp, **options): except AttributeError: raise NotImplementedError("Ext serializable class {:s} is missing implementation of packb()".format(repr(t))) else: - raise UnsupportedTypeException("unsupported type: %s" % str(type(obj))) + raise UnsupportedTypeException("unsupported type: {:s}".format(str(type(obj)))) else: raise UnsupportedTypeException( - "unsupported type: %s" % str(type(obj))) + "unsupported type: {:s}".format(str(type(obj)))) def _packb2(obj, **options): @@ -617,26 +631,25 @@ def _packb2(obj, **options): Args: obj: a Python object - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping a custom type to a callable that packs an instance of the type into an Ext object force_float_precision (str): "single" to force packing floats as IEEE-754 single-precision floats, "double" to force packing floats as - IEEE-754 double-precision floats. + IEEE-754 double-precision floats Returns: - A 'str' containing serialized MessagePack bytes. + str: Serialized MessagePack bytes Raises: - UnsupportedType(PackException): + UnsupportedTypeException(PackException): Object type not supported for packing. Example: - >>> umsgpack.packb({u"compact": True, u"schema": 0}) - '\x82\xa7compact\xc3\xa6schema\x00' - >>> + >>> umsgpack.packb({u"compact": True, u"schema": 0}) + '\\x82\\xa7compact\\xc3\\xa6schema\\x00' """ fp = io.BytesIO() _pack2(obj, fp, **options) @@ -650,26 +663,25 @@ def _packb3(obj, **options): Args: obj: a Python object - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping a custom type to a callable that packs an instance of the type into an Ext object force_float_precision (str): "single" to force packing floats as IEEE-754 single-precision floats, "double" to force packing floats as - IEEE-754 double-precision floats. + IEEE-754 double-precision floats Returns: - A 'bytes' containing serialized MessagePack bytes. + bytes: Serialized MessagePack bytes Raises: - UnsupportedType(PackException): + UnsupportedTypeException(PackException): Object type not supported for packing. Example: - >>> umsgpack.packb({u"compact": True, u"schema": 0}) - b'\x82\xa7compact\xc3\xa6schema\x00' - >>> + >>> umsgpack.packb({u"compact": True, u"schema": 0}) + b'\\x82\\xa7compact\\xc3\\xa6schema\\x00' """ fp = io.BytesIO() _pack3(obj, fp, **options) @@ -719,21 +731,21 @@ def _unpack_integer(code, fp, options): return struct.unpack(">I", _read_except(fp, 4))[0] elif code == b'\xcf': return struct.unpack(">Q", _read_except(fp, 8))[0] - raise Exception("logic error, not int: 0x%02x" % ord(code)) + raise Exception("logic error, not int: 0x{:02x}".format(ord(code))) def _unpack_reserved(code, fp, options): if code == b'\xc1': raise ReservedCodeException( - "encountered reserved code: 0x%02x" % ord(code)) + "encountered reserved code: 0x{:02x}".format(ord(code))) raise Exception( - "logic error, not reserved code: 0x%02x" % ord(code)) + "logic error, not reserved code: 0x{:02x}".format(ord(code))) def _unpack_nil(code, fp, options): if code == b'\xc0': return None - raise Exception("logic error, not nil: 0x%02x" % ord(code)) + raise Exception("logic error, not nil: 0x{:02x}".format(ord(code))) def _unpack_boolean(code, fp, options): @@ -741,7 +753,7 @@ def _unpack_boolean(code, fp, options): return False elif code == b'\xc3': return True - raise Exception("logic error, not boolean: 0x%02x" % ord(code)) + raise Exception("logic error, not boolean: 0x{:02x}".format(ord(code))) def _unpack_float(code, fp, options): @@ -749,7 +761,7 @@ def _unpack_float(code, fp, options): return struct.unpack(">f", _read_except(fp, 4))[0] elif code == b'\xcb': return struct.unpack(">d", _read_except(fp, 8))[0] - raise Exception("logic error, not float: 0x%02x" % ord(code)) + raise Exception("logic error, not float: 0x{:02x}".format(ord(code))) def _unpack_string(code, fp, options): @@ -762,7 +774,7 @@ def _unpack_string(code, fp, options): elif code == b'\xdb': length = struct.unpack(">I", _read_except(fp, 4))[0] else: - raise Exception("logic error, not string: 0x%02x" % ord(code)) + raise Exception("logic error, not string: 0x{:02x}".format(ord(code))) # Always return raw bytes in compatibility mode global compatibility @@ -786,7 +798,7 @@ def _unpack_binary(code, fp, options): elif code == b'\xc6': length = struct.unpack(">I", _read_except(fp, 4))[0] else: - raise Exception("logic error, not binary: 0x%02x" % ord(code)) + raise Exception("logic error, not binary: 0x{:02x}".format(ord(code))) return _read_except(fp, length) @@ -809,7 +821,7 @@ def _unpack_ext(code, fp, options): elif code == b'\xc9': length = struct.unpack(">I", _read_except(fp, 4))[0] else: - raise Exception("logic error, not ext: 0x%02x" % ord(code)) + raise Exception("logic error, not ext: 0x{:02x}".format(ord(code))) ext_type = struct.unpack("b", _read_except(fp, 1))[0] ext_data = _read_except(fp, length) @@ -850,7 +862,7 @@ def _unpack_ext_timestamp(ext_data, options): microseconds = struct.unpack(">I", ext_data[0:4])[0] // 1000 else: raise UnsupportedTimestampException( - "unsupported timestamp with data length %d" % len(ext_data)) + "unsupported timestamp with data length {:d}".format(len(ext_data))) return _epoch + datetime.timedelta(seconds=seconds, microseconds=microseconds) @@ -864,7 +876,7 @@ def _unpack_array(code, fp, options): elif code == b'\xdd': length = struct.unpack(">I", _read_except(fp, 4))[0] else: - raise Exception("logic error, not array: 0x%02x" % ord(code)) + raise Exception("logic error, not array: 0x{:02x}".format(ord(code))) if options.get('use_tuple'): return tuple((_unpack(fp, options) for i in xrange(length))) @@ -886,7 +898,7 @@ def _unpack_map(code, fp, options): elif code == b'\xdf': length = struct.unpack(">I", _read_except(fp, 4))[0] else: - raise Exception("logic error, not map: 0x%02x" % ord(code)) + raise Exception("logic error, not map: 0x{:02x}".format(ord(code))) d = {} if not options.get('use_ordered_dict') else collections.OrderedDict() for _ in xrange(length): @@ -898,10 +910,10 @@ def _unpack_map(code, fp, options): k = _deep_list_to_tuple(k) elif not isinstance(k, Hashable): raise UnhashableKeyException( - "encountered unhashable key: %s, %s" % (str(k), str(type(k)))) + "encountered unhashable key: \"{:s}\" ({:s})".format(str(k), str(type(k)))) elif k in d: raise DuplicateKeyException( - "encountered duplicate key: %s, %s" % (str(k), str(type(k)))) + "encountered duplicate key: \"{:s}\" ({:s})".format(str(k), str(type(k)))) # Unpack value v = _unpack(fp, options) @@ -910,7 +922,7 @@ def _unpack_map(code, fp, options): d[k] = v except TypeError: raise UnhashableKeyException( - "encountered unhashable key: %s" % str(k)) + "encountered unhashable key: \"{:s}\"".format(str(k))) return d @@ -928,20 +940,20 @@ def _unpack2(fp, **options): Args: fp: a .read()-supporting file-like object - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext type to a callable that unpacks an instance of Ext into an object - use_ordered_dict (bool): unpack maps into OrderedDict, instead of - unordered dict (default False) + use_ordered_dict (bool): unpack maps into OrderedDict, instead of dict + (default False) use_tuple (bool): unpacks arrays into tuples, instead of lists (default False) allow_invalid_utf8 (bool): unpack invalid strings into instances of - InvalidString, for access to the bytes - (default False) + :class:`InvalidString`, for access to the + bytes (default False) Returns: - A Python object. + Python object Raises: InsufficientDataException(UnpackException): @@ -959,10 +971,9 @@ def _unpack2(fp, **options): Duplicate key encountered during map unpacking. Example: - >>> f = open('test.bin', 'rb') - >>> umsgpack.unpackb(f) - {u'compact': True, u'schema': 0} - >>> + >>> f = open('test.bin', 'rb') + >>> umsgpack.unpackb(f) + {u'compact': True, u'schema': 0} """ return _unpack(fp, options) @@ -974,20 +985,20 @@ def _unpack3(fp, **options): Args: fp: a .read()-supporting file-like object - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext type to a callable that unpacks an instance of Ext into an object - use_ordered_dict (bool): unpack maps into OrderedDict, instead of - unordered dict (default False) + use_ordered_dict (bool): unpack maps into OrderedDict, instead of dict + (default False) use_tuple (bool): unpacks arrays into tuples, instead of lists (default False) allow_invalid_utf8 (bool): unpack invalid strings into instances of - InvalidString, for access to the bytes - (default False) + :class:`InvalidString`, for access to the + bytes (default False) Returns: - A Python object. + Python object Raises: InsufficientDataException(UnpackException): @@ -1005,10 +1016,9 @@ def _unpack3(fp, **options): Duplicate key encountered during map unpacking. Example: - >>> f = open('test.bin', 'rb') - >>> umsgpack.unpackb(f) - {'compact': True, 'schema': 0} - >>> + >>> f = open('test.bin', 'rb') + >>> umsgpack.unpackb(f) + {'compact': True, 'schema': 0} """ return _unpack(fp, options) @@ -1019,22 +1029,22 @@ def _unpackb2(s, **options): Deserialize MessagePack bytes into a Python object. Args: - s: a 'str' or 'bytearray' containing serialized MessagePack bytes + s (str, bytearray): serialized MessagePack bytes - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext type to a callable that unpacks an instance of Ext into an object - use_ordered_dict (bool): unpack maps into OrderedDict, instead of - unordered dict (default False) + use_ordered_dict (bool): unpack maps into OrderedDict, instead of dict + (default False) use_tuple (bool): unpacks arrays into tuples, instead of lists (default False) allow_invalid_utf8 (bool): unpack invalid strings into instances of - InvalidString, for access to the bytes - (default False) + :class:`InvalidString`, for access to the + bytes (default False) Returns: - A Python object. + Python object Raises: TypeError: @@ -1054,9 +1064,8 @@ def _unpackb2(s, **options): Duplicate key encountered during map unpacking. Example: - >>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00') - {u'compact': True, u'schema': 0} - >>> + >>> umsgpack.unpackb(b'\\x82\\xa7compact\\xc3\\xa6schema\\x00') + {u'compact': True, u'schema': 0} """ if not isinstance(s, (str, bytearray)): raise TypeError("packed data must be type 'str' or 'bytearray'") @@ -1069,22 +1078,22 @@ def _unpackb3(s, **options): Deserialize MessagePack bytes into a Python object. Args: - s: a 'bytes' or 'bytearray' containing serialized MessagePack bytes + s (bytes, bytearray): serialized MessagePack bytes - Kwargs: + Keyword Args: ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext type to a callable that unpacks an instance of Ext into an object - use_ordered_dict (bool): unpack maps into OrderedDict, instead of - unordered dict (default False) + use_ordered_dict (bool): unpack maps into OrderedDict, instead of dict + (default False) use_tuple (bool): unpacks arrays into tuples, instead of lists (default False) allow_invalid_utf8 (bool): unpack invalid strings into instances of - InvalidString, for access to the bytes - (default False) + :class:`InvalidString`, for access to the + bytes (default False) Returns: - A Python object. + Python object Raises: TypeError: @@ -1104,9 +1113,8 @@ def _unpackb3(s, **options): Duplicate key encountered during map unpacking. Example: - >>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00') - {'compact': True, 'schema': 0} - >>> + >>> umsgpack.unpackb(b'\\x82\\xa7compact\\xc3\\xa6schema\\x00') + {'compact': True, 'schema': 0} """ if not isinstance(s, (bytes, bytearray)): raise TypeError("packed data must be type 'bytes' or 'bytearray'") diff --git a/umsgpack/__init__.pyi b/umsgpack/__init__.pyi new file mode 100644 index 0000000..61a8413 --- /dev/null +++ b/umsgpack/__init__.pyi @@ -0,0 +1,41 @@ +from typing import Any + +__version__: str + +version: tuple[int, int, int] + +def pack(obj, fp, **options) -> None: ... +def packb(obj, **options) -> bytes: ... +def dump(obj, fp, **options) -> None: ... +def dumps(obj, **options) -> bytes: ... + +def unpackb(s: bytes | bytearray, **options) -> Any: ... +def unpack(fp, **options) -> Any: ... +def loads(s: bytes | bytearray, **options) -> Any: ... +def load(fp, **options) -> Any: ... + +class Ext: + type: int + data: bytes + def __init__(self, type: int, data: bytes) -> None: ... + def __eq__(self, other) -> bool: ... + def __ne__(self, other) -> bool: ... + def __hash__(self) -> int: ... + +class InvalidString(bytes): ... + +def ext_serializable(ext_type: int): ... + +class PackException(Exception): ... +class UnpackException(Exception): ... +class UnsupportedTypeException(PackException): ... +class InsufficientDataException(UnpackException): ... +class InvalidStringException(UnpackException): ... +class UnsupportedTimestampException(UnpackException): ... +class ReservedCodeException(UnpackException): ... +class UnhashableKeyException(UnpackException): ... +class DuplicateKeyException(UnpackException): ... +KeyNotPrimitiveException = UnhashableKeyException +KeyDuplicateException = DuplicateKeyException + +compatibility: bool