Skip to content

Upgrade guide

To v3

Old signatures will work

Data signed with previous versions (>=2.0, <=3.0) will still be valid.

The biggest change in this version was to drop Python 3.7. Other than that, file-related operations have been normalized internally so that using bytes always performs better, and the utility functions force_bytes and force_string now only accept either bytes or str, and raises TypeError otherwise.

All in all, not very big changes, and thus normal usage is not affected. However, if you were using the utility functions, or had a custom serializer signer, then YMMV.

To v2.5

Old signatures will work

Data signed with previous versions (>=2.0, <=2.5) will still be valid.

Now the ExpiredSignatureError exception contains valid unsigned data, which can be safely used. Check out the example to know more.

Python 3.7 is EOL

As Python 3.7 has reached its end-of-life, this is the last version supporting it.

To v2.4

Old signatures will work

Data signed with previous versions (>=2.0, <=2.4) will still be valid.

Both the public and private API of Blake2TimestampSigner for unsign and unsign_parts now accepts max_age=None to omit checking the signature timestamp (but note that there is no default! it has to be explicit). This happens after checking the signature, which must be valid.

Checkout the example for more information.

To v2.3

Old signatures will work

Data signed with previous versions (>=2.0, <=2.3) will still be valid.

For the public API, the constructor for signers now accepts as the secret, besides strings or bytes, a sequence of strings or bytes, to allow for secret rotation. This means you don't have to change anything unless you want to start using said feature.

Regarding the private API, a few internal methods were modified to work with this sequence of secrets. Check out the corresponding commit:

  • 5a0b22d5 - ✨ Support secret rotation

To v2.2

Old signatures will work

Data signed with previous versions (>=2.0, <=2.2) will still be valid.

No public API was changed, so there's no change for you except that you can now choose to use blake3.

Regarding the private API, several internal methods of the signers changed, and many were transferred to the BLAKEHasher class, and subclasses. Check out the corresponding commit and docs:

To v2.1

Old signatures will work

Data signed with previous versions (>=2.0, <=2.1) will still be valid.

The default compression level was hardcoded to 6 no matter which compressor was being used. This has changed so that the corresponding default compression level for the compressor is used.

If you were using the Zlib compressor (default), then there's no change for you. However, if you were using the Gzip compressor, the default level will now be 9 instead of 6. To continue using 6 as compression level, change the line calling the corresponding method (dump, dumps, or dumps_parts) and use the parameter compression_level=6:

from blake2signer import Blake2SerializerSigner


secret = b'secure-secret-that-nobody-knows!'
data = {'user_id': 1, 'is_admin': True, 'username': 'hackan'}

signer = Blake2SerializerSigner(
    secret,
    personalisation=b'some-signer',
)
# ...
signed = signer.dumps(data, compression_level=6)  # Add the compression_level parameter

See the examples for more information.

Moreover, if you have created a custom compressor, then you need to add the default_compression_level property:

from blake2signer.interfaces import CompressorInterface


class MyCompressor(CompressorInterface):
    """My compressor."""

    @property
    def default_compression_level(self) -> int:
        """Get the default compression level."""
        return 8

    ...

See the examples for more information.

To v2

Generally speaking, v2 broke the public API a bit, so most projects using v1 could probably work as-is with v2. However, the private API changed a lot.

Old signatures will fail

Data signed with previous versions fails with InvalidSignatureError.

Public API changes

  • Blake2Signer|Blake2TimestampSigner|Blake2SerializerSigner.SEPARATOR class attribute is replaced by the separator instance attribute and is now checked to be ASCII only and not belong to the encoder alphabet.
  • Blake2SerializerSigner.COMPRESSION_FLAG class attribute is replaced by the compression_flag instance attribute and is now checked to be ASCII only.
  • Blake2SerializerSigner.COMPRESSION_RATIO class attribute is replaced by the compression_ratio instance attribute and is now checked to be ASCII only.
  • The default digest size for all signers is set to 16 bytes. Previously, Blake2Signer and Blake2TimestampSigner defaulted to the maximum allowed size for the hasher.
  • The compression parameter used in Blake2SerializerSigner named use_compression is renamed to compress.

Private API changes

The private API changed a lot, so if you were using some private methods please review them for changes! Unfortunately I can't list them all here but mainly check these commits:

  • c6acaa0a - 🏗 Split classes into own modules by type
  • 0b1d0a6c - ✨ Allow changing encoder in every signer
  • c9bcd173 - ✨ Make separator an instance attribute
  • 675389de - ✨ Make comp flag and ratio an instance attribute
  • 8618e663 - ♻ Refactor serializer signer base methods
  • 40ccbd40 - ✨ Add new methods to get data and sig separately
  • b2d69910 - ♻ Rename use_compression to compress