Support for base64-encoded binary data in django rest framework serializers
Project description
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for drf_base64_binaryfield-1.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a4513c2bde101637dc50de467f8ba519683151b778bf7a1112105363493f00f9 |
|
MD5 | 5f7fa98c906671e32c7a053ab2345c05 |
|
BLAKE2b-256 | ef2691f1ce101d4d2915cfd8e37f7405e68b46de775af7d3b945307438513cb8 |
Hashes for drf_base64_binaryfield-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0e4e6f55d5430987782612b8f2605e9ca4d1bf9c54c73f27d66853851c45980b |
|
MD5 | 467afaec5bc82fc1825846c43bbc4543 |
|
BLAKE2b-256 | 8acf602ce81bf3f42bb66accf00d099b2c4e0a01f5727bdbcd6729cc33e8d2c2 |