Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit 2dd594dff4f68f36b345f454738c35f01e5dd48e 1 parent 0ab50aa
authored December 05, 2010
132  docs/ref/files/file.txt
... ...
@@ -1,56 +1,54 @@
1 1
 The ``File`` object
2 2
 ===================
3 3
 
4  
-.. currentmodule:: django.core.files
  4
+The :mod:`django.core.files` module and its submodules contain built-in classes
  5
+for basic file handling in Django.
5 6
 
6  
-``File`` attributes and methods
7  
--------------------------------
  7
+.. currentmodule:: django.core.files
8 8
 
9  
-The :mod:`django.core.files` module contains a built-in class for basic file
10  
-handling in Django. The :class:`File` class has the following attributes and
11  
-methods:
  9
+The ``File`` Class
  10
+------------------
12 11
 
13 12
 .. class:: File(file_object)
14 13
 
15  
-    .. attribute:: name
16  
-
17  
-        The name of file including the relative path from :setting:`MEDIA_ROOT`.
  14
+    The :class:`File` is a thin wrapper around Python's built-in file object
  15
+    with some Django-specific additions. Internally, Django uses this class
  16
+    any time it needs to represent a file.
  17
+    
  18
+    :class:`File` objects have the following attributes and methods:
18 19
 
19  
-    .. attribute:: path
20  
-
21  
-        The absolute path to the file's location on a local filesystem.
  20
+    .. attribute:: name
22 21
 
23  
-        :doc:`Custom file storage systems </howto/custom-file-storage>` may not store
24  
-        files locally; files stored on these systems will have a ``path`` of
25  
-        ``None``.
  22
+        The name of file including the relative path from
  23
+        :setting:`MEDIA_ROOT`.
26 24
 
27  
-    .. attribute:: url
  25
+    .. attribute:: size
28 26
 
29  
-        The URL where the file can be retrieved. This is often useful in
30  
-        :doc:`templates </topics/templates>`; for example, a bit of a template for
31  
-        displaying a ``Car`` (see above) might look like:
  27
+        The size of the file in bytes.
32 28
 
33  
-        .. code-block:: html+django
  29
+    .. attribute:: file
34 30
 
35  
-            <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
  31
+        The underlying Python ``file`` object passed to
  32
+        :class:`~django.core.files.File`.
36 33
 
37  
-    .. attribute:: size
  34
+    .. attribute:: mode
38 35
 
39  
-        The size of the file in bytes.
  36
+        The read/write mode for the file.
40 37
 
41 38
     .. method:: open([mode=None])
42 39
 
43  
-        Open or reopen the file (which by definition also does ``File.seek(0)``).
44  
-        The ``mode`` argument allows the same values as Python's standard
45  
-        ``open()``.
  40
+        Open or reopen the file (which by definition also does
  41
+        ``File.seek(0)``). The ``mode`` argument allows the same values
  42
+        as Python's standard ``open()``.
46 43
 
47  
-        When reopening a file, ``mode`` will override whatever mode the file was
48  
-        originally opened with; ``None`` means to reopen with the original mode.
  44
+        When reopening a file, ``mode`` will override whatever mode the file
  45
+        was originally opened with; ``None`` means to reopen with the original
  46
+        mode.
49 47
 
50 48
     .. method:: read([num_bytes=None])
51 49
 
52  
-        Read content from the file. The optional ``size`` is the number of bytes to
53  
-        read; if not specified, the file will be read to the end.
  50
+        Read content from the file. The optional ``size`` is the number of
  51
+        bytes to read; if not specified, the file will be read to the end.
54 52
 
55 53
     .. method:: __iter__()
56 54
 
@@ -61,38 +59,65 @@ methods:
61 59
         Iterate over the file yielding "chunks" of a given size. ``chunk_size``
62 60
         defaults to 64 KB.
63 61
 
64  
-        This is especially useful with very large files since it allows them to be
65  
-        streamed off disk and avoids storing the whole file in memory.
  62
+        This is especially useful with very large files since it allows them to
  63
+        be streamed off disk and avoids storing the whole file in memory.
66 64
 
67 65
     .. method:: multiple_chunks([chunk_size=None])
68 66
 
69  
-        Returns ``True`` if the file is large enough to require multiple chunks to
70  
-        access all of its content give some ``chunk_size``.
  67
+        Returns ``True`` if the file is large enough to require multiple chunks
  68
+        to access all of its content give some ``chunk_size``.
71 69
 
72 70
     .. method:: write([content])
73 71
 
74  
-        Writes the specified content string to the file. Depending on the storage
75  
-        system behind the scenes, this content might not be fully committed until
76  
-        ``close()`` is called on the file.
  72
+        Writes the specified content string to the file. Depending on the
  73
+        storage system behind the scenes, this content might not be fully
  74
+        committed until ``close()`` is called on the file.
77 75
 
78 76
     .. method:: close()
79 77
 
80 78
         Close the file.
