# django-backblaze-b2
[](https://pypi.org/project/django-backblaze-b2/)
[](https://pypi.org/project/django-backblaze-b2/)
[](https://pypi.org/project/django-backblaze-b2/)
A storage backend for Django that uses [Backblaze's B2 APIs](https://www.backblaze.com/b2/cloud-storage.html).
Implementation wraps [Official Python SDK](https://github.com/Backblaze/b2-sdk-python)
## Changelog / Releases
See [https://github.com/ehossack/django-backblaze-b2/releases](https://github.com/ehossack/django-backblaze-b2/releases)
## How to use
1. Install from this repo, or install from PyPi: `pip install django-backblaze-b2`
As tested, requires python 3.7 or greater but solely due to type annotations. PRs welcome :)
1. Configure your django `settings`. A minimalistic config would be:
```python
CACHES = {
"default": .... ,
# add a cache via db table or memcached that can be accessed from multiple threads
"django-backblaze-b2": {
'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
'LOCATION': 'django_backblaze_b2_cache_table',
}
}
BACKBLAZE_CONFIG = {
# however you want to securely retrieve these values
"application_key_id": os.getenv("BACKBLAZE_KEY_ID"),
"application_key": os.getenv("BACKBLAZE_KEY"),
}
```
Theoretically you may now refer to the base storage class as a storage class (see the sample app for some usage: you can run with `make run-sample-proj` although you might want to configure the `SECONDS_TO_RUN_APP` variable in `settings.env` to be 0 for unlimited to try things out)
e.g.
```python
from django_backblaze_b2 import BackblazeB2Storage
class MyModel(models.Model):
file_field = models.FileField(
upload_to="uploads",
storage=BackblazeB2Storage
)
```
### Public/Logged-In/Private storage
1. Add `django_backblaze_b2` to your `INSTALLED_APPS`
1. Add the urls to your `urlpatterns` in the root `urls.py`:
```python
urlpatterns = [
...
path('', include('django_backblaze_b2.urls')),
]
```
### Caching
To retrieve file metadata ("file info" as the b2 sdk names it), this library has to authorize and request data from b2 servers, even for just resolving the url for a file. Because these are network calls, and relatively expensive in comparison to a file-based storage, and because data is unlikely to change frequently, there is some caching done by this library.
By default, the account information (`account_info`) configuration of the settings uses a cache by the name of `django-backblaze-b2` which you must have in your `CACHES` section of your `settings.py`. This is to leverage django's thread-safe cache implementations, and if you are using a database cache table or memcached, (rather than LocMemCache) your cache can be shared by the multiple django processes that typically serve requests.
It is not recommended configure `account_info` with the `default` django cache, as the `clear()` method may be called during the backblaze lifecycle.
If you do not wish to use a django cache, 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).
For further discussion on this see https://github.com/ehossack/django-backblaze-b2/issues/16
### 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](./django_backblaze_b2/options.py) 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](https://github.com/jschneier/django-storages)
* Large community engagement ✅
* Well-tested ✅
* [Second-class support](https://github.com/jschneier/django-storages/issues/765) via [Apache Libcloud](https://github.com/apache/libcloud) ❌
* Disconnect in configuration and actual use ❌
* PR list with low turnaround ❌
* [django-b2](https://github.com/pyutil/django-b2)
* Similar aim to this project, around official backblaze SDK ✅
* Mixed goals (storage, scripts) ❌
* Tests?? ❌
* [django-backblazeb2-storage](https://github.com/royendgel/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](https://www.backblaze.com/b2/docs/s3_compatible_api.html)
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
* Support for CDN and cached url details
## 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:
1. `/b2/`
2. `/b2l/`
3. `/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.
* If you use a CDN config, you can specify the CDN options and then include the bucket url segments (`/file/<bucket-name>/`) if your CDN is proxying the classic b2 url (e.g. `f000.backblazeb2.com`) or not, if you are proxying the s3-compatible url.
### 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` or `StaffStorage`, 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` or `StaffStorage` 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 django model is no longer involved in file resolution. This means that if you share the bucket between multiple use-cases, you could in theory find files that don't belong to your django app (e.g. some image2.png), or similarly if you delete/change your models, the files could still be downloaded. Consider using an app like [django-cleanup](https://github.com/un1t/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](https://www.conventionalcommits.org/en/v1.0.0/)
## Setting up for development
### Requires
* python
* pyenv - align local version
* GNU Make
* (optional) docker - run sample app
#### Version compatibility reminder
[link](https://devguide.python.org/versions/)
| Ver | Status | EOL |
| ---- | -------- | ---------- |
| 3.12 | bugfix | 2028-10 |
| 3.11 | bugfix | 2027-10 |
| 3.10 | security | 2026-10 |
| 3.9 | security | 2025-10 |
| 3.8 | security | 2024-10 |
### Running
1. `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,
open `test/htmlcov/index.html`
or use `cov.xml` in your favourite IDE like VSCode
### Releasing
1. `make release`
### Cleanup
1. `make cleanup`
Raw data
{
"_id": null,
"home_page": "https://github.com/ehossack/django-backblaze-b2/",
"name": "django-backblaze-b2",
"maintainer": "Etienne H",
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": "django_backblaze_b2@internet-e-mail.com",
"keywords": "django, storage, backblaze, b2, cloud",
"author": "Etienne H",
"author_email": "django_backblaze_b2@internet-e-mail.com",
"download_url": "https://files.pythonhosted.org/packages/f4/00/da1c7a7c5a71672c34ebfb1042cb455a1eebdcc1ca79a4db434f4f21fd08/django_backblaze_b2-6.0.2.tar.gz",
"platform": null,
"description": "# django-backblaze-b2\n\n[](https://pypi.org/project/django-backblaze-b2/)\n[](https://pypi.org/project/django-backblaze-b2/)\n[](https://pypi.org/project/django-backblaze-b2/)\n\nA storage backend for Django that uses [Backblaze's B2 APIs](https://www.backblaze.com/b2/cloud-storage.html).\n\nImplementation wraps [Official Python SDK](https://github.com/Backblaze/b2-sdk-python)\n\n## Changelog / Releases\n\nSee [https://github.com/ehossack/django-backblaze-b2/releases](https://github.com/ehossack/django-backblaze-b2/releases)\n\n## How to use\n\n1. Install from this repo, or install from PyPi: `pip install django-backblaze-b2`\nAs tested, requires python 3.7 or greater but solely due to type annotations. PRs welcome :)\n1. Configure your django `settings`. A minimalistic config would be:\n```python\nCACHES = {\n \"default\": .... ,\n # add a cache via db table or memcached that can be accessed from multiple threads\n \"django-backblaze-b2\": {\n 'BACKEND': 'django.core.cache.backends.db.DatabaseCache',\n 'LOCATION': 'django_backblaze_b2_cache_table',\n }\n}\n\nBACKBLAZE_CONFIG = {\n # however you want to securely retrieve these values\n \"application_key_id\": os.getenv(\"BACKBLAZE_KEY_ID\"),\n \"application_key\": os.getenv(\"BACKBLAZE_KEY\"),\n}\n```\n\nTheoretically you may now refer to the base storage class as a storage class (see the sample app for some usage: you can run with `make run-sample-proj` although you might want to configure the `SECONDS_TO_RUN_APP` variable in `settings.env` to be 0 for unlimited to try things out)\ne.g.\n```python\nfrom django_backblaze_b2 import BackblazeB2Storage\n\nclass MyModel(models.Model):\n file_field = models.FileField(\n upload_to=\"uploads\",\n storage=BackblazeB2Storage\n )\n```\n\n### Public/Logged-In/Private storage\n\n1. Add `django_backblaze_b2` to your `INSTALLED_APPS`\n1. Add the urls to your `urlpatterns` in the root `urls.py`:\n```python\n urlpatterns = [\n ...\n path('', include('django_backblaze_b2.urls')),\n ]\n```\n\n### Caching\n\nTo retrieve file metadata (\"file info\" as the b2 sdk names it), this library has to authorize and request data from b2 servers, even for just resolving the url for a file. Because these are network calls, and relatively expensive in comparison to a file-based storage, and because data is unlikely to change frequently, there is some caching done by this library. \nBy default, the account information (`account_info`) configuration of the settings uses a cache by the name of `django-backblaze-b2` which you must have in your `CACHES` section of your `settings.py`. This is to leverage django's thread-safe cache implementations, and if you are using a database cache table or memcached, (rather than LocMemCache) your cache can be shared by the multiple django processes that typically serve requests. \nIt is not recommended configure `account_info` with the `default` django cache, as the `clear()` method may be called during the backblaze lifecycle. \nIf you do not wish to use a django cache, 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). \nFor further discussion on this see https://github.com/ehossack/django-backblaze-b2/issues/16\n\n### Configurations\n\nYou may want to use your own bucket name, or set further configuration such as lazy authorization/validation, or specifying file metadata. \nRefer to [the options](./django_backblaze_b2/options.py) for all options. \nYou can modify the settings dict, but additionally override any setting with the `opts` keyword argument to the storage classes.\n\nTo specify different buckets to use for your public, logged-in, staff storage, you can set the \n`specificBucketNames` attribute of the settings dict.\n## Why\n\nThere are several Django storage packages out there already which support B2, but none met my needs. These are:\n\n* [django-storages](https://github.com/jschneier/django-storages)\n * Large community engagement \u2705\n * Well-tested \u2705\n * [Second-class support](https://github.com/jschneier/django-storages/issues/765) via [Apache Libcloud](https://github.com/apache/libcloud) \u274c\n * Disconnect in configuration and actual use \u274c\n * PR list with low turnaround \u274c\n* [django-b2](https://github.com/pyutil/django-b2)\n * Similar aim to this project, around official backblaze SDK \u2705\n * Mixed goals (storage, scripts) \u274c\n * Tests?? \u274c\n* [django-backblazeb2-storage](https://github.com/royendgel/django-backblazeb2-storage)\n * Simple configuration \u2705\n * Not based around python SDK (potentially harder to keep up with version changes) \u274c\n * Tests?? \u274c\n\n### S3 Compatible API\n\nBackblazed can be used with an [S3-compatible API](https://www.backblaze.com/b2/docs/s3_compatible_api.html)\nThis is great, but most packages use an older version of the S3 Api (v2). Backblaze uses v4.\n\n### What this package offers\n\n* Type Annotations\n* Tested\n* No hacks required to get up and running around API deficiencies (any hacks are not exposed in API)\n* Support for public/private files, restricted via Django user permissions\n* Support for CDN and cached url details\n\n## How it works\n\n* A simple implementation of the `django.core.files.storage.Storage` class provides handling for storage behaviour within your Django application\n* Three url routes are appended to the root of your application: \n 1. `/b2/`\n 2. `/b2l/`\n 3. `/b2s/`\nThese 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.\n* If you use a CDN config, you can specify the CDN options and then include the bucket url segments (`/file/<bucket-name>/`) if your CDN is proxying the classic b2 url (e.g. `f000.backblazeb2.com`) or not, if you are proxying the s3-compatible url.\n\n### Gotchas\n\n* 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`)\n* When retrieving files from the `PublicStorage`, `LoggedInStorage` or `StaffStorage`, 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.\n* Simply using `LoggedInStorage` or `StaffStorage` 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.\n* Once the file is uploaded, and someone obtains a file url (e.g. http://djangodomain.com/b2l/uploads/image.png), the django model is no longer involved in file resolution. This means that if you share the bucket between multiple use-cases, you could in theory find files that don't belong to your django app (e.g. some image2.png), or similarly if you delete/change your models, the files could still be downloaded. Consider using an app like [django-cleanup](https://github.com/un1t/django-cleanup) if this is important to you\n\n## Contributing\n\nContributions welcome!\n\n* Please ensure test coverage does not decrease in a meaningful way.\n* Ensure formatting is compliant (`make lint`)\n* Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)\n\n## Setting up for development\n\n### Requires\n\n* python\n* pyenv - align local version\n* GNU Make\n* (optional) docker - run sample app\n\n#### Version compatibility reminder\n[link](https://devguide.python.org/versions/)\n| Ver | Status | EOL |\n| ---- | -------- | ---------- |\n| 3.12 | bugfix | 2028-10 |\n| 3.11 | bugfix | 2027-10 |\n| 3.10 | security | 2026-10 |\n| 3.9 | security | 2025-10 |\n| 3.8 | security | 2024-10 |\n\n### Running\n\n1. `make setup`\n\n* You can run django with `make run-django` to test django app.\n* You can run tests with `make test`\n* You can view test coverage with `make test-coverage`, then see in the terminal, \nopen `test/htmlcov/index.html`\nor use `cov.xml` in your favourite IDE like VSCode\n\n### Releasing\n\n1. `make release`\n\n### Cleanup\n\n1. `make cleanup`\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "A Django app to use backblaze b2 as storage.",
"version": "6.0.2",
"project_urls": {
"Homepage": "https://github.com/ehossack/django-backblaze-b2/",
"Repository": "https://github.com/ehossack/django-backblaze-b2/"
},
"split_keywords": [
"django",
" storage",
" backblaze",
" b2",
" cloud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8da473fe70a7d6da15438ffc201728c534ac4ec60b466cdd62e49371851393d",
"md5": "e67566155a3adfb49f0da30125e2a1cf",
"sha256": "bbf5f333bc91e6f98fcd92a1ad47d4b9f5be24403a292a7deae5807ec9a046b0"
},
"downloads": -1,
"filename": "django_backblaze_b2-6.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e67566155a3adfb49f0da30125e2a1cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 18444,
"upload_time": "2024-09-10T05:38:25",
"upload_time_iso_8601": "2024-09-10T05:38:25.918969Z",
"url": "https://files.pythonhosted.org/packages/f8/da/473fe70a7d6da15438ffc201728c534ac4ec60b466cdd62e49371851393d/django_backblaze_b2-6.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f400da1c7a7c5a71672c34ebfb1042cb455a1eebdcc1ca79a4db434f4f21fd08",
"md5": "47608baefab415dd00b7c51f1cdf7b72",
"sha256": "1120c1a0cb024eabd7eba33faa759c559d4e0c4e959d88ef63a7a1a5850912c8"
},
"downloads": -1,
"filename": "django_backblaze_b2-6.0.2.tar.gz",
"has_sig": false,
"md5_digest": "47608baefab415dd00b7c51f1cdf7b72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 18506,
"upload_time": "2024-09-10T05:38:27",
"upload_time_iso_8601": "2024-09-10T05:38:27.588420Z",
"url": "https://files.pythonhosted.org/packages/f4/00/da1c7a7c5a71672c34ebfb1042cb455a1eebdcc1ca79a4db434f4f21fd08/django_backblaze_b2-6.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 05:38:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ehossack",
"github_project": "django-backblaze-b2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [],
"lcname": "django-backblaze-b2"
}
JSON
