Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.2.X] Fixed #13040 -- Added info on where to import File class from…

… to File reference docs, and improved Sphinx formatting. Thanks to stherrien for the report.

Backport of [14339] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14340 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 4b61183840e43eee612de507e4b12470b61b5383 1 parent 92435e1
Gabriel Hurley authored
Showing with 59 additions and 53 deletions.
  1. +59 −53 docs/ref/files/file.txt
View
112 docs/ref/files/file.txt
@@ -3,100 +3,106 @@ The ``File`` object
.. currentmodule:: django.core.files
-.. class:: File(file_object)
-
``File`` attributes and methods
-------------------------------
-Django's ``File`` has the following 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:
+
+.. class:: File(file_object)
-.. attribute:: File.name
+ .. 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:: File.path
+ .. attribute:: path
- The absolute path to the file's location on a local filesystem.
+ The absolute path to the file's location on a local filesystem.
- :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``.
+ :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.url
+ .. attribute:: url
- 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:
-
- .. code-block:: html+django
+ 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:
+
+ .. code-block:: html+django
+
+ <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
- <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
+ .. attribute:: size
-.. attribute:: File.size
+ The size of the file in bytes.
- The size of the file in bytes.
+ .. method:: open([mode=None])
-.. method:: File.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])
-.. method:: File.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__()
-.. method:: File.__iter__()
+ Iterate over the file yielding one line at a time.
- Iterate over the file yielding one line at a time.
+ .. method:: chunks([chunk_size=None])
-.. method:: File.chunks(chunk_size=None)
+ Iterate over the file yielding "chunks" of a given size. ``chunk_size``
+ defaults to 64 KB.
- 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])
-.. method:: File.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])
-.. method:: File.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()
-.. method:: File.close()
+ Close the file.
- Close the file.
+.. currentmodule:: django.core.files.images
Additional ``ImageField`` attributes
------------------------------------
-.. attribute:: File.width
-
- Width of the image.
+.. class:: ImageFile(file_object)
+
+ .. attribute:: width
+
+ Width of the image.
-.. attribute:: File.height
+ .. attribute:: height
- Height of the image.
+ Height of the image.
+
+.. currentmodule:: django.core.files
Additional methods on files attached to objects
-----------------------------------------------
-.. highlight:: pycon
-
Any :class:`File` that's associated with an object (as with ``Car.photo``,
above) will also have a couple of extra methods:
-.. method:: File.save(name, content, save=True)
+.. 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
@@ -113,7 +119,7 @@ above) will also have a couple of extra methods:
Note that the ``content`` argument must be an instance of
:class:`File` or of a subclass of :class:`File`.
-.. method:: File.delete(save=True)
+.. method:: File.delete([save=True])
Remove the file from the model instance and delete the underlying file. The
``save`` argument works as above.
Please sign in to comment.
Something went wrong with that request. Please try again.