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.
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.
- Python 3.9+
- Django 3.2+
- Django REST Framework 3.14+
You can install drf-base64-binaryfield via pip from PyPI:
$ pip install drf-base64-binaryfield
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=='}
If you want to use web-safe base64 encoding, you can set url_safe=True
:
class CryptographicChallengeSerializer(serializers.Serializer):
challenge = Base64BinaryField(url_safe=True)
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)
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]
Contributions are very welcome. To learn more, see the Contributor Guide.
Distributed under the terms of the MIT license, drf-base64-binaryfield is free and open source software.
If you encounter any problems, please file an issue along with a detailed description.
This project was generated from @OmenApps's Cookiecutter Django Package template.