Code

Ticket #14855: template-respose-rest.diff

File template-respose-rest.diff, 9.2 KB (added by adamv, 3 years ago)
Line 
1diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt
2index 09bcd16..4332e6e 100644
3--- a/docs/ref/template-response.txt
4+++ b/docs/ref/template-response.txt
5@@ -7,10 +7,10 @@ TemplateResponse and SimpleTemplateResponse
6 .. module:: django.template.response
7    :synopsis: Classes dealing with lazy-rendered HTTP responses.
8 
9-Standard HttpResponse objects are static structures. They are provided
10-with a block of pre-rendered content at time of construction, and
11-while that content can be modified, it isn't in a form that makes it
12-easy to perform modifications.
13+Standard :class:`~django.http.HttpResponse` objects are static structures.
14+They are provided with a block of pre-rendered content at time of
15+construction, and while that content can be modified, it isn't in a form that
16+makes it easy to perform modifications.
17 
18 However, it can sometimes be beneficial to allow decorators or
19 middleware to modify a response *after* it has been constructed by the
20@@ -18,13 +18,13 @@ view. For example, you may want to change the template that is used,
21 or put additional data into the context.
22 
23 TemplateResponse provides a way to do just that. Unlike basic
24-HttpResponse objects, TemplateResponse objects retain the details of
25-the template and context that was provided by the view to compute the
26-response. The final output of the response is not computed until
27+:class:`~django.http.HttpResponse` objects, TemplateResponse objects retain
28+the details of the template and context that was provided by the view to
29+compute the response. The final output of the response is not computed until
30 it is needed, later in the response process.
31 
32-TemplateResponse objects
33-========================
34+SimpleTemplateResponse objects
35+==============================
36 
37 .. class:: SimpleTemplateResponse()
38 
39@@ -33,9 +33,9 @@ Attributes
40 
41 .. attribute:: SimpleTemplateResponse.template_name
42 
43-    The name of the template to be rendered. Accepts
44-    :class:`django.template.Template` object, path to template or list
45-    of paths.
46+    The name of the template to be rendered. Accepts a
47+    :class:`~django.template.Template` object, a path to a template or list
48+    of template paths.
49 
50     Example: ``['foo.html', 'path/to/bar.html']``
51 
52@@ -46,12 +46,12 @@ Attributes
53 
54     Example: ``{'foo': 123}``
55 
56-.. attr:: SimpleTemplateResponse.rendered_content:
57+.. attribute:: SimpleTemplateResponse.rendered_content
58 
59     The current rendered value of the response content, using the current
60     template and context data.
61 
62-.. attr:: SimpleTemplateResponse.is_rendered:
63+.. attribute:: SimpleTemplateResponse.is_rendered
64 
65     A boolean indicating whether the response content has been rendered.
66 
67@@ -61,29 +61,30 @@ Methods
68 
69 .. method:: SimpleTemplateResponse.__init__(template, context=None, mimetype=None, status=None, content_type=None)
70 
71-    Instantiates an
72+    Instantiates a
73     :class:`~django.template.response.SimpleTemplateResponse` object
74     with the given template, context, MIME type and HTTP status.
75 
76-    ``template`` is a full name of a template, or a sequence of
77-    template names. :class:`django.template.Template` instances can
78-    also be used.
79+    ``template``
80+        The full name of a template, or a sequence of template names.
81+        :class:`~django.template.Template` instances can also be used.
82 
83-    ``context`` is a dictionary of values to add to the template
84-    context. By default, this is an empty dictionary.
85-    :class:`~django.template.Context` objects are also accepted as
86-    ``context`` values.
87+    ``context``
88+        A dictionary of values to add to the template context. By default,
89+        this is an empty dictionary. :class:`~django.template.Context` objects
90+        are also accepted as ``context`` values.
91 
92-    ``status`` is the HTTP Status code for the response.
93+    ``status``
94+        The HTTP Status code for the response.
95 
96-    ``content_type`` is an alias for ``mimetype``. Historically, this
97-    parameter was only called ``mimetype``, but since this is actually
98-    the value included in the HTTP ``Content-Type`` header, it can
99-    also include the character set encoding, which makes it more than
100-    just a MIME type specification. If ``mimetype`` is specified (not
101-    ``None``), that value is used. Otherwise, ``content_type`` is
102-    used. If neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is
103-    used.
104+    ``content_type``
105+        An alias for ``mimetype``. Historically, this parameter was only called
106+        ``mimetype``, but since this is actually the value included in the HTTP
107+        ``Content-Type`` header, it can also include the character set encoding,
108+        which makes it more than just a MIME type specification. If ``mimetype``
109+        is specified (not ``None``), that value is used. Otherwise,
110+        ``content_type`` is used. If neither is given,
111+        :setting:`DEFAULT_CONTENT_TYPE` is used.
112 
113 
114 .. method:: SimpleTemplateResponse.resolve_context(context)
115@@ -115,45 +116,56 @@ Methods
116     the result obtained from the first call.
117 
118 
119+TemplateResponse objects
120+========================
121+
122 .. class:: TemplateResponse()
123 
124-   TemplateResponse is a subclass of :class:`SimpleTemplateResponse
125-   <django.template.response.SimpleTemplateResponse>` that uses
126-   RequestContext instead of Context.
127+   TemplateResponse is a subclass of
128+   :class:`~django.template.response.SimpleTemplateResponse` that uses
129+   a :class:`~django.template.RequestContext` instead of
130+   a :class:`~django.template.Context`.
131+
132+Methods
133+-------
134 
135 .. method:: TemplateResponse.__init__(request, template, context=None, mimetype=None, status=None, content_type=None)
136 
137-   Instantiates an ``TemplateResponse`` object with the given
138-   template, context, MIME type and HTTP status.
139+    Instantiates an ``TemplateResponse`` object with the given
140+    template, context, MIME type and HTTP status.
141 
142-   ``request`` is a HttpRequest instance.
143+    ``request``
144+        An :class:`~django.http.HttpRequest` instance.
145 
146-   ``template`` is a full name of a template to use or sequence of
147-   template names. :class:`django.template.Template` instances are
148-   also accepted.
149+    ``template``
150+        The full name of a template, or a sequence of template names.
151+        :class:`~django.template.Template` instances can also be used.
152 
153-   ``context`` is a dictionary of values to add to the template
154-   context. By default, this is an empty dictionary; context objects
155-   are also accepted as ``context`` values.
156+    ``context``
157+        A dictionary of values to add to the template context. By default,
158+        this is an empty dictionary. :class:`~django.template.Context` objects
159+        are also accepted as ``context`` values.
160 
161-   ``status`` is the HTTP Status code for the response.
162+    ``status``
163+        The HTTP Status code for the response.
164 
165-   ``content_type`` is an alias for ``mimetype``. Historically, this
166-   parameter was only called ``mimetype``, but since this is actually
167-   the value included in the HTTP ``Content-Type`` header, it can also
168-   include the character set encoding, which makes it more than just a
169-   MIME type specification. If ``mimetype`` is specified (not
170-   ``None``), that value is used. Otherwise, ``content_type`` is used.
171-   If neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is used.
172+    ``content_type``
173+        An alias for ``mimetype``. Historically, this parameter was only called
174+        ``mimetype``, but since this is actually the value included in the HTTP
175+        ``Content-Type`` header, it can also include the character set encoding,
176+        which makes it more than just a MIME type specification. If ``mimetype``
177+        is specified (not ``None``), that value is used. Otherwise,
178+        ``content_type`` is used. If neither is given,
179+        :setting:`DEFAULT_CONTENT_TYPE` is used.
180 
181 
182 The rendering process
183 =====================
184 
185-Before a :class:`TemplateResponse()` instance can be returned to the
186-client, it must be rendered. The rendering process takes the
187-intermediate representation of template and context, and turns it into
188-the final byte stream that can be served to the client.
189+Before a :class:`~django.template.response.TemplateResponse` instance can be
190+returned to the client, it must be rendered. The rendering process takes the
191+intermediate representation of template and context, and turns it into the
192+final byte stream that can be served to the client.
193 
194 There are three circumstances under which a TemplateResponse will be
195 rendered:
196@@ -168,7 +180,7 @@ rendered:
197       passing through response middleware.
198 
199 A TemplateResponse can only be rendered once. The first call to
200-:meth:`SimpleTemplateResponse.render()` sets the content of the
201+:meth:`SimpleTemplateResponse.render` sets the content of the
202 response; subsequent rendering calls do not change the response
203 content.
204 
205@@ -199,7 +211,7 @@ Using TemplateResponse and SimpleTemplateResponse
206 
207 A TemplateResponse object can be used anywhere that a normal
208 HttpResponse can be used. It can also be used as an alternative to
209-calling :method:`~django.shortcuts.render_to_response()`.
210+calling :meth:`~django.shortcuts.render_to_response()`.
211 
212 For example, the following simple view returns a
213 :class:`TemplateResponse()` with a simple template, and a context