Author: gabrielhurley
Date: 2010-12-05 01:36:40 -0600 (Sun, 05 Dec 2010)
New Revision: 14834
Modified:
django/branches/releases/1.2.X/docs/ref/files/file.txt
django/branches/releases/1.2.X/docs/ref/files/index.txt
django/branches/releases/1.2.X/docs/topics/files.txt
Log:
[1.2.X] 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.
Backport of [14833] from trunk.
Modified: django/branches/releases/1.2.X/docs/ref/files/file.txt
===================================================================
--- django/branches/releases/1.2.X/docs/ref/files/file.txt 2010-12-05
07:35:10 UTC (rev 14833)
+++ django/branches/releases/1.2.X/docs/ref/files/file.txt 2010-12-05
07:36:40 UTC (rev 14834)
@@ -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 ``File`` Class
+------------------
-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:
-
.. 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`.
+ The name of file including the relative path from
+ :setting:`MEDIA_ROOT`.
- .. attribute:: path
+ .. attribute:: size
- The absolute path to the file's location on a local filesystem.
+ The size of the file in bytes.
- :doc:`Custom file storage systems </howto/custom-file-storage>` may
not store
- files locally; files stored on these systems will have a ``path`` of
- ``None``.
+ .. attribute:: file
- .. attribute:: url
+ The underlying Python ``file`` object passed to
+ :class:`~django.core.files.File`.
- The URL where the file can be retrieved. This is often useful in
- :doc:`templates </topics/templates>`; for example, a bit of a template
for
- displaying a ``Car`` (see above) might look like:
+ .. attribute:: mode
- .. code-block:: html+django
+ The read/write mode for the file.
- <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
-
- .. attribute:: size
-
- The size of the file in bytes.
-
.. 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 @@
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 @@
-----------------------------------------------
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 @@
>>> 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.
Modified: django/branches/releases/1.2.X/docs/ref/files/index.txt
===================================================================
--- django/branches/releases/1.2.X/docs/ref/files/index.txt 2010-12-05
07:35:10 UTC (rev 14833)
+++ django/branches/releases/1.2.X/docs/ref/files/index.txt 2010-12-05
07:36:40 UTC (rev 14834)
@@ -6,7 +6,7 @@
:synopsis: File handling and storage
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
file
storage
Modified: django/branches/releases/1.2.X/docs/topics/files.txt
===================================================================
--- django/branches/releases/1.2.X/docs/topics/files.txt 2010-12-05
07:35:10 UTC (rev 14833)
+++ django/branches/releases/1.2.X/docs/topics/files.txt 2010-12-05
07:36:40 UTC (rev 14834)
@@ -50,9 +50,9 @@
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 @@
>>> 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
============
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-upda...@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
