From 2dd594dff4f68f36b345f454738c35f01e5dd48e Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Sun, 5 Dec 2010 07:35:10 +0000 Subject: [PATCH] Fixed #13162 and #11597 -- Improved the file handling documentation: Removed documentation of methods on django.core.files.File that did not exist, added documentation for undocumented methods and attributes that did exist, did a general cleanup of the text and organization, and added more metadata targets. Thanks to amenasse and tyrion.mx for the reports. git-svn-id: http://code.djangoproject.com/svn/django/trunk@14833 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/files/file.txt | 136 +++++++++++++++++++++------------------ docs/ref/files/index.txt | 2 +- docs/topics/files.txt | 10 +-- 3 files changed, 81 insertions(+), 67 deletions(-) diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index 652745c51c..1374d0179b 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -1,56 +1,54 @@ 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 -``File`` attributes and methods -------------------------------- - -The :mod:`django.core.files` module contains a built-in class for basic file -handling in Django. The :class:`File` class has the following attributes and -methods: +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:: path - - The absolute path to the file's location on a local filesystem. - - :doc:`Custom file storage systems ` may not store - files locally; files stored on these systems will have a ``path`` of - ``None``. - - .. attribute:: url - - The URL where the file can be retrieved. This is often useful in - :doc:`templates `; for example, a bit of a template for - displaying a ``Car`` (see above) might look like: - - .. code-block:: html+django - - {{ car.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()``. + 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. + 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. + 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__() @@ -61,38 +59,65 @@ methods: 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. + 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``. + 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. + 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 -Additional ``ImageFile`` attributes ------------------------------------- +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. + Width of the image in pixels. .. attribute:: height - Height of the image. + Height of the image in pixels. .. currentmodule:: django.core.files @@ -100,7 +125,7 @@ Additional methods on files attached to objects ----------------------------------------------- Any :class:`File` that's associated with an object (as with ``Car.photo``, -above) will also have a couple of extra methods: +below) will also have a couple of extra methods: .. method:: File.save(name, content, [save=True]) @@ -116,23 +141,12 @@ above) will also have a couple of extra methods: >>> car.photo.save('myphoto.jpg', contents, save=True) - Note that the ``content`` argument must be an instance of - :class:`File` or of a subclass of :class:`File` such as :class:`ContentFile`. + 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]) - Remove the file from the model instance and delete the underlying file. The - ``save`` argument works as above. - -``ContentFile`` objects ------------------------ - -.. class:: ContentFile(File) - -A ``ContentFile`` is a File-like object that takes string content, rather -than an actual file:: - - 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')) + 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/docs/ref/files/index.txt b/docs/ref/files/index.txt index 171fcc6391..552559ddcd 100644 --- a/docs/ref/files/index.txt +++ b/docs/ref/files/index.txt @@ -6,7 +6,7 @@ File handling :synopsis: File handling and storage .. toctree:: - :maxdepth: 1 + :maxdepth: 2 file storage diff --git a/docs/topics/files.txt b/docs/topics/files.txt index 619f7d3184..d1926c6ec1 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -50,9 +50,9 @@ it has all the methods and attributes described below. The ``File`` object =================== -Internally, Django uses a ``django.core.files.File`` any time it needs to -represent a file. This object is a thin wrapper around Python's `built-in file -object`_ with some Django-specific additions. +Internally, Django uses a :class:`django.core.files.File` instance any time it +needs to represent a file. This object is a thin wrapper around Python's +`built-in file object`_ with some Django-specific additions. .. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects @@ -68,8 +68,8 @@ using a Python built-in ``file`` object:: >>> f = open('/tmp/hello.world', 'w') >>> myfile = File(f) -Now you can use any of the ``File`` attributes and methods documented in -:doc:`/ref/files/file`. +Now you can use any of the documented attributes and methods +of the :class:`~django.core.files.File` class. File storage ============