mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 06:06:09 +00:00
Code Issues 32 Releases Wiki Activity

Refs #36485 -- Rewrapped docs to 79 columns line length.

Browse Source 
Lines in the docs files were manually adjusted to conform to the
79 columns limit per line (plus newline), improving readability and
consistency across the content.
This commit is contained in:
David Smith
2025-07-25 10:24:17 +01:00
committed by nessita
parent 4286a23df6
commit f81e6e3a53
230 changed files with 3250 additions and 2914 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/topics/http/decorators.txt
View File

@@ -102,8 +102,8 @@ caching based on specific request headers.
.. function:: vary_on_headers(*headers)
The ``Vary`` header defines which request headers a cache mechanism should take
into account when building its cache key.
The ``Vary`` header defines which request headers a cache mechanism should
take into account when building its cache key.
See :ref:`using vary headers <using-vary-headers>`.

13
docs/topics/http/file-uploads.txt
View File

@@ -67,8 +67,9 @@ described in :ref:`binding-uploaded-files`. This would look something like:
form = UploadFileForm()
return render(request, "upload.html", {"form": form})
Notice that we have to pass :attr:`request.FILES <django.http.HttpRequest.FILES>`
into the form's constructor; this is how file data gets bound into a form.
Notice that we have to pass :attr:`request.FILES
<django.http.HttpRequest.FILES>` into the form's constructor; this is how file
data gets bound into a form.
Here's a common way you might handle an uploaded file::
@@ -259,8 +260,8 @@ involves only a read from memory and a write to disk and thus is very fast.
However, if an uploaded file is too large, Django will write the uploaded file
to a temporary file stored in your system's temporary directory. On a Unix-like
platform this means you can expect Django to generate a file called something
like ``/tmp/tmpzfp6I6.upload``. If an upload is large enough, you can watch this
file grow in size as Django streams the data onto disk.
like ``/tmp/tmpzfp6I6.upload``. If an upload is large enough, you can watch
this file grow in size as Django streams the data onto disk.
These specifics -- 2.5 megabytes; ``/tmp``; etc. -- are "reasonable defaults"
which can be customized as described in the next section.
@@ -283,8 +284,8 @@ handlers given by :setting:`FILE_UPLOAD_HANDLERS`, but you can modify the list
as you would any other list.
For instance, suppose you've written a ``ProgressBarUploadHandler`` that
provides feedback on upload progress to some sort of AJAX widget. You'd add this
handler to your upload handlers like this::
provides feedback on upload progress to some sort of AJAX widget. You'd add
this handler to your upload handlers like this::
request.upload_handlers.insert(0, ProgressBarUploadHandler(request))

26
docs/topics/http/sessions.txt
View File

