Skip to content

Upgrade guide

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 accept as the secret, besides string or bytes, a sequence of string 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
Back to top