1
0
mirror of https://github.com/django/django.git synced 2025-10-23 21:59:11 +00:00

Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty.

This patch does not remove all occurrences of the words in question.
Rather, I went through all of the occurrences of the words listed
below, and judged if they a) suggested the reader had some kind of
knowledge/experience, and b) if they added anything of value (including
tone of voice, etc). I left most of the words alone. I looked at the
following words:

- simply/simple
- easy/easier/easiest
- obvious
- just
- merely
- straightforward
- ridiculous

Thanks to Carlton Gibson for guidance on how to approach this issue, and
to Tim Bell for providing the idea. But the enormous lion's share of
thanks go to Adam Johnson for his patient and helpful review.
This commit is contained in:
Tobias Kunze
2019-06-17 16:54:55 +02:00
committed by Mariusz Felisiak
parent addabc492b
commit 4a954cfd11
149 changed files with 1101 additions and 1157 deletions

View File

@@ -19,7 +19,7 @@ and in memory, and how to customize the default behavior.
Basic file uploads
==================
Consider a simple form containing a :class:`~django.forms.FileField`:
Consider a form containing a :class:`~django.forms.FileField`:
.. code-block:: python
:caption: forms.py
@@ -42,9 +42,8 @@ contain data if the request method was ``POST`` and the ``<form>`` that posted
the request has the attribute ``enctype="multipart/form-data"``. Otherwise,
``request.FILES`` will be empty.
Most of the time, you'll simply pass the file data from ``request`` into the
form as described in :ref:`binding-uploaded-files`. This would look
something like:
Most of the time, you'll pass the file data from ``request`` into the form as
described in :ref:`binding-uploaded-files`. This would look something like:
.. code-block:: python
:caption: views.py
@@ -107,9 +106,9 @@ corresponding :class:`~django.db.models.FileField` when calling
form = ModelFormWithFileField()
return render(request, 'upload.html', {'form': form})
If you are constructing an object manually, you can simply assign the file
object from :attr:`request.FILES <django.http.HttpRequest.FILES>` to the file
field in the model::
If you are constructing an object manually, you can assign the file object from
:attr:`request.FILES <django.http.HttpRequest.FILES>` to the file field in the
model::
from django.http import HttpResponseRedirect
from django.shortcuts import render
@@ -205,8 +204,8 @@ 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.
These specifics -- 2.5 megabytes; ``/tmp``; etc. -- are simply "reasonable
defaults" which can be customized as described in the next section.
These specifics -- 2.5 megabytes; ``/tmp``; etc. -- are "reasonable defaults"
which can be customized as described in the next section.
Changing upload handler behavior
--------------------------------
@@ -235,7 +234,7 @@ You'd probably want to use ``list.insert()`` in this case (instead of
``append()``) because a progress bar handler would need to run *before* any
other handlers. Remember, the upload handlers are processed in order.
If you want to replace the upload handlers completely, you can just assign a new
If you want to replace the upload handlers completely, you can assign a new
list::
request.upload_handlers = [ProgressBarUploadHandler(request)]

View File

@@ -379,7 +379,7 @@ convenience and security. If you wish to store more advanced data types
including ``datetime`` and ``Decimal`` in JSON backed sessions, you will need
to write a custom serializer (or convert such values to a JSON serializable
object before storing them in ``request.session``). While serializing these
values is fairly straightforward
values is often straightforward
(:class:`~django.core.serializers.json.DjangoJSONEncoder` may be helpful),
writing a decoder that can reliably get back the same thing that you put in is
more fragile. For example, you run the risk of returning a ``datetime`` that
@@ -444,10 +444,9 @@ objects, not as a full ``logout()`` implementation.
Setting test cookies
====================
As a convenience, Django provides an easy way to test whether the user's
browser accepts cookies. Just call the
:meth:`~backends.base.SessionBase.set_test_cookie` method of
``request.session`` in a view, and call
As a convenience, Django provides a way to test whether the user's browser
accepts cookies. Call the :meth:`~backends.base.SessionBase.set_test_cookie`
method of ``request.session`` in a view, and call
:meth:`~backends.base.SessionBase.test_cookie_worked` in a subsequent view --
not in the same view call.
@@ -509,7 +508,7 @@ generating a ``session_key`` that collides with an existing one. ``create()``
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 just a normal Django model. The ``Session`` model is defined in
session is a normal Django model. The ``Session`` model is defined in
``django/contrib/sessions/models.py``. Because it's a normal model, you can
access sessions using the normal Django database API::
@@ -701,9 +700,9 @@ In order to build a custom session engine or to customize an existing one, you
may create a new class inheriting from :class:`~backends.base.SessionBase` or
any other existing ``SessionStore`` class.
Extending most of the session engines is quite straightforward, but doing so
with database-backed session engines generally requires some extra effort (see
the next section for details).
You can extend the session engines, but doing so with database-backed session
engines generally requires some extra effort (see the next section for
details).
.. _extending-database-backed-session-engines:

