Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14339 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 5d02b86afb8c649f54dd01dcc3d10a6d20023fdd 1 parent e4c0c37
authored October 24, 2010

Showing 1 changed file with 59 additions and 53 deletions. Show diff stats Hide diff stats

  1. 112  docs/ref/files/file.txt
112  docs/ref/files/file.txt
@@ -3,100 +3,106 @@ The ``File`` object
3 3
 
4 4
 .. currentmodule:: django.core.files
5 5
 
6  
-.. class:: File(file_object)
7  
-
8 6
 ``File`` attributes and methods
9 7
 -------------------------------
10 8
 
11  
-Django's ``File`` has the following attributes and methods:
  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:
  12
+
  13
+.. class:: File(file_object)
12 14
 
13  
-.. attribute:: File.name
  15
+    .. attribute:: name
14 16
 
15  
-    The name of file including the relative path from :setting:`MEDIA_ROOT`.
  17
+        The name of file including the relative path from :setting:`MEDIA_ROOT`.
16 18
 
17  
-.. attribute:: File.path
  19
+    .. attribute:: path
18 20
 
19  
-    The absolute path to the file's location on a local filesystem.
  21
+        The absolute path to the file's location on a local filesystem.
20 22
 
21  
-    :doc:`Custom file storage systems </howto/custom-file-storage>` may not store
22  
-    files locally; files stored on these systems will have a ``path`` of
23  
-    ``None``.
  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``.
24 26
 
25  
-.. attribute:: File.url
  27
+    .. attribute:: url
26 28
 
27  
-    The URL where the file can be retrieved. This is often useful in
28  
-    :doc:`templates </topics/templates>`; for example, a bit of a template for
29  
-    displaying a ``Car`` (see above) might look like:
30  
-    
31  
-    .. code-block:: html+django
  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:
  32
+        
  33
+        .. code-block:: html+django
  34
+
  35
+            <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
32 36
 
33  
-        <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
  37
+    .. attribute:: size
34 38
 
35  
-.. attribute:: File.size
  39
+        The size of the file in bytes.
36 40
 
37  
-    The size of the file in bytes.
  41
+    .. method:: open([mode=None])
38 42
 
39  
-.. method:: File.open(mode=None)
  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 46
 
41  
-    Open or reopen the file (which by definition also does ``File.seek(0)``).
42  
-    The ``mode`` argument allows the same values as Python's standard
43  
-    ``open()``.
  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 49
 
45  
-    When reopening a file, ``mode`` will override whatever mode the file was
46  
-    originally opened with; ``None`` means to reopen with the original mode.
  50
+    .. method:: read([num_bytes=None])
47 51
 
48  
-.. method:: File.read(num_bytes=None)
  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.
49 54
 
50  
-    Read content from the file. The optional ``size`` is the number of bytes to
51  
-    read; if not specified, the file will be read to the end.
  55
+    .. method:: __iter__()
52 56
 
53  
-.. method:: File.__iter__()
  57
+        Iterate over the file yielding one line at a time.
54 58
 
55  
-    Iterate over the file yielding one line at a time.
  59
+    .. method:: chunks([chunk_size=None])
56 60
 
57  
-.. method:: File.chunks(chunk_size=None)
  61
+        Iterate over the file yielding "chunks" of a given size. ``chunk_size``
  62
+        defaults to 64 KB.
58 63
 
59  
-    Iterate over the file yielding "chunks" of a given size. ``chunk_size``
60  
-    defaults to 64 KB.
  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.
61 66
 
62  
-    This is especially useful with very large files since it allows them to be
63  
-    streamed off disk and avoids storing the whole file in memory.
  67
+    .. method:: multiple_chunks([chunk_size=None])
64 68
 
65  
-.. method:: File.multiple_chunks(chunk_size=None)
  69
+        Returns ``True`` if the file is large enough to require multiple chunks to
  70
+        access all of its content give some ``chunk_size``.
66 71
 
67  
-    Returns ``True`` if the file is large enough to require multiple chunks to
68  
-    access all of its content give some ``chunk_size``.
  72
+    .. method:: write([content])
69 73
 
70  
-.. method:: File.write(content)
  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.
71 77
 
72  
-    Writes the specified content string to the file. Depending on the storage
73  
-    system behind the scenes, this content might not be fully committed until
74  
-    ``close()`` is called on the file.
  78
+    .. method:: close()
75 79
 
76  
-.. method:: File.close()
  80
+        Close the file.
77 81
 
78  
-    Close the file.
  82
+.. currentmodule:: django.core.files.images
79 83
 
80 84
 Additional ``ImageField`` attributes
81 85
 ------------------------------------
82 86
 
83  
-.. attribute:: File.width
84  
-    
85  
-    Width of the image.
  87
+.. class:: ImageFile(file_object)
  88
+
  89
+    .. attribute:: width
  90
+        
  91
+        Width of the image.
86 92
 
87  
-.. attribute:: File.height
  93
+    .. attribute:: height
88 94
 
89  
-    Height of the image.
  95
+        Height of the image.
  96
+
  97
+.. currentmodule:: django.core.files
90 98
 
91 99
 Additional methods on files attached to objects
92 100
 -----------------------------------------------
93 101
 
94  
-.. highlight:: pycon
95  
-
96 102
 Any :class:`File` that's associated with an object (as with ``Car.photo``,
97 103
 above) will also have a couple of extra methods:
98 104
 
99  
-.. method:: File.save(name, content, save=True)
  105
+.. method:: File.save(name, content, [save=True])
100 106
 
101 107
     Saves a new file with the file name and contents provided. This will not
102 108
     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:
113 119
     Note that the ``content`` argument must be an instance of
114 120
     :class:`File` or of a subclass of :class:`File`.
115 121
 
116  
-.. method:: File.delete(save=True)
  122
+.. method:: File.delete([save=True])
117 123
 
118 124
     Remove the file from the model instance and delete the underlying file. The
119 125
     ``save`` argument works as above.

0 notes on commit 5d02b86

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