#############
File wrappers
#############

.. module:: django_downloadview.files

A view return :class:`~django_downloadview.response.DownloadResponse` which
itself carries a file wrapper. Here are file wrappers distributed by Django
and django-downloadview.


*****************
Django's builtins
*****************

`Django itself provides some file wrappers`_ you can use within
``django-downloadview``:

* :class:`django.core.files.File` wraps a file that live on local
  filesystem, initialized with a path. ``django-downloadview`` uses this
  wrapper in :doc:`/views/path`.

* :class:`django.db.models.fields.files.FieldFile` wraps a file that is
  managed in a model. ``django-downloadview`` uses this wrapper in 
  :doc:`/views/object`.

* :class:`django.core.files.base.ContentFile` wraps a bytes, string or
  unicode object. You may use it with :doc:`VirtualDownloadView
  </views/virtual>`.


****************************
django-downloadview builtins
****************************

``django-downloadview`` implements additional file wrappers:

* :class:`StorageFile` wraps a file that is
  managed via a storage (but not necessarily via a model).
  :doc:`/views/storage` uses this wrapper.

* :class:`HTTPFile` wraps a file that lives at
  some (remote) location, initialized with an URL.
  :doc:`/views/http` uses this wrapper.

* :class:`VirtualFile` wraps a file that lives in
  memory, i.e. built as a string.
  This is a convenient wrapper to use in :doc:`/views/virtual` subclasses.


**********************
Low-level IO utilities
**********************

`django-downloadview` provides two classes to implement file-like objects
whose content is dynamically generated:

* :class:`~django_downloadview.io.TextIteratorIO` for generated text;
* :class:`~django_downloadview.io.BytesIteratorIO` for generated bytes.

These classes may be handy to serve dynamically generated files. See
:doc:`/views/virtual` for details.

.. tip::

   **Text or bytes?** (formerly "unicode or str?") As `django-downloadview`
   is meant to serve files, as opposed to read or parse files, what matters
   is file contents is preserved. `django-downloadview` tends to handle files
   in binary mode and as bytes.


*************
API reference
*************

StorageFile
===========

.. autoclass:: StorageFile
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource

HTTPFile
========

.. autoclass:: HTTPFile
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource


VirtualFile
===========

.. autoclass:: VirtualFile
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource


BytesIteratorIO
===============

.. autoclass:: django_downloadview.io.BytesIteratorIO
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource


TextIteratorIO
==============

.. autoclass:: django_downloadview.io.TextIteratorIO
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource


.. rubric:: Notes & references

.. target-notes::

.. _`Django itself provides some file wrappers`:
   https://docs.djangoproject.com/en/3.0/ref/files/file/
