Skip to main content

Support for base64-encoded binary data in django rest framework serializers

Project description

drf-base64-binaryfield

PyPI Status Python Version License

Tests Codecov

pre-commit Black

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

drf_base64_binaryfield-1.1.0.tar.gz (7.2 kB view details)

Uploaded Source

Built Distribution

drf_base64_binaryfield-1.1.0-py3-none-any.whl (8.6 kB view details)

Uploaded Python 3

File details

Details for the file drf_base64_binaryfield-1.1.0.tar.gz.

File metadata

File hashes

Hashes for drf_base64_binaryfield-1.1.0.tar.gz
Algorithm Hash digest
SHA256 a4513c2bde101637dc50de467f8ba519683151b778bf7a1112105363493f00f9
MD5 5f7fa98c906671e32c7a053ab2345c05
BLAKE2b-256 ef2691f1ce101d4d2915cfd8e37f7405e68b46de775af7d3b945307438513cb8

See more details on using hashes here.

File details

Details for the file drf_base64_binaryfield-1.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for drf_base64_binaryfield-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0e4e6f55d5430987782612b8f2605e9ca4d1bf9c54c73f27d66853851c45980b
MD5 467afaec5bc82fc1825846c43bbc4543
BLAKE2b-256 8acf602ce81bf3f42bb66accf00d099b2c4e0a01f5727bdbcd6729cc33e8d2c2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page