A Django app to use backblaze b2 as storage.
Project description
django-backblaze-b2
A storage backend for Django that uses Backblaze's B2 APIs.
Implementation wraps Official Python SDK
How to use
- Install from this repo, or install from PyPi:
pip install django-backblaze-b2
As tested, requires python 3.6 or greater but solely due to type annotations. PRs welcome :) - Configure your django
settings
. The absolute minimum config would be:
BACKBLAZE_CONFIG = {
"application_key_id": os.getenv("BACKBLAZE_KEY_ID"), # however you want to securely retrieve these values
"application_key": os.getenv("BACKBLAZE_KEY"),
}
Theoretically you may now refer to the base storage class as a storage class.
e.g.
from django_backblaze_b2 import BackblazeB2Storage
class MyModel(models.Model):
fileField = models.FileField(
upload_to="uploads",
storage=BackblazeB2Storage
)
Caching
Because the SDK will authorize/request with the b2 server to retrieve file info, the library caches these account information lookups.
By default, the accountInfo
configuration uses a cache by the name of django-backblaze-b2
which you must have in your CACHES
section of your settings.py
. This is the recommended caching implementation as it leverages the django framework and with that comes thread-safety. You can then use whichever cache implementation you want. It is not recommended to cache with the default
django cache, as the clear()
method may be called during the backblaze lifecycle.
If you do not wish to use this, you can use a sqlite database on disk for caching, or use a non-thread-safe in-memory implementation. This is only recommended for single-threaded deployments. (remember in most deployments a new thread serves each request).
Public/Logged-In/Private storage
- Add
django_backblaze_b2
to yourINSTALLED_APPS
- Add the urls to your
urlpatterns
in the rooturls.py
:
urlpatterns = [
...
path('', include('django_backblaze_b2.urls')),
]
Configurations
You may want to use your own bucket name, or set further configuration such as lazy authorization/validation, or specifying file metadata.
Refer to the options for all options.
You can modify the settings dict, but additionally override any setting with the opts
keyword argument to the storage classes.
To specify different buckets to use for your public, logged-in, staff storage, you can set the
specificBucketNames
attribute of the settings dict.
Why
There are several Django storage packages out there already which support B2, but none met my needs. These are:
- django-storages
- Large community engagement ✅
- Well-tested ✅
- Second-class support via Apache Libcloud ❌
- Disconnect in configuration and actual use ❌
- PR list with low turnaround ❌
- django-b2
- Similar aim to this project, around official backblaze SDK ✅
- Mixed goals (storage, scripts) ❌
- Tests?? ❌
- django-backblazeb2-storage
- Simple configuration ✅
- Not based around python SDK (potentially harder to keep up with version changes) ❌
- Tests?? ❌
S3 Compatible API
Backblazed can be used with an S3-compatible API This is great, but most packages use an older version of the S3 Api (v2). Backblaze uses v4.
What this package offers
- Type Annotations
- Tested
- No hacks required to get up and running around API deficiencies (any hacks are not exposed in API)
- Support for public/private files, restricted via Django user permissions
How it works
- A simple implementation of the
django.core.files.storage.Storage
class provides handling for storage behaviour within your Django application - Three url routes are appended to the root of your application:
/b2/
/b2l/
/b2s/
These routes act as a proxy/intermediary between the requester and backblaze b2 apis. The public/b2/
allows exposing files from a private bucket, and the logged-in and staff routes will perform the known validations of a django app to prevent unauthorized access.
Gotchas
- The original filename + any upload paths is stored in the database. Thus your column name must be of sufficient length to hold that (unchanged behaviour from
FileSystemStorage
) - When retrieving files from the
PublicStorage
,LoggedInStorage
orStaffStorage
, you may not override the"bucket"
or authorization options, or else when the app proxies the file download, it will be unable to retrieve the file from the respective bucket. - Simply using
LoggedInStorage
orStaffStorage
is not enough to protect your files if your bucket is not public. If any individual gains access to the file ids/urls for these files, there is no authentication around them. It is up to the implementer to ensure the security of their application. - Once the file is uploaded, and someone obtains a file url (e.g. http://djangodomain.com/b2l/uploads/image.png), the model will no longer be checked for the file. This means that if you share the bucket between multiple use-cases, you could in theory find finds that don't belong to your django app, or similarly if you delete/change your models, the files could still be downloaded. Consider using an app like django-cleanup if this is important to you
Contributing
Contributions welcome!
- Please ensure test coverage does not decrease in a meaningful way.
- Ensure formatting is compliant (
make lint
) - Use conventional commits
Setting up for development
Requires
- python
- pyenv - align local version
- GNU Make
- (optional) docker - run sample app
Version compatibility reminder
Ver | Status | EOL |
---|---|---|
3.9 | bugfix | 2025-10 |
3.8 | bugfix | 2024-10 |
3.7 | security | 2023-06-27 |
3.6 | security | 2021-12-23 |
Running
make setup
- You can run django with
make run-django
to test django app. - You can run tests with
make test
- You can view test coverage with
make test-coverage
, then see in the terminal, opentest/htmlcov/index.html
or usecov.xml
in your favourite IDE like VSCode
Releasing
make publish-to-pypi
Cleanup
make cleanup
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 django-backblaze-b2-2.0.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 13f28b0c30ec421ae969768d909fc2cd346b241ca7f29e5a34c2b02720b5e870 |
|
MD5 | 187bdc08ea6c25d05c446693de1450c1 |
|
BLAKE2b-256 | 2152bb5dfe0825fec82b4c56350df18d87f940b4c8d04a6c806bd2b8db17fc99 |
Hashes for django_backblaze_b2-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 683da8a277677c3c07db76cb7281b8a4f430bf1612e2c46badfc1b31bb74d720 |
|
MD5 | 7233b303d4c2c050d4f799f24f7d5fd9 |
|
BLAKE2b-256 | ce49efee7e4b10b294861b08486a29fbff3fe808dd6c071d4dc90d0baef90c55 |