Code

Ticket #8642: r8728.diff

File r8728.diff, 9.4 KB (added by varikin, 6 years ago)

Fixed accidental removal of a word

Line 
1Index: docs/faq/usage.txt
2===================================================================
3--- docs/faq/usage.txt  (revision 8728)
4+++ docs/faq/usage.txt  (working copy)
5@@ -45,21 +45,24 @@
6 How do I use image and file fields?
7 -----------------------------------
8 
9-Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
10+Using a :class:`~django.db.models.FileField` or an
11+:class:`~django.db.models.ImageField` in a model takes a few steps:
12 
13-    #. In your settings file, define ``MEDIA_ROOT`` as the full path to
14-       a directory where you'd like Django to store uploaded files. (For
15-       performance, these files are not stored in the database.) Define
16-       ``MEDIA_URL`` as the base public URL of that directory. Make sure that
17-       this directory is writable by the Web server's user account.
18+    #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
19+       full path to a directory where you'd like Django to store uploaded files.
20+       (For performance, these files are not stored in the database.) Define
21+       :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
22+       that this directory is writable by the Web server's user account.
23 
24-    #. Add the ``FileField`` or ``ImageField`` to your model, making sure
25-       to define the ``upload_to`` option to tell Django to which subdirectory
26-       of ``MEDIA_ROOT`` it should upload files.
27+    #. Add the :class:`~django.db.models.FileField` or
28+       :class:`~django.db.models.ImageField` to your model, making sure to
29+       define the :attr:`~django.db.models.FileField.upload_to` option to tell
30+       Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload
31+       files.
32 
33-    #. All that will be stored in your database is a path to the file
34-       (relative to ``MEDIA_ROOT``). You'll most likely want to use the
35-       convenience ``get_<fieldname>_url`` function provided by Django. For
36-       example, if your ``ImageField`` is called ``mug_shot``, you can get the
37-       absolute URL to your image in a template with
38-       ``{{ object.get_mug_shot_url }}``.
39+    #. All that will be stored in your database is a path to the file
40+       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
41+       convenience :attr:`~django.core.files.File.url` attribute provided by
42+       Django. For example, if your :class:`~django.db.models.ImageField` is
43+       called ``mug_shot``, you can get the absolute URL to your image in a
44+       template with ``{{ object.mug_shot.url }}``.
45Index: docs/ref/files/file.txt
46===================================================================
47--- docs/ref/files/file.txt     (revision 8728)
48+++ docs/ref/files/file.txt     (working copy)
49@@ -12,16 +12,18 @@
50 
51 Django's ``File`` has the following attributes and methods:
52 
53-``File.path``
54-~~~~~~~~~~~~~
55+.. attribute:: File.name
56 
57+The name of file including the relative path from :setting:`MEDIA_ROOT`.
58+
59+.. attribute:: File.path
60+
61 The absolute path to the file's location on a local filesystem.
62 
63 :ref:`Custom file storage systems <howto-custom-file-storage>` may not store
64 files locally; files stored on these systems will have a ``path`` of ``None``.
65 
66-``File.url``
67-~~~~~~~~~~~~
68+.. attribute:: File.url
69 
70 The URL where the file can be retrieved. This is often useful in :ref:`templates
71 <topics-templates>`; for example, a bit of a template for displaying a ``Car``
72@@ -29,13 +31,11 @@
73 
74     <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
75 
76-``File.size``
77-~~~~~~~~~~~~~
78+.. attribute:: File.size
79 
80 The size of the file in bytes.
81 
82-``File.open(mode=None)``
83-~~~~~~~~~~~~~~~~~~~~~~~~
84+.. method:: File.open(mode=None)
85 
86 Open or reopen the file (which by definition also does ``File.seek(0)``). The
87 ``mode`` argument allows the same values as Python's standard ``open()``.
88@@ -43,19 +43,16 @@
89 When reopening a file, ``mode`` will override whatever mode the file was
90 originally opened with; ``None`` means to reopen with the original mode.
91 
92-``File.read(num_bytes=None)``
93-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94+.. method:: File.read(num_bytes=None)
95 
96 Read content from the file. The optional ``size`` is the number of bytes to
97 read; if not specified, the file will be read to the end.
98 
99-``File.__iter__()``
100-~~~~~~~~~~~~~~~~~~~
101+.. method:: File.__iter__()
102 
103 Iterate over the file yielding one line at a time.
104 
105-``File.chunks(chunk_size=None)``
106-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107+.. method:: File.chunks(chunk_size=None)
108 
109 Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults
110 to 64 KB.
111@@ -63,40 +60,36 @@
112 This is especially useful with very large files since it allows them to be
113 streamed off disk and avoids storing the whole file in memory.
114 
115-``File.multiple_chunks(chunk_size=None)``
116-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117+.. method:: File.multiple_chunks(chunk_size=None)
118 
119 Returns ``True`` if the file is large enough to require multiple chunks to
120 access all of its content give some ``chunk_size``.
121 
122-``File.write(content)``
123-~~~~~~~~~~~~~~~~~~~~~~~
124+.. method:: File.write(content)
125 
126 Writes the specified content string to the file. Depending on the storage system
127 behind the scenes, this content might not be fully committed until ``close()``
128 is called on the file.
129 
130-``File.close()``
131-~~~~~~~~~~~~~~~~
132+.. method:: File.close()
133 
134 Close the file.
135 
136 Additional ``ImageField`` attributes
137 ------------------------------------
138 
139-``File.width`` and ``File.height``
140-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141+.. attribute:: File.width
142+.. attribute:: File.height
143 
144 These attributes provide the dimensions of the image.
145 
146 Additional methods on files attached to objects
147 -----------------------------------------------
148 
149-Any ``File`` that's associated with an object (as with ``Car.photo``, above)
150+Any :class:`File` that's associated with an object (as with ``Car.photo``, above)
151 will also have a couple of extra methods:
152 
153-``File.save(name, content, save=True)``
154-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155+.. method:: File.save(name, content, save=True)
156 
157 Saves a new file with the file name and contents provided. This will not replace
158 the existing file, but will create a new file and update the object to point to
159@@ -110,8 +103,7 @@
160 
161     >>> car.photo.save('myphoto.jpg', contents, save=True)
162 
163-``File.delete(save=True)``
164-~~~~~~~~~~~~~~~~~~~~~~~~~~
165+.. method:: File.delete(save=True)
166 
167 Remove the file from the model instance and delete the underlying file. The
168 ``save`` argument works as above.
169Index: docs/ref/models/fields.txt
170===================================================================
171--- docs/ref/models/fields.txt  (revision 8728)
172+++ docs/ref/models/fields.txt  (working copy)
173@@ -415,8 +415,8 @@
174 .. attribute:: FileField.upload_to
175     
176     A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
177-    setting to determine the output of the ``get_<fieldname>_url()`` helper
178-    function.
179+    setting to determine the value of the :attr:`~django.core.files.File.url`
180+    attribute.
181 
182     This path may contain `strftime formatting`_, which will be replaced by the
183     date/time of the file upload (so that uploaded files don't fill up the given
184@@ -470,15 +470,15 @@
185        that this directory is writable by the Web server's user account.
186 
187     2. Add the :class:`FileField` or :class:`ImageField` to your model, making
188-       sure to define the :attr:`~FileField.upload_to` option to tell Django to
189-       which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
190+       sure to define the :attr:`~FileField.upload_to` option to tell Django
191+       to which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
192 
193     3. All that will be stored in your database is a path to the file
194        (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
195-       convenience ``get_<fieldname>_url`` function provided by Django. For
196-       example, if your :class:`ImageField` is called ``mug_shot``, you can get
197-       the absolute URL to your image in a template with ``{{
198-       object.get_mug_shot_url }}``.
199+       convenience :attr:`~django.core.files.File.url` function provided by
200+       Django. For example, if your :class:`ImageField` is called ``mug_shot``,
201+       you can get the absolute URL to your image in a template with
202+       ``{{ object.mug_shot.url }}``.
203 
204 For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
205 :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
206@@ -488,8 +488,9 @@
207 ``/home/media/photos/2007/01/15``.
208 
209 If you want to retrieve the upload file's on-disk filename, or a URL that refers
210-to that file, or the file's size, you can use the ``File.name``, ``File.url``
211-and ``File.size`` attributes; see :ref:`topics-files`.
212+to that file, or the file's size, you can use the
213+:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url`
214+and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`.
215 
216 Note that whenever you deal with uploaded files, you should pay close attention
217 to where you're uploading them and what type of files they are, to avoid
218@@ -575,7 +576,7 @@
219     Name of a model field which will be auto-populated with the height of the
220     image each time the model instance is saved.
221 
222-.. attribute:: ImageField.width_field`
223+.. attribute:: ImageField.width_field
224 
225     Name of a model field which will be auto-populated with the width of the
226     image each time the model instance is saved.