document how to use PrivateStorageDetailView, add `parent_object` field.

README.rst

@@ -133,6 +133,32 @@ which has the following fields:
 * ``full_path``: the full file system path.
 * ``exists()``: whether the file exists.
 * ``content_type``: the HTTP content type.
+* ``parent_object``: only set when ``PrivateStorageDetailView`` was used.
+
+
+Retrieving files by object ID
+-----------------------------
+
+To implement more object-based access permissions,
+create a custom view that provides the download.
+
+.. code-block:: python
+
+    from private_storage.views import PrivateStorageDetailView
+
+    class MyDocumentDownloadView(PrivateStorageDetailView):
+        model = MyModel
+        model_file_field = 'file'
+
+        def get_queryset(self):
+            # Make sure only certain objects can be accessed.
+            return super().get_queryset().filter(...)
+
+        def can_access_file(self, private_file):
+            # When the object can be accessed, the file may be downloaded.
+            # This overrides PRIVATE_STORAGE_AUTH_FUNCTION
+            return True
+
 
 Optimizing large file transfers
 -------------------------------
@@ -230,6 +256,7 @@ And expose that URL:
         url('^private-documents2/(?P<path>.*)$', views.MyStorageView.as_view()),
     ]
 
+
 Contributing
 ------------
 

private_storage/models.py

@@ -10,10 +10,11 @@ class PrivateFile(object):
     A wrapper object that describes the file that is being accessed.
     """
 
-    def __init__(self, request, storage, relative_name):
+    def __init__(self, request, storage, relative_name, parent_object=None):
         self.request = request
         self.storage = storage  # type: Storage
         self.relative_name = relative_name
+        self.parent_object = parent_object
 
     @cached_property
     def full_path(self):

private_storage/views.py

@@ -136,6 +136,15 @@ class PrivateStorageDetailView(SingleObjectMixin, PrivateStorageView):
         file = getattr(self.object, self.model_file_field)
         return file.name
 
+    def get_private_file(self):
+        # Provide the parent object as well.
+        return PrivateFile(
+            request=self.request,
+            storage=self.storage,
+            relative_name=self.get_path(),
+            parent_object=self.object
+        )
+
     def can_access_file(self, private_file):
         """
         The authorization rule for this view.