diff options
Diffstat (limited to 'parts/django/docs/ref/files')
| -rw-r--r-- | parts/django/docs/ref/files/file.txt | 152 | ||||
| -rw-r--r-- | parts/django/docs/ref/files/index.txt | 12 | ||||
| -rw-r--r-- | parts/django/docs/ref/files/storage.txt | 119 |
3 files changed, 0 insertions, 283 deletions
diff --git a/parts/django/docs/ref/files/file.txt b/parts/django/docs/ref/files/file.txt deleted file mode 100644 index 1374d01..0000000 --- a/parts/django/docs/ref/files/file.txt +++ /dev/null @@ -1,152 +0,0 @@ -The ``File`` object -=================== - -The :mod:`django.core.files` module and its submodules contain built-in classes -for basic file handling in Django. - -.. currentmodule:: django.core.files - -The ``File`` Class ------------------- - -.. class:: File(file_object) - - The :class:`File` is a thin wrapper around Python's built-in file object - with some Django-specific additions. Internally, Django uses this class - any time it needs to represent a file. - - :class:`File` objects have the following attributes and methods: - - .. attribute:: name - - The name of file including the relative path from - :setting:`MEDIA_ROOT`. - - .. attribute:: size - - The size of the file in bytes. - - .. attribute:: file - - The underlying Python ``file`` object passed to - :class:`~django.core.files.File`. - - .. attribute:: mode - - The read/write mode for the file. - - .. method:: open([mode=None]) - - Open or reopen the file (which by definition also does - ``File.seek(0)``). The ``mode`` argument allows the same values - as Python's standard ``open()``. - - When reopening a file, ``mode`` will override whatever mode the file - was originally opened with; ``None`` means to reopen with the original - mode. - - .. method:: read([num_bytes=None]) - - Read content from the file. The optional ``size`` is the number of - bytes to read; if not specified, the file will be read to the end. - - .. method:: __iter__() - - Iterate over the file yielding one line at a time. - - .. method:: chunks([chunk_size=None]) - - Iterate over the file yielding "chunks" of a given size. ``chunk_size`` - defaults to 64 KB. - - This is especially useful with very large files since it allows them to - be streamed off disk and avoids storing the whole file in memory. - - .. method:: multiple_chunks([chunk_size=None]) - - Returns ``True`` if the file is large enough to require multiple chunks - to access all of its content give some ``chunk_size``. - - .. method:: write([content]) - - Writes the specified content string to the file. Depending on the - storage system behind the scenes, this content might not be fully - committed until ``close()`` is called on the file. - - .. method:: close() - - Close the file. - - In addition to the listed methods, :class:`~django.core.files.File` exposes - the following attributes and methods of the underlying ``file`` object: - ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``, - ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``, - ``truncate``, ``writelines``, ``xreadlines``. - -.. currentmodule:: django.core.files.base - -The ``ContentFile`` Class -------------------------- - -.. class:: ContentFile(File) - - The ``ContentFile`` class inherits from :class:`~django.core.files.File`, - but unlike :class:`~django.core.files.File` it operates on string content, - rather than an actual file. For example:: - - from django.core.files.base import ContentFile - - f1 = ContentFile("my string content") - f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8')) - -.. currentmodule:: django.core.files.images - -The ``ImageFile`` Class ------------------------ - -.. class:: ImageFile(file_object) - - Django provides a built-in class specifically for images. - :class:`django.core.files.images.ImageFile` inherits all the attributes - and methods of :class:`~django.core.files.File`, and additionally - provides the following: - - .. attribute:: width - - Width of the image in pixels. - - .. attribute:: height - - Height of the image in pixels. - -.. currentmodule:: django.core.files - -Additional methods on files attached to objects ------------------------------------------------ - -Any :class:`File` that's associated with an object (as with ``Car.photo``, -below) will also have a couple of extra methods: - -.. method:: File.save(name, content, [save=True]) - - Saves a new file with the file name and contents provided. This will not - replace the existing file, but will create a new file and update the object - to point to it. If ``save`` is ``True``, the model's ``save()`` method will - be called once the file is saved. That is, these two lines:: - - >>> car.photo.save('myphoto.jpg', contents, save=False) - >>> car.save() - - are the same as this one line:: - - >>> car.photo.save('myphoto.jpg', contents, save=True) - - Note that the ``content`` argument must be an instance of either - :class:`File` or of a subclass of :class:`File`, such as - :class:`ContentFile`. - -.. method:: File.delete([save=True]) - - Removes the file from the model instance and deletes the underlying file. - If ``save`` is ``True``, the model's ``save()`` method will be called once - the file is deleted. diff --git a/parts/django/docs/ref/files/index.txt b/parts/django/docs/ref/files/index.txt deleted file mode 100644 index 552559d..0000000 --- a/parts/django/docs/ref/files/index.txt +++ /dev/null @@ -1,12 +0,0 @@ -============= -File handling -============= - -.. module:: django.core.files - :synopsis: File handling and storage - -.. toctree:: - :maxdepth: 2 - - file - storage diff --git a/parts/django/docs/ref/files/storage.txt b/parts/django/docs/ref/files/storage.txt deleted file mode 100644 index 84ef00c..0000000 --- a/parts/django/docs/ref/files/storage.txt +++ /dev/null @@ -1,119 +0,0 @@ -File storage API -================ - -.. module:: django.core.files.storage - -Getting the current storage class ---------------------------------- - -Django provides two convenient ways to access the current storage class: - -.. class:: DefaultStorage - - :class:`~django.core.files.storage.DefaultStorage` provides - lazy access to the current default storage system as defined by - :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses - :func:`~django.core.files.storage.get_storage_class` internally. - -.. function:: get_storage_class([import_path=None]) - - Returns a class or module which implements the storage API. - - When called without the ``import_path`` parameter ``get_storage_class`` - will return the current default storage system as defined by - :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided, - ``get_storage_class`` will attempt to import the class or module from the - given path and will return it if successful. An exception will be - raised if the import is unsuccessful. - -The FileSystemStorage Class ---------------------------- - -.. class:: FileSystemStorage - - The :class:`~django.core.files.storage.FileSystemStorage` class implements - basic file storage on a local filesystem. It inherits from - :class:`~django.core.files.storage.Storage` and provides implementations - for all the public methods thereof. - - .. note:: - - The :class:`FileSystemStorage.delete` method will not raise - raise an exception if the given file name does not exist. - -The Storage Class ------------------ - -.. class:: Storage - - The :class:`~django.core.files.storage.Storage` class provides a - standardized API for storing files, along with a set of default - behaviors that all other storage systems can inherit or override - as necessary. - - .. method:: delete(name) - - Deletes the file referenced by ``name``. If deletion is not supported - on the targest storage system this will raise ``NotImplementedError`` - instead - - .. method:: exists(name) - - Returns ``True`` if a file referened by the given name already exists - in the storage system, or ``False`` if the name is available for a new - file. - - .. method:: get_available_name(name) - - Returns a filename based on the ``name`` parameter that's free and - available for new content to be written to on the target storage - system. - - - .. method:: get_valid_name(name) - - Returns a filename based on the ``name`` parameter that's suitable - for use on the target storage system. - - .. method:: listdir(path) - - Lists the contents of the specified path, returning a 2-tuple of lists; - the first item being directories, the second item being files. For - storage systems that aren't able to provide such a listing, this will - raise a ``NotImplementedError`` instead. - - .. method:: open(name, mode='rb') - - Opens the file given by ``name``. Note that although the returned file - is guaranteed to be a ``File`` object, it might actually be some - subclass. In the case of remote file storage this means that - reading/writing could be quite slow, so be warned. - - .. method:: path(name) - - The local filesystem path where the file can be opened using Python's - standard ``open()``. For storage systems that aren't accessible from - the local filesystem, this will raise ``NotImplementedError`` instead. - - .. method:: save(name, content) - - Saves a new file using the storage system, preferably with the name - specified. If there already exists a file with this name ``name``, the - storage system may modify the filename as necessary to get a unique - name. The actual name of the stored file will be returned. - - The ``content`` argument must be an instance of - :class:`django.core.files.File` or of a subclass of - :class:`~django.core.files.File`. - - .. method:: size(name) - - Returns the total size, in bytes, of the file referenced by ``name``. - For storage systems that aren't able to return the file size this will - raise ``NotImplementedError`` instead. - - .. method:: url(name) - - Returns the URL where the contents of the file referenced by ``name`` - can be accessed. For storage systems that don't support access by URL - this will raise ``NotImplementedError`` instead. |