@@ -131,10 +131,10 @@ and the :setting:`SECRET_KEY` setting.
When using the cookies backend the session data can be read by the client.
A MAC (Message Authentication Code) is used to protect the data against
changes by the client, so that the session data will be invalidated when being
tampered with. The same invalidation happens if the client storing the
cookie (e.g. your user's browser) can't store all of the session cookie and
drops data. Even though Django compresses the data, it's still entirely
changes by the client, so that the session data will be invalidated when
being tampered with. The same invalidation happens if the client storing
the cookie (e.g. your user's browser) can't store all of the session cookie
and drops data. Even though Django compresses the data, it's still entirely
possible to exceed the :rfc:`common limit of 4096 bytes <2965#section-5.3>`
per cookie.
@@ -578,8 +578,8 @@ calls ``save()`` and loops until an unused ``session_key`` is generated.
If you're using the ``django.contrib.sessions.backends.db`` backend, each
session is a normal Django model. The ``Session`` model is defined in
:source:`django/contrib/sessions/models.py`. Because it's a normal model, you can
access sessions using the normal Django database API:
:source:`django/contrib/sessions/models.py`. Because it's a normal model, you
can access sessions using the normal Django database API:
.. code-block:: pycon
@@ -728,11 +728,12 @@ domain. This makes session fixation possible if cookies are permitted from
subdomains not controlled by trusted users.
For example, an attacker could log into ``good.example.com`` and get a valid
session for their account. If the attacker has control over ``bad.example.com``,
they can use it to send their session key to you since a subdomain is permitted
to set cookies on ``*.example.com``. When you visit ``good.example.com``,
you'll be logged in as the attacker and might inadvertently enter your
sensitive personal data (e.g. credit card info) into the attacker's account.
session for their account. If the attacker has control over
``bad.example.com``, they can use it to send their session key to you since a
subdomain is permitted to set cookies on ``*.example.com``. When you visit
``good.example.com``, you'll be logged in as the attacker and might
inadvertently enter your sensitive personal data (e.g. credit card info) into
the attacker's account.
Another possible attack would be if ``good.example.com`` sets its
:setting:`SESSION_COOKIE_DOMAIN` to ``"example.com"`` which would cause
@@ -839,7 +840,8 @@ You can also customize the model manager by subclassing
.. method:: encode(session_dict)
Returns the given session dictionary serialized and encoded as a string.
Returns the given session dictionary serialized and encoded as a
string.
Encoding is performed by the session store class tied to a model class.

77
docs/topics/http/urls.txt
View File

@@ -34,8 +34,8 @@ How Django processes a request
When a user requests a page from your Django-powered site, this is the
algorithm the system follows to determine which Python code to execute:
#. Django determines the root URLconf module to use. Ordinarily,
this is the value of the :setting:`ROOT_URLCONF` setting, but if the incoming
#. Django determines the root URLconf module to use. Ordinarily, this is the
value of the :setting:`ROOT_URLCONF` setting, but if the incoming
``HttpRequest`` object has a :attr:`~django.http.HttpRequest.urlconf`
attribute (set by middleware), its value will be used in place of the
:setting:`ROOT_URLCONF` setting.
@@ -86,8 +86,8 @@ Notes:
* To capture a value from the URL, use angle brackets.
* Captured values can optionally include a converter type. For example, use
``<int:name>`` to capture an integer parameter. If a converter isn't included,
any string, excluding a ``/`` character, is matched.
``<int:name>`` to capture an integer parameter. If a converter isn't
included, any string, excluding a ``/`` character, is matched.
* There's no need to add a leading slash, because every URL has that. For
example, it's ``articles``, not ``/articles``.
@@ -107,8 +107,8 @@ Example requests:
* ``/articles/2003`` would not match any of these patterns, because each
pattern requires that the URL end with a slash.
* ``/articles/2003/03/building-a-django-site/`` would match the final
pattern. Django would call the function
* ``/articles/2003/03/building-a-django-site/`` would match the final pattern.
Django would call the function
``views.article_detail(request, year=2003, month=3, slug="building-a-django-site")``.
Path converters
@@ -116,8 +116,8 @@ Path converters
The following path converters are available by default:
* ``str`` - Matches any non-empty string, excluding the path separator, ``'/'``.
This is the default if a converter isn't included in the expression.
* ``str`` - Matches any non-empty string, excluding the path separator,
``'/'``. This is the default if a converter isn't included in the expression.
* ``int`` - Matches zero or any positive integer. Returns an ``int``.
@@ -139,7 +139,8 @@ The following path converters are available by default:
Registering custom path converters
==================================
For more complex matching requirements, you can define your own path converters.
For more complex matching requirements, you can define your own path
converters.
A converter is a class that includes the following:
@@ -260,9 +261,9 @@ positional arguments: ``page-2/`` and ``2``. The second pattern for
``page_number`` set to 2. The outer argument in this case is a non-capturing
argument ``(?:...)``.
The ``blog_articles`` view needs the outermost captured argument to be reversed,
``page-2/`` or no arguments in this case, while ``comments`` can be reversed
with either no arguments or a value for ``page_number``.
The ``blog_articles`` view needs the outermost captured argument to be
reversed, ``page-2/`` or no arguments in this case, while ``comments`` can be
reversed with either no arguments or a value for ``page_number``.
Nested captured arguments create a strong coupling between the view arguments
and the URL as illustrated by ``blog_articles``: the view receives part of the
@@ -283,8 +284,8 @@ does not include GET or POST parameters, or the domain name.
For example, in a request to ``https://www.example.com/myapp/``, the URLconf
will look for ``myapp/``.
In a request to ``https://www.example.com/myapp/?page=3``, the URLconf will look
for ``myapp/``.
In a request to ``https://www.example.com/myapp/?page=3``, the URLconf will
look for ``myapp/``.
The URLconf doesn't look at the request method. In other words, all request
methods -- ``POST``, ``GET``, ``HEAD``, etc. -- will be routed to the same
@@ -551,15 +552,16 @@ every view in the included URLconf accepts the extra options you're passing.
Reverse resolution of URLs
==========================
A common need when working on a Django project is the possibility to obtain URLs
in their final forms either for embedding in generated content (views and assets
URLs, URLs shown to the user, etc.) or for handling of the navigation flow on
the server side (redirections, etc.)
A common need when working on a Django project is the possibility to obtain
URLs in their final forms either for embedding in generated content (views and
assets URLs, URLs shown to the user, etc.) or for handling of the navigation
flow on the server side (redirections, etc.)
It is strongly desirable to avoid hardcoding these URLs (a laborious,
non-scalable and error-prone strategy). Equally dangerous is devising ad-hoc
mechanisms to generate URLs that are parallel to the design described by the
URLconf, which can result in the production of URLs that become stale over time.
URLconf, which can result in the production of URLs that become stale over
time.
In other words, what's needed is a DRY mechanism. Among other advantages it
would allow evolution of the URL design without having to go over all the
@@ -575,8 +577,8 @@ the URL design. You feed it with your URLconf and then it can be used in both
directions:
* Starting with a URL requested by the user/browser, it calls the right Django
view providing any arguments it might need with their values as extracted from
the URL.
view providing any arguments it might need with their values as extracted
from the URL.
* Starting with the identification of the corresponding Django view plus the
values of arguments that would be passed to it, obtain the associated URL.
@@ -643,8 +645,8 @@ change the entry in the URLconf.
In some scenarios where views are of a generic nature, a many-to-one
relationship might exist between URLs and views. For these cases the view name
isn't a good enough identifier for it when comes the time of reversing
URLs. Read the next section to know about the solution Django provides for this.
isn't a good enough identifier for it when comes the time of reversing URLs.
Read the next section to know about the solution Django provides for this.
.. _naming-url-patterns:
@@ -726,8 +728,8 @@ index page of the admin application is referenced using ``'admin:index'``. This
indicates a namespace of ``'admin'``, and a named URL of ``'index'``.
Namespaces can also be nested. The named URL ``'sports:polls:index'`` would
look for a pattern named ``'index'`` in the namespace ``'polls'`` that is itself
defined within the top-level namespace ``'sports'``.
look for a pattern named ``'index'`` in the namespace ``'polls'`` that is
itself defined within the top-level namespace ``'sports'``.
.. _topics-http-reversing-url-namespaces:
@@ -771,11 +773,11 @@ resolved into a URL in the namespace that has been found.
Example
~~~~~~~
To show this resolution strategy in action, consider an example of two instances
of the ``polls`` application from the tutorial: one called ``'author-polls'``
and one called ``'publisher-polls'``. Assume we have enhanced that application
so that it takes the instance namespace into consideration when creating and
displaying polls.
To show this resolution strategy in action, consider an example of two
instances of the ``polls`` application from the tutorial: one called
``'author-polls'`` and one called ``'publisher-polls'``. Assume we have
enhanced that application so that it takes the instance namespace into
consideration when creating and displaying polls.
.. code-block:: python
:caption: ``urls.py``
@@ -803,10 +805,10 @@ displaying polls.
Using this setup, the following lookups are possible:
* If one of the instances is current - say, if we were rendering the detail page
in the instance ``'author-polls'`` - ``'polls:index'`` will resolve to the
index page of the ``'author-polls'`` instance; i.e. both of the following will
result in ``"/author-polls/"``.
* If one of the instances is current - say, if we were rendering the detail
page in the instance ``'author-polls'`` - ``'polls:index'`` will resolve to
the index page of the ``'author-polls'`` instance; i.e. both of the following
will result in ``"/author-polls/"``.
In the method of a class-based view::
@@ -825,8 +827,8 @@ Using this setup, the following lookups are possible:
registered will be used. This would be ``'publisher-polls'`` since it's
declared last in the ``urlpatterns``.
* ``'author-polls:index'`` will always resolve to the index page of the instance
``'author-polls'`` (and likewise for ``'publisher-polls'``) .
* ``'author-polls:index'`` will always resolve to the index page of the
instance ``'author-polls'`` (and likewise for ``'publisher-polls'``).
If there were also a default instance - i.e., an instance named ``'polls'`` -
the only change from above would be in the case where there is no current
@@ -869,7 +871,8 @@ not the list of ``urlpatterns`` itself.
path("polls/", include("polls.urls")),
]
The URLs defined in ``polls.urls`` will have an application namespace ``polls``.
The URLs defined in ``polls.urls`` will have an application namespace
``polls``.
Secondly, you can include an object that contains embedded namespace data. If
you ``include()`` a list of :func:`~django.urls.path` or

31
docs/topics/http/views.txt
View File

@@ -2,15 +2,15 @@
Writing views
=============
A view function, or *view* for short, is a Python function that takes a
web request and returns a web response. This response can be the HTML contents
of a web page, or a redirect, or a 404 error, or an XML document, or an image .
. . or anything, really. The view itself contains whatever arbitrary logic is
necessary to return that response. This code can live anywhere you want, as long
as it's on your Python path. There's no other requirement--no "magic," so to
speak. For the sake of putting the code *somewhere*, the convention is to
put views in a file called ``views.py``, placed in your project or
application directory.
A view function, or *view* for short, is a Python function that takes a web
request and returns a web response. This response can be the HTML contents of a
web page, or a redirect, or a 404 error, or an XML document, or an image . . .
or anything, really. The view itself contains whatever arbitrary logic is
necessary to return that response. This code can live anywhere you want, as
long as it's on your Python path. There's no other requirement--no "magic," so
to speak. For the sake of putting the code *somewhere*, the convention is to
put views in a file called ``views.py``, placed in your project or application
directory.
A simple view
=============
@@ -55,8 +55,8 @@ Mapping URLs to views
=====================
So, to recap, this view function returns an HTML page that includes the current
date and time. To display this view at a particular URL, you'll need to create a
*URLconf*; see :doc:`/topics/http/urls` for instructions.
date and time. To display this view at a particular URL, you'll need to create
a *URLconf*; see :doc:`/topics/http/urls` for instructions.
Returning errors
================
@@ -107,10 +107,11 @@ you're responsible for defining the HTML of the resulting error page::
return HttpResponseNotFound("<h1>Page not found</h1>")
For convenience, and because it's a good idea to have a consistent 404 error page
across your site, Django provides an ``Http404`` exception. If you raise
``Http404`` at any point in a view function, Django will catch it and return the
standard error page for your application, along with an HTTP error code 404.
For convenience, and because it's a good idea to have a consistent 404 error
page across your site, Django provides an ``Http404`` exception. If you raise
``Http404`` at any point in a view function, Django will catch it and return
the standard error page for your application, along with an HTTP error code
404.
Example usage::