README.md

drf-base64-binaryfield

Features

This package provides a Base64BinaryField for use with Django REST Framework serializers.

It allows you to:

• Serialize binary data into base64 strings for use in JSON responses
• Deserialize base64 strings back into binary data
• Optionally use url-safe base64 encoding (replacing + and / with - and _)
• Validate the length of the binary data

Why? because JSON does not support binary data, and base64 is a common way to represent binary data in JSON.

Considerations

Base64 encoding isn't very space efficient.

If you need to send a lot of binary data quite often, you may want to consider using a more efficient serialization format instead of JSON, such as MessagePack. There is a MessagePack serializer for Django REST Framework available: django-rest-framework-msgpack.

If you only occasionally need to send binary data then base64 encoding is probably fine for your use case. This package may be suitable for you.

Requirements

• Python 3.9+
• Django 3.2+
• Django REST Framework 3.14+

Installation

You can install drf-base64-binaryfield via pip from PyPI:

$ pip install drf-base64-binaryfield

Usage

In this example, we need to send a cryptographic challenge to the client that consists of raw bytes. Wouldn't it be convenient if there was a way to send this data as part of JSON response?

We can use Base64BinaryField provided by this package to serialize the binary data into a base64 string, which can be sent as part of a JSON response.

from rest_framework import serializers
from drf_base64_binaryfield.fields import Base64BinaryField

class ChallengerSerializer(serializers.Serializer):
    # This field accepts a Python bytes object and serializes it into a base64 string. Or it can deserialize a base64 string back into a bytes object.
    challenge = Base64BinaryField()

serializer = ChallengerSerializer(instance={'challenge': b'\x00\x01\x02\x03'})
print(serializer.data)
# {'challenge': 'AAECAw=='}

Web-safe encoding

If you want to use web-safe base64 encoding, you can set url_safe=True:

class CryptographicChallengeSerializer(serializers.Serializer):
    challenge = Base64BinaryField(url_safe=True)

Binary data size validation

This package also supports validating the size of the decoded binary data:

class ExampleSerializer(serializers.Serializer):
    # This field will only accept binary data that is between 16 and 32 bytes long
    example_binary = Base64BinaryField(min_size=16, max_size=32)

Extending Base64BinaryField

You can extend Base64BinaryField to create your own custom fields. You may want to unpack the binary data into a different format, for example.

import struct

class CustomBinaryField(Base64BinaryField):
    def to_internal_value(self, data):
        binary_data = super().to_internal_value(data)

        # Do something with the binary data...

        # For example: unpack it as a little-endian, 32-bit unsigned integer
        return struct.unpack('<I', binary_data)[0]

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, drf-base64-binaryfield is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @OmenApps's Cookiecutter Django Package template.