django-zerobucket 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- django_zerobucket-0.1.0/.gitignore +32 -0
- django_zerobucket-0.1.0/PKG-INFO +220 -0
- django_zerobucket-0.1.0/README.md +179 -0
- django_zerobucket-0.1.0/pyproject.toml +69 -0
- django_zerobucket-0.1.0/src/django_zerobucket/__init__.py +24 -0
- django_zerobucket-0.1.0/src/django_zerobucket/apps.py +7 -0
- django_zerobucket-0.1.0/src/django_zerobucket/management/__init__.py +0 -0
- django_zerobucket-0.1.0/src/django_zerobucket/management/commands/__init__.py +0 -0
- django_zerobucket-0.1.0/src/django_zerobucket/management/commands/zerobucket_info.py +28 -0
- django_zerobucket-0.1.0/src/django_zerobucket/management/commands/zerobucket_tier.py +63 -0
- django_zerobucket-0.1.0/src/django_zerobucket/management/commands/zerobucket_verify.py +35 -0
- django_zerobucket-0.1.0/src/django_zerobucket/storage.py +179 -0
- django_zerobucket-0.1.0/src/django_zerobucket/urls.py +26 -0
- django_zerobucket-0.1.0/src/django_zerobucket/views.py +104 -0
- django_zerobucket-0.1.0/tests/__init__.py +0 -0
- django_zerobucket-0.1.0/tests/conftest.py +59 -0
- django_zerobucket-0.1.0/tests/django_settings.py +47 -0
- django_zerobucket-0.1.0/tests/empty_urls.py +5 -0
- django_zerobucket-0.1.0/tests/test_management_commands.py +96 -0
- django_zerobucket-0.1.0/tests/test_storage.py +178 -0
- django_zerobucket-0.1.0/tests/test_views.py +70 -0
- django_zerobucket-0.1.0/tests/testapp/__init__.py +0 -0
- django_zerobucket-0.1.0/tests/testapp/migrations/0001_initial.py +37 -0
- django_zerobucket-0.1.0/tests/testapp/migrations/__init__.py +0 -0
- django_zerobucket-0.1.0/tests/testapp/models.py +17 -0
- django_zerobucket-0.1.0/tests/urls.py +5 -0
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.eggs/
|
|
6
|
+
build/
|
|
7
|
+
dist/
|
|
8
|
+
.pytest_cache/
|
|
9
|
+
.ruff_cache/
|
|
10
|
+
.mypy_cache/
|
|
11
|
+
htmlcov/
|
|
12
|
+
.coverage
|
|
13
|
+
|
|
14
|
+
# Virtual environments
|
|
15
|
+
.venv/
|
|
16
|
+
venv/
|
|
17
|
+
env/
|
|
18
|
+
|
|
19
|
+
# Environment / secrets -- never commit real credentials
|
|
20
|
+
.env
|
|
21
|
+
.env.*
|
|
22
|
+
!.env.example
|
|
23
|
+
|
|
24
|
+
# Editor/OS cruft
|
|
25
|
+
.vscode/
|
|
26
|
+
.idea/
|
|
27
|
+
.DS_Store
|
|
28
|
+
Thumbs.db
|
|
29
|
+
|
|
30
|
+
# Benchmark output (regenerate, don't version)
|
|
31
|
+
benchmarks/results.csv
|
|
32
|
+
benchmarks/test/retrieved*
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: django-zerobucket
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Django Storage backend for ZeroBucket -- database-native image storage via FileField/ImageField.
|
|
5
|
+
Project-URL: Homepage, https://github.com/KedarGhadyalji/ZeroBucket
|
|
6
|
+
Project-URL: Repository, https://github.com/KedarGhadyalji/ZeroBucket
|
|
7
|
+
Project-URL: Issues, https://github.com/KedarGhadyalji/ZeroBucket/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/KedarGhadyalji/ZeroBucket/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Kedar Ghadyalji <your-email@example.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
Keywords: django,image,postgresql,storage,zerobucket
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Framework :: Django
|
|
14
|
+
Classifier: Framework :: Django :: 5.2
|
|
15
|
+
Classifier: Framework :: Django :: 6.0
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Topic :: Database
|
|
24
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Requires-Dist: django>=5.2
|
|
28
|
+
Requires-Dist: zerobucket>=0.15.0
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: boto3>=1.34; extra == 'dev'
|
|
31
|
+
Requires-Dist: django-stubs>=5.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: moto[s3]>=5.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
|
|
35
|
+
Requires-Dist: pytest-django>=4.8; extra == 'dev'
|
|
36
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
37
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
38
|
+
Provides-Extra: s3
|
|
39
|
+
Requires-Dist: zerobucket[s3]>=0.15.0; extra == 's3'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# django-zerobucket
|
|
43
|
+
|
|
44
|
+
A Django [`Storage`](https://docs.djangoproject.com/en/stable/ref/files/storage/)
|
|
45
|
+
backend adapter for [ZeroBucket](https://github.com/KedarGhadyalji/ZeroBucket)
|
|
46
|
+
-- database-native image storage, plugged into Django's existing
|
|
47
|
+
`FileField`/`ImageField` machinery. No new field type to learn, works
|
|
48
|
+
with existing forms/admin/migrations the same way `django-storages`'
|
|
49
|
+
S3/GCS backends do for their targets.
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install django-zerobucket
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Requires Django >= 5.2 and a PostgreSQL database ZeroBucket can store
|
|
58
|
+
images in (see the [core `zerobucket` package](https://github.com/KedarGhadyalji/ZeroBucket)
|
|
59
|
+
for schema/setup details -- this package doesn't change any of that,
|
|
60
|
+
it's a thin adapter on top).
|
|
61
|
+
|
|
62
|
+
## Setup
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
# settings.py
|
|
66
|
+
INSTALLED_APPS = [
|
|
67
|
+
...,
|
|
68
|
+
"django_zerobucket", # needed for the zerobucket_* management commands
|
|
69
|
+
]
|
|
70
|
+
|
|
71
|
+
STORAGES = {
|
|
72
|
+
"default": {
|
|
73
|
+
"BACKEND": "django_zerobucket.storage.ZeroBucketStorage",
|
|
74
|
+
"OPTIONS": {"database_url": "postgresql://user:pass@localhost/mydb"},
|
|
75
|
+
},
|
|
76
|
+
}
|
|
77
|
+
# or, instead of OPTIONS above:
|
|
78
|
+
ZEROBUCKET_DATABASE_URL = "postgresql://user:pass@localhost/mydb"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
# project urls.py -- required for ZeroBucketStorage.url() to resolve
|
|
83
|
+
from django.urls import include, path
|
|
84
|
+
|
|
85
|
+
urlpatterns = [
|
|
86
|
+
...,
|
|
87
|
+
path("images/", include("django_zerobucket.urls")),
|
|
88
|
+
]
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
# models.py -- just a normal ImageField/FileField
|
|
93
|
+
class Product(models.Model):
|
|
94
|
+
photo = models.ImageField(upload_to="ignored")
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
That's it. `product.photo.save(...)`, `product.photo.read()`,
|
|
98
|
+
`product.photo.url`, `product.photo.delete()` -- all work exactly like
|
|
99
|
+
any other Django Storage backend from here.
|
|
100
|
+
|
|
101
|
+
## The one thing worth knowing before you adopt this
|
|
102
|
+
|
|
103
|
+
**The `name` Django stores for each file is a ZeroBucket image id (a
|
|
104
|
+
UUID), not a filesystem-style path.** Every other Django Storage
|
|
105
|
+
backend builds a path out of `upload_to=` plus the uploaded filename
|
|
106
|
+
(e.g. `"uploads/2024/photo.jpg"`) -- ZeroBucket is _id-addressed_
|
|
107
|
+
storage, not path-addressed, so there's no "directory" for a file to
|
|
108
|
+
live in. `upload_to=` is still required by Django's field API but is
|
|
109
|
+
effectively ignored by this backend.
|
|
110
|
+
|
|
111
|
+
This is invisible for the vast majority of normal usage
|
|
112
|
+
(`instance.photo.url`, `.read()`, `.open()`, template `{{ instance.photo.url }}`
|
|
113
|
+
all work exactly the same) -- it only matters if your code inspects the
|
|
114
|
+
raw `instance.photo.name` string and expects something path-shaped. The
|
|
115
|
+
original upload filename isn't lost, though: it's preserved in
|
|
116
|
+
ZeroBucket's own metadata and retrievable via the core `zerobucket`
|
|
117
|
+
client's `metadata()`/`get()` methods, even though Django's own `name`
|
|
118
|
+
field won't show it.
|
|
119
|
+
|
|
120
|
+
## Serving images
|
|
121
|
+
|
|
122
|
+
`ZeroBucketStorage.url()` reverses to a built-in view
|
|
123
|
+
(`ServeImageView`) that streams the image back via ZeroBucket's own
|
|
124
|
+
`get_stream()` -- a real use of the core library's streaming feature,
|
|
125
|
+
not just a demonstration of it.
|
|
126
|
+
|
|
127
|
+
**No built-in access control.** This is a deliberate first-pass scope
|
|
128
|
+
decision: ZeroBucket's own `before_get`/`before_put` hooks exist for
|
|
129
|
+
exactly this, but wiring a `context=` through Django's request/auth
|
|
130
|
+
system into those hooks is a real design question of its own (whose
|
|
131
|
+
context -- the request? the user? something else?) that's out of scope
|
|
132
|
+
for this first pass. If you need access control on served images,
|
|
133
|
+
protect the view the normal Django way:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from django.contrib.auth.decorators import login_required
|
|
137
|
+
from django_zerobucket.views import ServeImageView
|
|
138
|
+
|
|
139
|
+
urlpatterns = [
|
|
140
|
+
path("images/<uuid:image_id>/",
|
|
141
|
+
login_required(ServeImageView.as_view()),
|
|
142
|
+
name="my_protected_image"),
|
|
143
|
+
]
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
(and don't also `include("django_zerobucket.urls")`, or the same images
|
|
147
|
+
stay reachable unprotected there too.)
|
|
148
|
+
|
|
149
|
+
Want images served some other way entirely -- a CDN in front of tiered
|
|
150
|
+
S3 objects, presigned S3 URLs for images you've moved via
|
|
151
|
+
`tier_to_object_storage()`, whatever -- subclass `ZeroBucketStorage` and
|
|
152
|
+
override `url()`. This backend has no special knowledge of tiering one
|
|
153
|
+
way or the other, since transparent reads mean it doesn't need any.
|
|
154
|
+
|
|
155
|
+
## Management commands
|
|
156
|
+
|
|
157
|
+
Thin wrappers around the core `zerobucket` CLI's already-tested
|
|
158
|
+
`cmd_info`/`cmd_verify`/`cmd_tier` -- not reimplementations. Same
|
|
159
|
+
behavior, same flags, just reading `ZEROBUCKET_DATABASE_URL` from
|
|
160
|
+
Django settings instead of requiring `--database-url`:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
./manage.py zerobucket_info
|
|
164
|
+
./manage.py zerobucket_verify
|
|
165
|
+
./manage.py zerobucket_verify --sample 100
|
|
166
|
+
./manage.py zerobucket_tier IMAGE_ID --bucket my-bucket
|
|
167
|
+
./manage.py zerobucket_tier --all --bucket my-bucket
|
|
168
|
+
./manage.py zerobucket_tier --min-size 2000000 --older-than 90 --bucket my-bucket
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`zerobucket_tier` needs `boto3` (`pip install "zerobucket[s3]"`) the
|
|
172
|
+
same way the standalone `zerobucket tier` CLI command does -- not
|
|
173
|
+
pulled in by installing `django-zerobucket` itself. `zerobucket_verify`/
|
|
174
|
+
`zerobucket_tier` exit non-zero on failure (checksum mismatch, tier
|
|
175
|
+
failure), same convention the standalone CLI uses, so both are usable
|
|
176
|
+
in a cron job or CI/deploy step, not just interactively.
|
|
177
|
+
|
|
178
|
+
## What this package deliberately doesn't do (yet)
|
|
179
|
+
|
|
180
|
+
- **No custom model field.** A Storage adapter was judged the higher-
|
|
181
|
+
leverage, more idiomatic choice for a first pass -- it composes with
|
|
182
|
+
Django's existing `FileField`/`ImageField`, forms, and admin, rather
|
|
183
|
+
than asking every adopting project to learn a new field type.
|
|
184
|
+
- **No async support.** The core `zerobucket` package ships
|
|
185
|
+
`AsyncZeroBucket`; this package's `ZeroBucketStorage`/`ServeImageView`
|
|
186
|
+
are both built on the sync client. Django's own async views/ORM paths
|
|
187
|
+
aren't wired up to it yet.
|
|
188
|
+
- **No signal-based cleanup.** Django does not automatically delete
|
|
189
|
+
storage files when a model instance is deleted (this is a general
|
|
190
|
+
Django behavior, not specific to this backend -- confirmed directly,
|
|
191
|
+
not assumed) -- if you want images cleaned up when their owning model
|
|
192
|
+
is deleted, add a `post_delete` signal calling `instance.photo.delete()`
|
|
193
|
+
yourself, same as you would with any other Django Storage backend.
|
|
194
|
+
- **No `dedup=True`/tiering-aware URLs.** Both are fully supported at
|
|
195
|
+
the core `zerobucket` client level (pass the relevant options through
|
|
196
|
+
`STORAGES`' `OPTIONS`) and work transparently through this adapter --
|
|
197
|
+
there's just no Django-specific UI/behavior built on top of them yet
|
|
198
|
+
(e.g. an admin action to bulk-tier selected objects).
|
|
199
|
+
|
|
200
|
+
## Development
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
cd packages/django-zerobucket
|
|
204
|
+
pip install -e ".[dev]"
|
|
205
|
+
export ZEROBUCKET_TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zerobucket_test
|
|
206
|
+
pytest -q
|
|
207
|
+
ruff check src tests
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Tests run against a real PostgreSQL instance, used for two separate
|
|
211
|
+
roles simultaneously: Django's own `DATABASES` (its internal tables plus
|
|
212
|
+
this test suite's dummy `Product` model) and `ZEROBUCKET_DATABASE_URL`
|
|
213
|
+
(where ZeroBucket actually stores image bytes) -- see
|
|
214
|
+
`tests/django_settings.py`'s module docstring for why those are kept
|
|
215
|
+
conceptually distinct even when pointed at the same physical server in
|
|
216
|
+
this test setup.
|
|
217
|
+
|
|
218
|
+
## License
|
|
219
|
+
|
|
220
|
+
MIT, same as the core `zerobucket` package.
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# django-zerobucket
|
|
2
|
+
|
|
3
|
+
A Django [`Storage`](https://docs.djangoproject.com/en/stable/ref/files/storage/)
|
|
4
|
+
backend adapter for [ZeroBucket](https://github.com/KedarGhadyalji/ZeroBucket)
|
|
5
|
+
-- database-native image storage, plugged into Django's existing
|
|
6
|
+
`FileField`/`ImageField` machinery. No new field type to learn, works
|
|
7
|
+
with existing forms/admin/migrations the same way `django-storages`'
|
|
8
|
+
S3/GCS backends do for their targets.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install django-zerobucket
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Requires Django >= 5.2 and a PostgreSQL database ZeroBucket can store
|
|
17
|
+
images in (see the [core `zerobucket` package](https://github.com/KedarGhadyalji/ZeroBucket)
|
|
18
|
+
for schema/setup details -- this package doesn't change any of that,
|
|
19
|
+
it's a thin adapter on top).
|
|
20
|
+
|
|
21
|
+
## Setup
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
# settings.py
|
|
25
|
+
INSTALLED_APPS = [
|
|
26
|
+
...,
|
|
27
|
+
"django_zerobucket", # needed for the zerobucket_* management commands
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
STORAGES = {
|
|
31
|
+
"default": {
|
|
32
|
+
"BACKEND": "django_zerobucket.storage.ZeroBucketStorage",
|
|
33
|
+
"OPTIONS": {"database_url": "postgresql://user:pass@localhost/mydb"},
|
|
34
|
+
},
|
|
35
|
+
}
|
|
36
|
+
# or, instead of OPTIONS above:
|
|
37
|
+
ZEROBUCKET_DATABASE_URL = "postgresql://user:pass@localhost/mydb"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
# project urls.py -- required for ZeroBucketStorage.url() to resolve
|
|
42
|
+
from django.urls import include, path
|
|
43
|
+
|
|
44
|
+
urlpatterns = [
|
|
45
|
+
...,
|
|
46
|
+
path("images/", include("django_zerobucket.urls")),
|
|
47
|
+
]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
# models.py -- just a normal ImageField/FileField
|
|
52
|
+
class Product(models.Model):
|
|
53
|
+
photo = models.ImageField(upload_to="ignored")
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
That's it. `product.photo.save(...)`, `product.photo.read()`,
|
|
57
|
+
`product.photo.url`, `product.photo.delete()` -- all work exactly like
|
|
58
|
+
any other Django Storage backend from here.
|
|
59
|
+
|
|
60
|
+
## The one thing worth knowing before you adopt this
|
|
61
|
+
|
|
62
|
+
**The `name` Django stores for each file is a ZeroBucket image id (a
|
|
63
|
+
UUID), not a filesystem-style path.** Every other Django Storage
|
|
64
|
+
backend builds a path out of `upload_to=` plus the uploaded filename
|
|
65
|
+
(e.g. `"uploads/2024/photo.jpg"`) -- ZeroBucket is _id-addressed_
|
|
66
|
+
storage, not path-addressed, so there's no "directory" for a file to
|
|
67
|
+
live in. `upload_to=` is still required by Django's field API but is
|
|
68
|
+
effectively ignored by this backend.
|
|
69
|
+
|
|
70
|
+
This is invisible for the vast majority of normal usage
|
|
71
|
+
(`instance.photo.url`, `.read()`, `.open()`, template `{{ instance.photo.url }}`
|
|
72
|
+
all work exactly the same) -- it only matters if your code inspects the
|
|
73
|
+
raw `instance.photo.name` string and expects something path-shaped. The
|
|
74
|
+
original upload filename isn't lost, though: it's preserved in
|
|
75
|
+
ZeroBucket's own metadata and retrievable via the core `zerobucket`
|
|
76
|
+
client's `metadata()`/`get()` methods, even though Django's own `name`
|
|
77
|
+
field won't show it.
|
|
78
|
+
|
|
79
|
+
## Serving images
|
|
80
|
+
|
|
81
|
+
`ZeroBucketStorage.url()` reverses to a built-in view
|
|
82
|
+
(`ServeImageView`) that streams the image back via ZeroBucket's own
|
|
83
|
+
`get_stream()` -- a real use of the core library's streaming feature,
|
|
84
|
+
not just a demonstration of it.
|
|
85
|
+
|
|
86
|
+
**No built-in access control.** This is a deliberate first-pass scope
|
|
87
|
+
decision: ZeroBucket's own `before_get`/`before_put` hooks exist for
|
|
88
|
+
exactly this, but wiring a `context=` through Django's request/auth
|
|
89
|
+
system into those hooks is a real design question of its own (whose
|
|
90
|
+
context -- the request? the user? something else?) that's out of scope
|
|
91
|
+
for this first pass. If you need access control on served images,
|
|
92
|
+
protect the view the normal Django way:
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from django.contrib.auth.decorators import login_required
|
|
96
|
+
from django_zerobucket.views import ServeImageView
|
|
97
|
+
|
|
98
|
+
urlpatterns = [
|
|
99
|
+
path("images/<uuid:image_id>/",
|
|
100
|
+
login_required(ServeImageView.as_view()),
|
|
101
|
+
name="my_protected_image"),
|
|
102
|
+
]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
(and don't also `include("django_zerobucket.urls")`, or the same images
|
|
106
|
+
stay reachable unprotected there too.)
|
|
107
|
+
|
|
108
|
+
Want images served some other way entirely -- a CDN in front of tiered
|
|
109
|
+
S3 objects, presigned S3 URLs for images you've moved via
|
|
110
|
+
`tier_to_object_storage()`, whatever -- subclass `ZeroBucketStorage` and
|
|
111
|
+
override `url()`. This backend has no special knowledge of tiering one
|
|
112
|
+
way or the other, since transparent reads mean it doesn't need any.
|
|
113
|
+
|
|
114
|
+
## Management commands
|
|
115
|
+
|
|
116
|
+
Thin wrappers around the core `zerobucket` CLI's already-tested
|
|
117
|
+
`cmd_info`/`cmd_verify`/`cmd_tier` -- not reimplementations. Same
|
|
118
|
+
behavior, same flags, just reading `ZEROBUCKET_DATABASE_URL` from
|
|
119
|
+
Django settings instead of requiring `--database-url`:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
./manage.py zerobucket_info
|
|
123
|
+
./manage.py zerobucket_verify
|
|
124
|
+
./manage.py zerobucket_verify --sample 100
|
|
125
|
+
./manage.py zerobucket_tier IMAGE_ID --bucket my-bucket
|
|
126
|
+
./manage.py zerobucket_tier --all --bucket my-bucket
|
|
127
|
+
./manage.py zerobucket_tier --min-size 2000000 --older-than 90 --bucket my-bucket
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`zerobucket_tier` needs `boto3` (`pip install "zerobucket[s3]"`) the
|
|
131
|
+
same way the standalone `zerobucket tier` CLI command does -- not
|
|
132
|
+
pulled in by installing `django-zerobucket` itself. `zerobucket_verify`/
|
|
133
|
+
`zerobucket_tier` exit non-zero on failure (checksum mismatch, tier
|
|
134
|
+
failure), same convention the standalone CLI uses, so both are usable
|
|
135
|
+
in a cron job or CI/deploy step, not just interactively.
|
|
136
|
+
|
|
137
|
+
## What this package deliberately doesn't do (yet)
|
|
138
|
+
|
|
139
|
+
- **No custom model field.** A Storage adapter was judged the higher-
|
|
140
|
+
leverage, more idiomatic choice for a first pass -- it composes with
|
|
141
|
+
Django's existing `FileField`/`ImageField`, forms, and admin, rather
|
|
142
|
+
than asking every adopting project to learn a new field type.
|
|
143
|
+
- **No async support.** The core `zerobucket` package ships
|
|
144
|
+
`AsyncZeroBucket`; this package's `ZeroBucketStorage`/`ServeImageView`
|
|
145
|
+
are both built on the sync client. Django's own async views/ORM paths
|
|
146
|
+
aren't wired up to it yet.
|
|
147
|
+
- **No signal-based cleanup.** Django does not automatically delete
|
|
148
|
+
storage files when a model instance is deleted (this is a general
|
|
149
|
+
Django behavior, not specific to this backend -- confirmed directly,
|
|
150
|
+
not assumed) -- if you want images cleaned up when their owning model
|
|
151
|
+
is deleted, add a `post_delete` signal calling `instance.photo.delete()`
|
|
152
|
+
yourself, same as you would with any other Django Storage backend.
|
|
153
|
+
- **No `dedup=True`/tiering-aware URLs.** Both are fully supported at
|
|
154
|
+
the core `zerobucket` client level (pass the relevant options through
|
|
155
|
+
`STORAGES`' `OPTIONS`) and work transparently through this adapter --
|
|
156
|
+
there's just no Django-specific UI/behavior built on top of them yet
|
|
157
|
+
(e.g. an admin action to bulk-tier selected objects).
|
|
158
|
+
|
|
159
|
+
## Development
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
cd packages/django-zerobucket
|
|
163
|
+
pip install -e ".[dev]"
|
|
164
|
+
export ZEROBUCKET_TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zerobucket_test
|
|
165
|
+
pytest -q
|
|
166
|
+
ruff check src tests
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Tests run against a real PostgreSQL instance, used for two separate
|
|
170
|
+
roles simultaneously: Django's own `DATABASES` (its internal tables plus
|
|
171
|
+
this test suite's dummy `Product` model) and `ZEROBUCKET_DATABASE_URL`
|
|
172
|
+
(where ZeroBucket actually stores image bytes) -- see
|
|
173
|
+
`tests/django_settings.py`'s module docstring for why those are kept
|
|
174
|
+
conceptually distinct even when pointed at the same physical server in
|
|
175
|
+
this test setup.
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT, same as the core `zerobucket` package.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "django-zerobucket"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Django Storage backend for ZeroBucket -- database-native image storage via FileField/ImageField."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [{ name = "Kedar Ghadyalji", email = "your-email@example.com" }]
|
|
13
|
+
keywords = ["django", "image", "storage", "postgresql", "zerobucket"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Framework :: Django",
|
|
17
|
+
"Framework :: Django :: 5.2",
|
|
18
|
+
"Framework :: Django :: 6.0",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"License :: OSI Approved :: MIT License",
|
|
21
|
+
"Operating System :: OS Independent",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3.10",
|
|
24
|
+
"Programming Language :: Python :: 3.11",
|
|
25
|
+
"Programming Language :: Python :: 3.12",
|
|
26
|
+
"Topic :: Database",
|
|
27
|
+
"Topic :: Multimedia :: Graphics",
|
|
28
|
+
"Typing :: Typed",
|
|
29
|
+
]
|
|
30
|
+
dependencies = [
|
|
31
|
+
"Django>=5.2",
|
|
32
|
+
"zerobucket>=0.15.0",
|
|
33
|
+
]
|
|
34
|
+
|
|
35
|
+
[project.optional-dependencies]
|
|
36
|
+
s3 = [
|
|
37
|
+
"zerobucket[s3]>=0.15.0",
|
|
38
|
+
]
|
|
39
|
+
dev = [
|
|
40
|
+
"pytest>=8.0",
|
|
41
|
+
"pytest-django>=4.8",
|
|
42
|
+
"pytest-cov>=5.0",
|
|
43
|
+
"ruff>=0.6",
|
|
44
|
+
"mypy>=1.10",
|
|
45
|
+
"django-stubs>=5.0",
|
|
46
|
+
"boto3>=1.34",
|
|
47
|
+
"moto[s3]>=5.0",
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
[project.urls]
|
|
51
|
+
Homepage = "https://github.com/KedarGhadyalji/ZeroBucket"
|
|
52
|
+
Repository = "https://github.com/KedarGhadyalji/ZeroBucket"
|
|
53
|
+
Issues = "https://github.com/KedarGhadyalji/ZeroBucket/issues"
|
|
54
|
+
Changelog = "https://github.com/KedarGhadyalji/ZeroBucket/blob/main/CHANGELOG.md"
|
|
55
|
+
|
|
56
|
+
[tool.hatch.build.targets.wheel]
|
|
57
|
+
packages = ["src/django_zerobucket"]
|
|
58
|
+
|
|
59
|
+
[tool.ruff]
|
|
60
|
+
line-length = 100
|
|
61
|
+
target-version = "py310"
|
|
62
|
+
extend-exclude = ["**/migrations/*.py"]
|
|
63
|
+
|
|
64
|
+
[tool.ruff.lint]
|
|
65
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
66
|
+
|
|
67
|
+
[tool.pytest.ini_options]
|
|
68
|
+
DJANGO_SETTINGS_MODULE = "tests.django_settings"
|
|
69
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""django-zerobucket: a Django Storage backend adapter for ZeroBucket.
|
|
2
|
+
|
|
3
|
+
from django_zerobucket import ZeroBucketStorage
|
|
4
|
+
|
|
5
|
+
See storage.py's module docstring for the id-vs-path naming difference
|
|
6
|
+
from typical Django Storage backends, and views.py's for how served
|
|
7
|
+
images work and their access-control scope.
|
|
8
|
+
|
|
9
|
+
default_app_config is not needed (Django's app-loading auto-discovery
|
|
10
|
+
handles apps.py without it since Django 3.2) -- this package still
|
|
11
|
+
needs "django_zerobucket" added to INSTALLED_APPS for its management
|
|
12
|
+
commands (management/commands/zerobucket_*.py) to be discovered, even
|
|
13
|
+
though the Storage backend and serving view themselves would technically
|
|
14
|
+
work without that (Django's STORAGES/urlconf wiring doesn't require
|
|
15
|
+
INSTALLED_APPS membership, only manage.py's command discovery does).
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from .storage import ZeroBucketStorage
|
|
21
|
+
|
|
22
|
+
__version__ = "0.1.0"
|
|
23
|
+
|
|
24
|
+
__all__ = ["ZeroBucketStorage"]
|
|
File without changes
|
|
File without changes
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""./manage.py zerobucket_info -- thin wrapper around zerobucket.cli's
|
|
2
|
+
cmd_info, reusing that exact, already-tested implementation rather than
|
|
3
|
+
reimplementing it. Supplies database_url from the
|
|
4
|
+
ZEROBUCKET_DATABASE_URL Django setting (falling back further to the
|
|
5
|
+
ZEROBUCKET_DATABASE_URL environment variable, same as the standalone
|
|
6
|
+
CLI, since cmd_info's own _resolve_database_url already does that) so
|
|
7
|
+
you don't have to pass --database-url by hand in a Django project that
|
|
8
|
+
already has it configured.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import argparse
|
|
14
|
+
|
|
15
|
+
from django.conf import settings
|
|
16
|
+
from django.core.management.base import BaseCommand
|
|
17
|
+
from zerobucket.cli import cmd_info
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Command(BaseCommand):
|
|
21
|
+
help = "Report ZeroBucket storage stats: image count, total size, format breakdown."
|
|
22
|
+
|
|
23
|
+
def handle(self, *args, **options) -> None:
|
|
24
|
+
cmd_info(
|
|
25
|
+
argparse.Namespace(
|
|
26
|
+
database_url=getattr(settings, "ZEROBUCKET_DATABASE_URL", None)
|
|
27
|
+
)
|
|
28
|
+
)
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""./manage.py zerobucket_tier -- thin wrapper around zerobucket.cli's
|
|
2
|
+
cmd_tier. Same argument shape as the standalone `zerobucket tier` CLI
|
|
3
|
+
command (see that command's docs for the full explanation of single-id
|
|
4
|
+
vs bulk selection, --dry-run, and the transactional-safety guarantee of
|
|
5
|
+
tier_to_object_storage() underneath) -- this just supplies
|
|
6
|
+
database_url from Django settings instead of requiring --database-url,
|
|
7
|
+
and requires `pip install zerobucket[s3]` the same way the standalone
|
|
8
|
+
command does (boto3 stays an optional dependency here too, not pulled
|
|
9
|
+
in by installing django-zerobucket itself).
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import argparse
|
|
15
|
+
|
|
16
|
+
from django.conf import settings
|
|
17
|
+
from django.core.management.base import BaseCommand
|
|
18
|
+
from zerobucket.cli import cmd_tier
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Command(BaseCommand):
|
|
22
|
+
help = "Move image(s) from Postgres into S3-compatible object storage."
|
|
23
|
+
|
|
24
|
+
def add_arguments(self, parser: argparse.ArgumentParser) -> None:
|
|
25
|
+
parser.add_argument(
|
|
26
|
+
"image_id",
|
|
27
|
+
nargs="?",
|
|
28
|
+
default=None,
|
|
29
|
+
help="Tier a single image by id. Omit and use --all/--min-size/"
|
|
30
|
+
"--older-than instead for bulk selection.",
|
|
31
|
+
)
|
|
32
|
+
parser.add_argument(
|
|
33
|
+
"--bucket",
|
|
34
|
+
required=True,
|
|
35
|
+
help="S3(-compatible) bucket -- must already exist.",
|
|
36
|
+
)
|
|
37
|
+
parser.add_argument("--endpoint-url", default=None)
|
|
38
|
+
parser.add_argument("--region", default=None)
|
|
39
|
+
parser.add_argument("--aws-access-key-id", default=None)
|
|
40
|
+
parser.add_argument("--aws-secret-access-key", default=None)
|
|
41
|
+
parser.add_argument("--min-size", type=int, default=None, metavar="BYTES")
|
|
42
|
+
parser.add_argument("--older-than", type=int, default=None, metavar="DAYS")
|
|
43
|
+
parser.add_argument("--all", action="store_true")
|
|
44
|
+
parser.add_argument("--limit", type=int, default=None)
|
|
45
|
+
parser.add_argument("--dry-run", action="store_true")
|
|
46
|
+
|
|
47
|
+
def handle(self, *args, **options) -> None:
|
|
48
|
+
cmd_tier(
|
|
49
|
+
argparse.Namespace(
|
|
50
|
+
database_url=getattr(settings, "ZEROBUCKET_DATABASE_URL", None),
|
|
51
|
+
image_id=options["image_id"],
|
|
52
|
+
bucket=options["bucket"],
|
|
53
|
+
endpoint_url=options["endpoint_url"],
|
|
54
|
+
region=options["region"],
|
|
55
|
+
aws_access_key_id=options["aws_access_key_id"],
|
|
56
|
+
aws_secret_access_key=options["aws_secret_access_key"],
|
|
57
|
+
min_size=options["min_size"],
|
|
58
|
+
older_than=options["older_than"],
|
|
59
|
+
all=options["all"],
|
|
60
|
+
limit=options["limit"],
|
|
61
|
+
dry_run=options["dry_run"],
|
|
62
|
+
)
|
|
63
|
+
)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""./manage.py zerobucket_verify -- thin wrapper around
|
|
2
|
+
zerobucket.cli's cmd_verify. Note that cmd_verify calls sys.exit(1) on
|
|
3
|
+
any checksum mismatch (and sys.exit(2) on a bad/missing database URL) --
|
|
4
|
+
that propagates as this management command's process exit code
|
|
5
|
+
unchanged, the same way it would from the standalone CLI, making this
|
|
6
|
+
usable in a cron job or CI step exactly like `zerobucket verify` is.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
|
|
13
|
+
from django.conf import settings
|
|
14
|
+
from django.core.management.base import BaseCommand
|
|
15
|
+
from zerobucket.cli import cmd_verify
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class Command(BaseCommand):
|
|
19
|
+
help = "Re-checksum stored images to detect corruption."
|
|
20
|
+
|
|
21
|
+
def add_arguments(self, parser: argparse.ArgumentParser) -> None:
|
|
22
|
+
parser.add_argument(
|
|
23
|
+
"--sample",
|
|
24
|
+
type=int,
|
|
25
|
+
default=None,
|
|
26
|
+
help="Check a random sample of this many images instead of every one.",
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
def handle(self, *args, **options) -> None:
|
|
30
|
+
cmd_verify(
|
|
31
|
+
argparse.Namespace(
|
|
32
|
+
database_url=getattr(settings, "ZEROBUCKET_DATABASE_URL", None),
|
|
33
|
+
sample=options["sample"],
|
|
34
|
+
)
|
|
35
|
+
)
|