View File

@@ -48,7 +48,7 @@ algorithm the system follows to determine which Python code to execute:
one that matches the requested URL.
#. Once one of the URL patterns matches, Django imports and calls the given
view, which is a simple Python function (or a :doc:`class-based view
view, which is a Python function (or a :doc:`class-based view
</topics/class-based-views/index>`). The view gets passed the following
arguments:
@@ -131,7 +131,7 @@ The following path converters are available by default:
* ``path`` - Matches any non-empty string, including the path separator,
``'/'``. This allows you to match against a complete URL path rather than
just a segment of a URL path as with ``str``.
a segment of a URL path as with ``str``.
.. _registering-custom-path-converters:
@@ -679,13 +679,13 @@ instances of an application are deployed. In other words, since multiple
instances of a single application will share named URLs, namespaces provide a
way to tell these named URLs apart.
Django applications that make proper use of URL namespacing can be deployed more
than once for a particular site. For example :mod:`django.contrib.admin` has an
:class:`~django.contrib.admin.AdminSite` class which allows you to easily
:ref:`deploy more than one instance of the admin <multiple-admin-sites>`.
In a later example, we'll discuss the idea of deploying the polls application
from the tutorial in two different locations so we can serve the same
functionality to two different audiences (authors and publishers).
Django applications that make proper use of URL namespacing can be deployed
more than once for a particular site. For example :mod:`django.contrib.admin`
has an :class:`~django.contrib.admin.AdminSite` class which allows you to
:ref:`deploy more than one instance of the admin <multiple-admin-sites>`. In a
later example, we'll discuss the idea of deploying the polls application from
the tutorial in two different locations so we can serve the same functionality
to two different audiences (authors and publishers).
A URL namespace comes in two parts, both of which are strings:

View File

@@ -2,7 +2,7 @@
Writing views
=============
A view function, or *view* for short, is simply a Python function that takes a
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
@@ -60,12 +60,12 @@ date and time. To display this view at a particular URL, you'll need to create a
Returning errors
================
Returning HTTP error codes in Django is easy. There are subclasses of
Django provides help for returning HTTP error codes. There are subclasses of
:class:`~django.http.HttpResponse` for a number of common HTTP status codes
other than 200 (which means *"OK"*). You can find the full list of available
subclasses in the :ref:`request/response <ref-httpresponse-subclasses>`
documentation. Just return an instance of one of those subclasses instead of
a normal :class:`~django.http.HttpResponse` in order to signify an error. For
documentation. Return an instance of one of those subclasses instead of a
normal :class:`~django.http.HttpResponse` in order to signify an error. For
example::
from django.http import HttpResponse, HttpResponseNotFound
@@ -138,9 +138,9 @@ Customizing error views
=======================
The default error views in Django should suffice for most Web applications,
but can easily be overridden if you need any custom behavior. Simply specify
the handlers as seen below in your URLconf (setting them anywhere else will
have no effect).
but can easily be overridden if you need any custom behavior. Specify the
handlers as seen below in your URLconf (setting them anywhere else will have no
effect).
The :func:`~django.views.defaults.page_not_found` view is overridden by
:data:`~django.conf.urls.handler404`::