django-private-storage


Namedjango-private-storage JSON
Version 1.0.2 PyPI version JSON
home_pagehttps://github.com/edoburu/django-private-storage
SummaryPrivate media file storage for Django projects
upload_time2017-01-11 10:49:25
maintainer
docs_urlNone
authorDiederik van der Boor
requires_python
licenseApache 2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
Coveralis test coverage No Coveralis.
            django-private-storage
======================

This module offers a private media file storage,
so user uploads can be protected behind a login.

It uses the Django storage API's internally,
so all form rendering and admin integration work out of the box.

Installation
============

::

    pip install django-private-storage

Configuration
-------------

Add to the settings:

.. code-block:: python

    INSTALLED_APPS += (
        'private_storage',
    )

    PRIVATE_STORAGE_ROOT = '/path/to/private-media/'
    PRIVATE_STORAGE_AUTH_FUNCTION = 'apps.utils.private_storage.permissions.allow_staff'

Add to ``urls.py``:

.. code-block:: python

    import private_storage.urls

    urlpatterns += [
        url('^private-media/', include(private_storage.urls)),
    ]

Usage
-----

In a Django model, add the ``PrivateFileField``:

.. code-block:: python

    from django.db import models
    from private_storage.fields import PrivateFileField

    class MyModel(models.Model):
        title = models.CharField("Title", max_length=200)
        file = PrivateFileField("File")

The ``PrivateFileField`` also accepts the following kwargs:

* ``upload_to``: the optional subfolder in the ``PRIVATE_STORAGE_ROOT``.
* ``upload_subfolder``: a function that defines the folder, it receives the current model ``instance``.
* ``content_types``: allowed content types
* ``max_file_size``: maximum file size.
* ``storage``: the storage object to use, defaults to ``private_storage.storage.private_storage``

Other topics
============

Defining access rules
---------------------

The ``PRIVATE_STORAGE_AUTH_FUNCTION`` defines which user may access the files.
By default, this only includes superusers.

The following options are available out of the box:

* ``private_storage.permissions.allow_authenticated``
* ``private_storage.permissions.allow_staff``
* ``private_storage.permissions.allow_superuser``

You can create a custom function, and use that instead.
The function receives a ``private_storate.models.PrivateFile`` object,
which has the following fields:

* ``request``: the Django request.
* ``storage``: the storage engine used to retrieve the file.
* ``relative_name``: the file name in the storage.
* ``full_path``: the full file system path.
* ``exists()``: whether the file exists.
* ``content_type``: the HTTP content type.

Optimizing large file transfers
-------------------------------

By default, the files are served by the Django instance.
This can be inefficient, since the whole file needs to be read in chunks
and passed through the WSGI buffers, OS kernel and webserver.
In effect, the complete file is copied several times through memory buffers.

Hence, webservers offer a method to send the file on behalf of the backend application.
This happens with the ``sendfile()`` system call,
which can be enabled with the following settings:

For apache
~~~~~~~~~~

.. code-block:: python

    PRIVATE_STORAGE_SERVER = 'apache'

For Nginx
~~~~~~~~~

.. code-block:: python

    PRIVATE_STORAGE_SERVER = 'nginx'
    PRIVATE_STORAGE_INTERNAL_URL = '/private-x-accel-redirect/'

Add the following location block in the server config:

.. code-block:: nginx

    location /private-x-accel-redirect/ {
      internal;
      alias   /path/to/private-media/;
    }

Other webservers
~~~~~~~~~~~~~~~~

The ``PRIVATE_STORAGE_SERVER`` may also point to a dotted Python class path.
Implement a class with a static ``serve(private_file)`` method.

Using multiple storages
-----------------------

The ``PrivateFileField`` accepts a ``storage`` kwarg,
hence you can initialize multiple ``private_storage.storage.PrivateStorage`` objects,
each providing files from a different ``location`` and ``base_url``.

For example:

.. code-block:: python


    from django.db import models
    from private_storage.fields import PrivateFileField
    from private_storage.storage import PrivateStorage

    my_storage = PrivateStorage(
        location='/path/to/storage2/',
        base_url='/private-documents2/'
    )

    class MyModel(models.Model):
        file = PrivateFileField(storage=my_storage)


