{"id":20313080,"url":"https://github.com/edoburu/django-private-storage","last_synced_at":"2025-05-15T20:03:27.191Z","repository":{"id":11633758,"uuid":"70163264","full_name":"edoburu/django-private-storage","owner":"edoburu","description":"Private media file storage for Django projects","archived":false,"fork":false,"pushed_at":"2023-10-09T10:37:12.000Z","size":160,"stargazers_count":345,"open_issues_count":25,"forks_count":64,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-15T20:03:21.668Z","etag":null,"topics":["amazon-s3-storage","django","django-field","django-storages","file-storage"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edoburu.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-06T14:44:35.000Z","updated_at":"2025-04-29T11:28:25.000Z","dependencies_parsed_at":"2024-06-18T14:08:27.660Z","dependency_job_id":null,"html_url":"https://github.com/edoburu/django-private-storage","commit_stats":{"total_commits":124,"total_committers":22,"mean_commits":5.636363636363637,"dds":"0.25806451612903225","last_synced_commit":"cfe1e62e2458798760fe6f6c9825e2f663d25ac1"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdjango-private-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdjango-private-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdjango-private-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edoburu%2Fdjango-private-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edoburu","download_url":"https://codeload.github.com/edoburu/django-private-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414493,"owners_count":22067271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-s3-storage","django","django-field","django-storages","file-storage"],"created_at":"2024-11-14T18:09:11.828Z","updated_at":"2025-05-15T20:03:24.177Z","avatar_url":"https://github.com/edoburu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"django-private-storage\n======================\n\n.. image:: https://github.com/edoburu/django-private-storage/actions/workflows/tests.yaml/badge.svg?branch=master\n    :target: https://github.com/edoburu/django-private-storage/actions/workflows/tests.yaml\n.. image:: https://img.shields.io/pypi/v/django-private-storage.svg\n    :target: https://pypi.python.org/pypi/django-private-storage/\n.. image:: https://img.shields.io/pypi/l/django-private-storage.svg\n    :target: https://pypi.python.org/pypi/django-private-storage/\n.. image:: https://img.shields.io/codecov/c/github/edoburu/django-private-storage/master.svg\n    :target: https://codecov.io/github/edoburu/django-private-storage?branch=master\n\nThis module offers a private media file storage,\nso user uploads can be protected behind a login.\n\nIt uses the Django storage API's internally,\nso all form rendering and admin integration work out of the box.\n\nInstallation\n============\n\n::\n\n    pip install django-private-storage\n\nConfiguration\n-------------\n\nAdd to the settings:\n\n.. code-block:: python\n\n    INSTALLED_APPS += (\n        'private_storage',\n    )\n\n    PRIVATE_STORAGE_ROOT = '/path/to/private-media/'\n    PRIVATE_STORAGE_AUTH_FUNCTION = 'private_storage.permissions.allow_staff'\n\nAdd to ``urls.py``:\n\n.. code-block:: python\n\n    import private_storage.urls\n\n    urlpatterns += [\n        path('private-media/', include(private_storage.urls)),\n    ]\n\nUsage\n-----\n\nIn a Django model, add the ``PrivateFileField``:\n\n.. code-block:: python\n\n    from django.db import models\n    from private_storage.fields import PrivateFileField\n\n    class MyModel(models.Model):\n        title = models.CharField(\"Title\", max_length=200)\n        file = PrivateFileField(\"File\")\n\nThe ``PrivateFileField`` also accepts the following kwargs:\n\n* ``upload_to``: the optional subfolder in the ``PRIVATE_STORAGE_ROOT``.\n* ``upload_subfolder``: a function that defines the folder, it receives the current model ``instance``.\n* ``content_types``: allowed content types\n* ``max_file_size``: maximum file size in bytes. (1MB is 1024 * 1024)\n* ``storage``: the storage object to use, defaults to ``private_storage.storage.private_storage``\n\n\nImages\n------\n\nYou can also use ``PrivateImageField`` which only allows you to upload images:\n\n.. code-block:: python\n\n    from django.db import models\n    from private_storage.fields import PrivateImageField\n\n    class MyModel(models.Model):\n        title = models.CharField(\"Title\", max_length=200)\n        width = models.PositiveSmallIntegerField(default=0)\n        height = models.PositiveSmallIntegerField(default=0)\n        image = PrivateFileField(\"Image\", width_field='width', height_field='height')\n\nThe ``PrivateImageField`` also accepts the following kwargs on top of ``PrivateFileField``:\n\n* ``width_field``: optional field for that stores the width of the image\n* ``height_field``: optional field for that stores the height of the image\n\nOther topics\n============\n\nStoring files on Amazon S3\n--------------------------\n\nThe ``PRIVATE_STORAGE_CLASS`` setting can be redefined to point to a different storage class.\nThe default is ``private_storage.storage.files.PrivateFileSystemStorage``, which uses\na private media folder that ``PRIVATE_STORAGE_ROOT`` points to.\n\nDefine one of these settings instead:\n\n.. code-block:: python\n\n    PRIVATE_STORAGE_CLASS = 'private_storage.storage.s3boto3.PrivateS3BotoStorage'\n\n    AWS_PRIVATE_STORAGE_BUCKET_NAME = 'private-files'  # bucket name\n\nThis uses django-storages_ settings. Replace the prefix ``AWS_`` with ``AWS_PRIVATE_``.\nThe following settings are reused when they don't have an corresponding ``AWS_PRIVATE_...`` setting:\n\n* ``AWS_ACCESS_KEY_ID``\n* ``AWS_SECRET_ACCESS_KEY``\n* ``AWS_S3_URL_PROTOCOL``\n* ``AWS_S3_REGION_NAME``\n* ``AWS_IS_GZIPPED``\n\nAll other settings should be explicitly defined with ``AWS_PRIVATE_...`` settings.\n\nBy default, all URLs in the admin return the direct S3 bucket URls, with the `query parameter authentication`_ enabled.\nWhen ``AWS_PRIVATE_QUERYSTRING_AUTH = False``, all file downloads are proxied through our ``PrivateFileView`` URL.\nThis behavior can be enabled explicitly using ``PRIVATE_STORAGE_S3_REVERSE_PROXY = True``.\n\nTo have encryption either configure ``AWS_PRIVATE_S3_ENCRYPTION``\nand ``AWS_PRIVATE_S3_SIGNATURE_VERSION`` or use:\n\n.. code-block:: python\n\n    PRIVATE_STORAGE_CLASS = 'private_storage.storage.s3boto3.PrivateEncryptedS3BotoStorage'\n\nMake sure an encryption key is generated on Amazon.\n\nMinIO storage\n--------------------------\n\nDefine one of these settings :\n\n.. code-block:: python\n\n    PRIVATE_STORAGE_CLASS = 'private_storage.storage.minio.PrivateMinioStorage'\n\n    MINIO_PRIVATE_STORAGE_MEDIA_BUCKET_NAME = 'private-files'\n    MINIO_PRIVATE_STORAGE_MEDIA_URL= '/private-files'\n\nThis uses django-minio-storage_ settings. Replace the prefix ``MINIO_`` with ``MINIO_PRIVATE_``.\nThe all settings are reused when they don't have an corresponding ``MINIO_PRIVATE_...`` setting.\n\n* ``MINIO_STORAGE_ENDPOINT``\n* ``MINIO_STORAGE_ACCESS_KEY``\n* ``MINIO_STORAGE_SECRET_KEY``\n* ``MINIO_STORAGE_USE_HTTPS``\n* ``MINIO_STORAGE_MEDIA_BUCKET_NAME``\n* ``MINIO_STORAGE_MEDIA_URL``\n* ``MINIO_STORAGE_AUTO_CREATE_MEDIA_BUCKET``\n* ``MINIO_STORAGE_AUTO_CREATE_MEDIA_POLICY``\n* ``MINIO_STORAGE_MEDIA_USE_PRESIGNED``\n* ``MINIO_STORAGE_MEDIA_BACKUP_FORMAT``\n* ``MINIO_STORAGE_ASSUME_MEDIA_BUCKET_EXISTS``\n* ``MINIO_STORAGE_MEDIA_OBJECT_METADATA``\n\nAs with S3, you can enable proxy through our ``PrivateFileView`` URL.\nJust specify ``PRIVATE_STORAGE_MINO_REVERSE_PROXY = True``.\n\nDefining access rules\n---------------------\n\nThe ``PRIVATE_STORAGE_AUTH_FUNCTION`` defines which user may access the files.\nBy default, this only includes superusers.\n\nThe following options are available out of the box:\n\n* ``private_storage.permissions.allow_authenticated``\n* ``private_storage.permissions.allow_staff``\n* ``private_storage.permissions.allow_superuser``\n\nYou can create a custom function, and use that instead.\nThe function receives a ``private_storage.models.PrivateFile`` object,\nwhich has the following fields:\n\n* ``request``: the Django request.\n* ``storage``: the storage engine used to retrieve the file.\n* ``relative_name``: the file name in the storage.\n* ``full_path``: the full file system path.\n* ``exists()``: whether the file exists.\n* ``content_type``: the HTTP content type.\n* ``parent_object``: only set when ``PrivateStorageDetailView`` was used.\n\n\nRetrieving files by object ID\n-----------------------------\n\nTo implement more object-based access permissions,\ncreate a custom view that provides the download.\n\n.. code-block:: python\n\n    from private_storage.views import PrivateStorageDetailView\n\n    class MyDocumentDownloadView(PrivateStorageDetailView):\n        model = MyModel\n        model_file_field = 'file'\n\n        def get_queryset(self):\n            # Make sure only certain objects can be accessed.\n            return super().get_queryset().filter(...)\n\n        def can_access_file(self, private_file):\n            # When the object can be accessed, the file may be downloaded.\n            # This overrides PRIVATE_STORAGE_AUTH_FUNCTION\n            return True\n\nThe following class-level attributes can be overwritten:\n\n* ``model``: The model to fetch (including every other attribute of ``SingleObjectMixin``).\n* ``model_file_field``: This should point to the field used to store the file.\n* ``storage`` / ``get_storage()``: The storage class to read the file from.\n* ``server_class``: The Python class used to generate the ``HttpResponse`` / ``FileResponse``.\n* ``content_disposition``: Can be \"inline\" (show inside the browser) or \"attachment\" (saved as download).\n* ``content_disposition_filename`` / ``get_content_disposition_filename()``: Overrides the filename for downloading.\n\n\nOptimizing large file transfers\n-------------------------------\n\nSending large files can be inefficient in some configurations.\n\nIn the worst case scenario, the whole file needs to be read in chunks\nand passed as a whole through the WSGI buffers, OS kernel, webserver and proxy server.\nIn effect, the complete file is copied several times through memory buffers.\n\nThere are more efficient ways to transfer files, such as the ``sendfile()`` system call on UNIX.\nDjango uses such feature when the WSGI server provides ``wsgi.file_handler`` support.\n\nIn some situations, this effect is nullified,\nfor example by by a local HTTP server sitting in front of the WSGI container.\nA typical case would be  running Gunicorn behind an Nginx or Apache webserver.\n\nFor such situation, the native support of the\nwebserver can be enabled with the following settings:\n\nFor apache\n~~~~~~~~~~\n\n.. code-block:: python\n\n    PRIVATE_STORAGE_SERVER = 'apache'\n\nThis requires in addition an installed and activated mod_xsendfile Apache module.\nAdd the following XSendFile configurations to your conf.d config file.\n\n.. code-block:: apache\n\n    \u003cvirtualhost ...\u003e\n    ...\n    WSGIScriptAlias / ...\n    XSendFile On\n    XSendFilePath ... [path to where the files are, same as PRIVATE_STORAGE_ROOT]\n    ...\n    \u003c/virtualhost\u003e\n\n\nFor Nginx\n~~~~~~~~~\n\n.. code-block:: python\n\n    PRIVATE_STORAGE_SERVER = 'nginx'\n    PRIVATE_STORAGE_INTERNAL_URL = '/private-x-accel-redirect/'\n\nAdd the following location block in the server config:\n\n.. code-block:: nginx\n\n    location /private-x-accel-redirect/ {\n      internal;\n      alias   /path/to/private-media/;\n    }\n\nFor very old Nginx versions, you'll have to configure ``PRIVATE_STORAGE_NGINX_VERSION``,\nbecause Nginx versions before 1.5.9 (released in 2014) handle non-ASCII filenames differently.\n\nOther webservers\n~~~~~~~~~~~~~~~~\n\nThe ``PRIVATE_STORAGE_SERVER`` may also point to a dotted Python class path.\nImplement a class with a static ``serve(private_file)`` method.\n\nUsing multiple storages\n-----------------------\n\nThe ``PrivateFileField`` accepts a ``storage`` kwarg,\nhence you can initialize multiple ``private_storage.storage.PrivateStorage`` objects,\neach providing files from a different ``location`` and ``base_url``.\n\nFor example:\n\n.. code-block:: python\n\n\n    from django.db import models\n    from private_storage.fields import PrivateFileField\n    from private_storage.storage.files import PrivateFileSystemStorage\n\n    my_storage = PrivateFileSystemStorage(\n        location='/path/to/storage2/',\n        base_url='/private-documents2/'\n    )\n\n    class MyModel(models.Model):\n        file = PrivateFileField(storage=my_storage)\n\n\nThen create a view to serve those files:\n\n.. code-block:: python\n\n    from private_storage.views import PrivateStorageView\n    from .models import my_storage\n\n    class MyStorageView(PrivateStorageView):\n        storage = my_storage\n\n        def can_access_file(self, private_file):\n            # This overrides PRIVATE_STORAGE_AUTH_FUNCTION\n            return self.request.is_superuser\n\nAnd expose that URL:\n\n.. code-block:: python\n\n    urlpatterns += [\n        url('^private-documents2/(?P\u003cpath\u003e.*)$', views.MyStorageView.as_view()),\n    ]\n\n\nContributing\n------------\n\nThis module is designed to be generic. In case there is anything you didn't like about it,\nor think it's not flexible enough, please let us know. We'd love to improve it!\n\nRunning tests\n~~~~~~~~~~~~~\n\nWe use tox to run the test suite on different versions locally (and travis-ci to automate the check for PRs).\n\nTo tun the test suite locally, please make sure your python environment has tox and django installed::\n\n    python3.6 -m pip install tox django\n\nAnd then simply execute tox to run the whole test matrix::\n\n    tox\n\n.. _django-storages: https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html\n.. _django-minio-storage: https://django-minio-storage.readthedocs.io/en/latest/usage/#django-settings-configuration\n.. _query parameter authentication: https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedoburu%2Fdjango-private-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedoburu%2Fdjango-private-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedoburu%2Fdjango-private-storage/lists"}