81 79
 
  80
+    In addition to the listed methods, :class:`~django.core.files.File` exposes
  81
+    the following attributes and methods of the underlying ``file`` object:
  82
+    ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``,
  83
+    ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``,
  84
+    ``truncate``, ``writelines``, ``xreadlines``.
  85
+
  86
+.. currentmodule:: django.core.files.base
  87
+
  88
+The ``ContentFile`` Class
  89
+-------------------------
  90
+
  91
+.. class:: ContentFile(File)
  92
+
  93
+    The ``ContentFile`` class inherits from :class:`~django.core.files.File`,
  94
+    but unlike :class:`~django.core.files.File` it operates on string content,
  95
+    rather than an actual file. For example::
  96
+
  97
+        from django.core.files.base import ContentFile
  98
+
  99
+        f1 = ContentFile("my string content")
  100
+        f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
  101
+
82 102
 .. currentmodule:: django.core.files.images
83 103
 
84  
-Additional ``ImageFile`` attributes
85  
-------------------------------------
  104
+The ``ImageFile`` Class
  105
+-----------------------
86 106
 
87 107
 .. class:: ImageFile(file_object)
88 108
 
  109
+    Django provides a built-in class specifically for images.
  110
+    :class:`django.core.files.images.ImageFile` inherits all the attributes
  111
+    and methods of :class:`~django.core.files.File`, and additionally
  112
+    provides the following:
  113
+
89 114
     .. attribute:: width
90 115
 
91  
-        Width of the image.
  116
+        Width of the image in pixels.
92 117
 
93 118
     .. attribute:: height
94 119
 
95  
-        Height of the image.
  120
+        Height of the image in pixels.
96 121
 
97 122
 .. currentmodule:: django.core.files
98 123
 
@@ -100,7 +125,7 @@ Additional methods on files attached to objects
100 125
 -----------------------------------------------
101 126
 
102 127
 Any :class:`File` that's associated with an object (as with ``Car.photo``,
103  
-above) will also have a couple of extra methods:
  128
+below) will also have a couple of extra methods:
104 129
 
105 130
 .. method:: File.save(name, content, [save=True])
106 131
 
@@ -116,23 +141,12 @@ above) will also have a couple of extra methods:
116 141
 
117 142
         >>> car.photo.save('myphoto.jpg', contents, save=True)
118 143
 
119  
-    Note that the ``content`` argument must be an instance of
120  
-    :class:`File` or of a subclass of :class:`File` such as :class:`ContentFile`.
  144
+    Note that the ``content`` argument must be an instance of either
  145
+    :class:`File` or of a subclass of :class:`File`, such as
  146
+    :class:`ContentFile`.
121 147
 
122 148
 .. method:: File.delete([save=True])
123 149
 
124  
-    Remove the file from the model instance and delete the underlying file. The
125  
-    ``save`` argument works as above.
126  
-
127  
-``ContentFile`` objects
128  
------------------------
129  
-
130  
-.. class:: ContentFile(File)
131  
-
132  
-A ``ContentFile`` is a File-like object that takes string content, rather
133  
-than an actual file::
134  
-
135  
-    from django.core.files.base import ContentFile
136  
-
137  
-    f1 = ContentFile("my string content")
138  
-    f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
  150
+    Removes the file from the model instance and deletes the underlying file.
  151
+    If ``save`` is ``True``, the model's ``save()`` method will be called once
  152
+    the file is deleted.
2  docs/ref/files/index.txt
@@ -6,7 +6,7 @@ File handling
6 6
    :synopsis: File handling and storage
7 7
 
8 8
 .. toctree::
9  
-   :maxdepth: 1
  9
+   :maxdepth: 2
10 10
 
11 11
    file
12 12
    storage
10  docs/topics/files.txt
@@ -50,9 +50,9 @@ it has all the methods and attributes described below.
50 50
 The ``File`` object
51 51
 ===================
52 52
 
53  
-Internally, Django uses a ``django.core.files.File`` any time it needs to
54  
-represent a file. This object is a thin wrapper around Python's `built-in file
55  
-object`_ with some Django-specific additions.
  53
+Internally, Django uses a :class:`django.core.files.File` instance any time it
  54
+needs to represent a file. This object is a thin wrapper around Python's
  55
+`built-in file object`_ with some Django-specific additions.
56 56
 
57 57
 .. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
58 58
 
@@ -68,8 +68,8 @@ using a Python built-in ``file`` object::
68 68
     >>> f = open('/tmp/hello.world', 'w')
69 69
     >>> myfile = File(f)
70 70
 
71  
-Now you can use any of the ``File`` attributes and methods documented in
72  
-:doc:`/ref/files/file`.
  71
+Now you can use any of the documented attributes and methods
  72
+of the :class:`~django.core.files.File` class.
73 73
 
74 74
 File storage
75 75
 ============

0 notes on commit 2dd594d

Please sign in to comment.
Something went wrong with that request. Please try again.