Then create a view to serve those files:

.. code-block:: python

    from private_storage.views import PrivateStorageView
    from .models import my_storage

    class MyStorageView(PrivateStorageView):
        storage = my_storage

        def can_access_file(self, private_file):
            # This overrides PRIVATE_STORAGE_AUTH_FUNCTION
            return self.request.is_superuser

And expose that URL:

.. code-block:: python

    urlpatterns += [
        url(^private-documents2/(?P<path>.*)$', views.MyStorageView.as_view()),
    ]

Contributing
------------

This module is designed to be generic. In case there is anything you didn't like about it,
or think it's not flexible enough, please let us know. We'd love to improve it!
            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "coveralis": false, 
    "keywords": "", 
    "upload_time": "2017-01-11 10:49:25", 
    "author": "Diederik van der Boor", 
    "home_page": "https://github.com/edoburu/django-private-storage", 
    "github_user": "edoburu", 
    "download_url": "https://pypi.python.org/packages/c1/d1/69d23c33b6ba08028bd730e2435c2183d121725a9fd100004c7fd7203d61/django-private-storage-1.0.2.tar.gz", 
    "platform": "UNKNOWN", 
    "version": "1.0.2", 
    "cheesecake_documentation_id": null, 
    "description": "django-private-storage\n======================\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 = 'apps.utils.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        url('^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.\n* ``storage``: the storage object to use, defaults to ``private_storage.storage.private_storage``\n\nOther topics\n============\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_storate.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\nOptimizing large file transfers\n-------------------------------\n\nBy default, the files are served by the Django instance.\nThis can be inefficient, since the whole file needs to be read in chunks\nand passed through the WSGI buffers, OS kernel and webserver.\nIn effect, the complete file is copied several times through memory buffers.\n\nHence, webservers offer a method to send the file on behalf of the backend application.\nThis happens with the ``sendfile()`` system call,\nwhich can be enabled with the following settings:\n\nFor apache\n~~~~~~~~~~\n\n.. code-block:: python\n\n    PRIVATE_STORAGE_SERVER = 'apache'\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\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 import PrivateStorage\n\n    my_storage = PrivateStorage(\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<path>.*)$', views.MyStorageView.as_view()),\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!", 
    "lcname": "django-private-storage", 
    "bugtrack_url": null, 
    "github": true, 
    "name": "django-private-storage", 
    "license": "Apache 2.0", 
    "travis_ci": false, 
    "github_project": "django-private-storage", 
    "summary": "Private media file storage for Django projects", 
    "split_keywords": [], 
    "author_email": "opensource@edoburu.nl", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2017-01-11T10:49:25", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/c1/d1/69d23c33b6ba08028bd730e2435c2183d121725a9fd100004c7fd7203d61/django-private-storage-1.0.2.tar.gz", 
            "md5_digest": "bf9a2456696a1eb1e42a37b33b3bb311", 
            "downloads": 0, 
            "filename": "django-private-storage-1.0.2.tar.gz", 
            "packagetype": "sdist", 
            "path": "c1/d1/69d23c33b6ba08028bd730e2435c2183d121725a9fd100004c7fd7203d61/django-private-storage-1.0.2.tar.gz", 
            "size": 13916
        }, 
        {
            "has_sig": false, 
            "upload_time": "2017-01-11T10:49:23", 
            "comment_text": "", 
            "python_version": "py2.py3", 
            "url": "https://pypi.python.org/packages/d7/11/aeaf4c369ebf21c3b8ce565595caee58bf149725e79d9a09f87f61d8f525/django_private_storage-1.0.2-py2.py3-none-any.whl", 
            "md5_digest": "6155979ee99f5f75594abbce8f8a42b0", 
            "downloads": 0, 
            "filename": "django_private_storage-1.0.2-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "d7/11/aeaf4c369ebf21c3b8ce565595caee58bf149725e79d9a09f87f61d8f525/django_private_storage-1.0.2-py2.py3-none-any.whl", 
            "size": 15085
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}