Reference

This document contains the public Python API reference.

Fields

class privates.fields.PrivateMediaFieldFile(instance, field, name)

class privates.fields.PrivateMediaFieldMixin(*args, **kwargs)

Enable a private media storage for file-based model fields.

Use the mixin in combination with django’s FileField class or derivatives to set up the (default) private media storage.

Parameters:: storage – the (private) file storage to use. Expects a "privates" storage to be configured in your STORAGES setting. You can override this with a custom storage, see the upstream storage documentation: https://docs.djangoproject.com/en/stable/topics/files/#file-storage

class privates.fields.PrivateMediaFileField(*args, **kwargs)

A generic private media file field.

attr_class: alias of PrivateMediaFieldFile

class privates.fields.PrivateMediaImageField(*args, **kwargs)

A private media image field.

attr_class: alias of PrivateMediaImageFieldFile

class privates.fields.PrivateMediaImageFieldFile(instance, field, name)

Views

class privates.views.PrivateMediaView(**kwargs)

Verify the required permission and send the filefield content via sendfile.

The permissions of the user are verified before sending back any data. If the user has the correct permissions, the path of the specified field name is looked up on the object and passed to sendfile, which transforms it into the appropriate response header so the web-server can serve the file contents.

Parameters:

permission_required – the permission required to view the file
model – the model class to look up the object

file_field: str = ''

Name of the file field on the model to look up.

The path (on-disk) of the file is passed along to django_sendfile.sendfile().

sendfile_options: dict | None = None: Additional options for django_sendfile.sendfile().

Admin

class privates.admin.PrivateMediaMixin

Enable downloading private-media model fields in the admin.

Use this mixin to automatically replace the Django admin file field widget so that private media fields can be downloaded. Django’s default behaviour is to create URLs that are not actually served by the webserver (directly, and by design). Instead, a custom view is installed for each private media field of the model and registered in the admin URL configuration (automatically).

get_object(request, object_id, from_field=None)

Override to replace the readonly private media file field accessors.

See issue #10 - injecting the private media (admin specific) URLs for readonly fields is not possible since all the form field machinery gets bypassed, and a bunch of helpers/utilities that are private Django API are used to render a form, fieldsets, field lines and ultimately the field. This call chain ends up in django.db.models.fields.file.FieldFile.url. We cannot blindly always return the admin URL at the model level, since these URLs should not be exposed to non-admin users.

So, in the admin context we instead taint the model instance so that our custom FieldFile class/attr_class can introspect this and conditionally build up the correct URL.

get_private_media_fields() → Sequence[str]

Return a sequence of model field names that are private media fields.

By default, all private media fields are detected automatically. You can override this with the private_media_fields attribute or by overriding this method.

get_private_media_permission_required(field: str) → str

Return the permission required to download private media field contents.

The permission is specified in Django’s typical format: {app_label}.change_{model_name}. By default, users are allowed to download the model field contents if they have change permissions for the model.

Override this method if you want to use permissions specific to a particular field or set of fields, or specify private_media_permission_required for an alternative static permission.

Parameters:: field – name of the private media field

get_private_media_view(field: str): Construct a view for the given private media field on the model.

get_private_media_view_options(field: str) → dict: Specify any additional options to forward to django_sendfile.sendfile().

private_media_file_widget: alias of PrivateFileWidget

private_media_no_download_fields: Sequence[str] = ()

A list of field names for which downloads are forbidden.

By default, the contents for private media field are made downloadable through the custom widget. You can block this by specifying the name of the field(s) that should only be writable and not downloadable.

private_media_view_class

The Django view class to use for private media field content download views.

alias of PrivateMediaView

Testing helpers

class privates.test.temp_private_root(reset_storage: bool = True, update_sendfile_backend: bool = True)

Set up an isolated private media storage.

You can use this as a test class or test decorator. When enabled, the private media storage will be replaced with an in-memory storage, and the sendfile backend is updated to serve files from the in-memory storage.

Parameters:

reset_storage – If enabled (by default it is), the storage contents are reset in the test cleanup function when used as a class decorator.
update_sendfile_backend – If enabled (by default it is), the sendfile backend is updated with a custom backend to serve files from the in-memory storage.

Storages

class privates.storages.PrivateMediaStorage: Look up the privates storage from the settings.

privates.storages.private_media_storage = <privates.storages.PrivateMediaStorage object>

The default (lazy) private media storage.

This is kept lazy so that override_settings with STORAGES works, per the Django docs: https://docs.djangoproject.com/en/5.2/topics/files/#file-storage, though it requires a signal receiver on setting_changed - see: https://code.djangoproject.com/ticket/36504