diff options
| author | Tobias Kunze <r@rixx.de> | 2019-06-17 16:54:55 +0200 |
|---|---|---|
| committer | Mariusz Felisiak <felisiak.mariusz@gmail.com> | 2019-09-06 13:27:46 +0200 |
| commit | 4a954cfd11a5d034491f87fcbc920eb97a302bb3 (patch) | |
| tree | 1c92caae5d8a9b33c51ddd74b4b2061248f3915f | |
| parent | addabc492bdc0191ac95d59ec34b56b34086ebb9 (diff) | |
| download | django-4a954cfd11a5d034491f87fcbc920eb97a302bb3.tar.gz | |
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.
149 files changed, 1101 insertions, 1157 deletions
diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt index f1c6f61eba..1e96def9a9 100644 --- a/docs/faq/admin.txt +++ b/docs/faq/admin.txt @@ -78,9 +78,9 @@ modules to the page via the model's class Admin :ref:`js parameter pointing to JavaScript modules that will be included within the admin form via a ``<script>`` tag. -If you want more flexibility than simply tweaking the auto-generated forms, -feel free to write custom views for the admin. The admin is powered by Django -itself, and you can write custom views that hook into the authentication +If you want more flexibility than is feasible by tweaking the auto-generated +forms, feel free to write custom views for the admin. The admin is powered by +Django itself, and you can write custom views that hook into the authentication system, check permissions and do whatever else they need to do. If you want to customize the look-and-feel of the admin interface, read the diff --git a/docs/faq/contributing.txt b/docs/faq/contributing.txt index 17e730d96f..8d8eb2ded7 100644 --- a/docs/faq/contributing.txt +++ b/docs/faq/contributing.txt @@ -84,7 +84,7 @@ of a larger problem. While we can spend time writing, testing and applying lots of little patches, sometimes the right solution is to rebuild. If a rebuild or refactor of a particular component has been proposed or is underway, you may find that bugs affecting that component will not get as much -attention. Again, this is just a matter of prioritizing scarce resources. By +attention. Again, this is a matter of prioritizing scarce resources. By concentrating on the rebuild, we can close all the little bugs at once, and hopefully prevent other little bugs from appearing in the future. @@ -93,7 +93,7 @@ bug regularly, it doesn't necessarily follow that every single Django user will hit the same bug. Different users use Django in different ways, stressing different parts of the code under different conditions. When we evaluate the relative priorities, we are generally trying to consider the needs of the -entire community, not just the severity for one particular user. This doesn't -mean that we think your problem is unimportant -- just that in the limited -time we have available, we will always err on the side of making 10 people -happy rather than making 1 person happy. +entire community, instead of prioritizing the impact on one particular user. +This doesn't mean that we think your problem is unimportant -- just that in the +limited time we have available, we will always err on the side of making 10 +people happy rather than making a single person happy. diff --git a/docs/faq/models.txt b/docs/faq/models.txt index c6a7f28e23..89bbbd1724 100644 --- a/docs/faq/models.txt +++ b/docs/faq/models.txt @@ -8,7 +8,7 @@ How can I see the raw SQL queries Django is running? ==================================================== Make sure your Django :setting:`DEBUG` setting is set to ``True``. -Then, just do this:: +Then do this:: >>> from django.db import connection >>> connection.queries @@ -32,7 +32,7 @@ same interface on each member of the ``connections`` dictionary:: >>> connections['my_db_alias'].queries If you need to clear the query list manually at any point in your functions, -just call ``reset_queries()``, like this:: +call ``reset_queries()``, like this:: from django.db import reset_queries reset_queries() @@ -61,8 +61,8 @@ But this isn't an issue in practice, because there's nothing stopping you from adding other constraints (using the ``unique_together`` model option or creating the constraint directly in your database), and enforcing the uniqueness at that level. Single-column primary keys are needed for things such -as the admin interface to work; e.g., you need a simple way of being able to -specify an object to edit or delete. +as the admin interface to work; e.g., you need a single value to specify +an object to edit or delete. Does Django support NoSQL databases? ==================================== diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt index 9c659bd711..60261508df 100644 --- a/docs/faq/usage.txt +++ b/docs/faq/usage.txt @@ -61,9 +61,9 @@ Using a :class:`~django.db.models.FileField` or an How do I make a variable available to all my templates? ======================================================= -Sometimes your templates just all need the same thing. A common example would -be dynamically-generated menus. At first glance, it seems logical to simply -add a common dictionary to the template context. +Sometimes your templates all need the same thing. A common example would be +dynamically generated menus. At first glance, it seems logical to add a common +dictionary to the template context. -The correct solution is to use a ``RequestContext``. Details on how to do this -are here: :ref:`subclassing-context-requestcontext`. +The best way to do this in Django is to use a ``RequestContext``. Details on +how to do this are here: :ref:`subclassing-context-requestcontext`. diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt index fc16647098..742c0d223b 100644 --- a/docs/howto/auth-remote-user.txt +++ b/docs/howto/auth-remote-user.txt @@ -111,8 +111,8 @@ Using ``REMOTE_USER`` on login pages only The ``RemoteUserMiddleware`` authentication middleware assumes that the HTTP request header ``REMOTE_USER`` is present with all authenticated requests. That -might be expected and practical when Basic HTTP Auth with ``htpasswd`` or other -simple mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other +might be expected and practical when Basic HTTP Auth with ``htpasswd`` or +similar mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other resource intensive authentication methods, the authentication in the front-end HTTP server is usually only set up for one or a few login URLs, and after successful authentication, the application is supposed to maintain the diff --git a/docs/howto/custom-lookups.txt b/docs/howto/custom-lookups.txt index efa9685522..82ccb9a69d 100644 --- a/docs/howto/custom-lookups.txt +++ b/docs/howto/custom-lookups.txt @@ -9,10 +9,10 @@ filtering (for example, ``exact`` and ``icontains``). This documentation explains how to write custom lookups and how to alter the working of existing lookups. For the API references of lookups, see the :doc:`/ref/models/lookups`. -A simple lookup example -======================= +A lookup example +================ -Let's start with a simple custom lookup. We will write a custom lookup ``ne`` +Let's start with a small custom lookup. We will write a custom lookup ``ne`` which works opposite to ``exact``. ``Author.objects.filter(name__ne='Jack')`` will translate to the SQL: @@ -24,8 +24,7 @@ This SQL is backend independent, so we don't need to worry about different databases. There are two steps to making this work. Firstly we need to implement the -lookup, then we need to tell Django about it. The implementation is quite -straightforward:: +lookup, then we need to tell Django about it:: from django.db.models import Lookup @@ -38,10 +37,10 @@ straightforward:: params = lhs_params + rhs_params return '%s <> %s' % (lhs, rhs), params -To register the ``NotEqual`` lookup we will just need to call -``register_lookup`` on the field class we want the lookup to be available. In -this case, the lookup makes sense on all ``Field`` subclasses, so we register -it with ``Field`` directly:: +To register the ``NotEqual`` lookup we will need to call ``register_lookup`` on +the field class we want the lookup to be available for. In this case, the lookup +makes sense on all ``Field`` subclasses, so we register it with ``Field`` +directly:: from django.db.models.fields import Field Field.register_lookup(NotEqual) @@ -94,8 +93,8 @@ Finally we combine the parts into an SQL expression with ``<>``, and supply all the parameters for the query. We then return a tuple containing the generated SQL string and the parameters. -A simple transformer example -============================ +A transformer example +===================== The custom lookup above is great, but in some cases you may want to be able to chain lookups together. For example, let's suppose we are building an @@ -241,10 +240,10 @@ want the transformation to be applied to both the left-hand side and the right-hand side. For instance, if you want to filter a queryset based on the equality of the left and right-hand side insensitively to some SQL function. -Let's examine the simple example of case-insensitive transformation here. This -transformation isn't very useful in practice as Django already comes with a bunch -of built-in case-insensitive lookups, but it will be a nice demonstration of -bilateral transformations in a database-agnostic way. +Let's examine case-insensitive transformations here. This transformation isn't +very useful in practice as Django already comes with a bunch of built-in +case-insensitive lookups, but it will be a nice demonstration of bilateral +transformations in a database-agnostic way. We define an ``UpperCase`` transformer which uses the SQL function ``UPPER()`` to transform the values before comparison. We define diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index 178f54f33b..f76896b790 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -10,9 +10,9 @@ distributing. In this document, we will be building a custom ``closepoll`` command for the ``polls`` application from the :doc:`tutorial</intro/tutorial01>`. -To do this, just add a ``management/commands`` directory to the application. -Django will register a ``manage.py`` command for each Python module in that -directory whose name doesn't begin with an underscore. For example:: +To do this, add a ``management/commands`` directory to the application. Django +will register a ``manage.py`` command for each Python module in that directory +whose name doesn't begin with an underscore. For example:: polls/ __init__.py diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 56d5c03718..8a8da037f3 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -50,7 +50,7 @@ something like this:: .. _Bridge: https://en.wikipedia.org/wiki/Contract_bridge -This is just an ordinary Python class, with nothing Django-specific about it. +This is an ordinary Python class, with nothing Django-specific about it. We'd like to be able to do things like this in our models (we assume the ``hand`` attribute on the model is an instance of ``Hand``):: @@ -81,11 +81,12 @@ Background theory Database storage ---------------- -The simplest way to think of a model field is that it provides a way to take a -normal Python object -- string, boolean, ``datetime``, or something more -complex like ``Hand`` -- and convert it to and from a format that is useful -when dealing with the database (and serialization, but, as we'll see later, -that falls out fairly naturally once you have the database side under control). +Let's start with model fields. If you break it down, a model field provides a +way to take a normal Python object -- string, boolean, ``datetime``, or +something more complex like ``Hand`` -- and convert it to and from a format +that is useful when dealing with the database. (Such a format is also useful +for serialization, but as we'll see later, that is easier once you have the +database side under control). Fields in a model must somehow be converted to fit into an existing database column type. Different databases provide different sets of valid column types, @@ -94,8 +95,7 @@ with. Anything you want to store in the database must fit into one of those types. Normally, you're either writing a Django field to match a particular database -column type, or there's a fairly straightforward way to convert your data to, -say, a string. +column type, or you will need a way to convert your data to, say, a string. For our ``Hand`` example, we could convert the card data to a string of 104 characters by concatenating all the cards together in a pre-determined order -- @@ -180,16 +180,16 @@ card values plus their suits; 104 characters in total. with. For example, you can pass both :attr:`~django.db.models.Field.editable` and :attr:`~django.db.models.DateField.auto_now` to a - :class:`django.db.models.DateField` and it will simply ignore the + :class:`django.db.models.DateField` and it will ignore the :attr:`~django.db.models.Field.editable` parameter (:attr:`~django.db.models.DateField.auto_now` being set implies ``editable=False``). No error is raised in this case. This behavior simplifies the field classes, because they don't need to - check for options that aren't necessary. They just pass all the options to + check for options that aren't necessary. They pass all the options to the parent class and then don't use them later on. It's up to you whether you want your fields to be more strict about the options they select, or to - use the simpler, more permissive behavior of the current fields. + use the more permissive behavior of the current fields. The ``Field.__init__()`` method takes the following parameters: @@ -241,11 +241,11 @@ then there's no need to write a new ``deconstruct()`` method. If, however, you're changing the arguments passed in ``__init__()`` (like we are in ``HandField``), you'll need to supplement the values being passed. -The contract of ``deconstruct()`` is simple; it returns a tuple of four items: -the field's attribute name, the full import path of the field class, the -positional arguments (as a list), and the keyword arguments (as a dict). Note -this is different from the ``deconstruct()`` method :ref:`for custom classes -<custom-deconstruct-method>` which returns a tuple of three things. +``deconstruct()`` returns a tuple of four items: the field's attribute name, +the full import path of the field class, the positional arguments (as a list), +and the keyword arguments (as a dict). Note this is different from the +``deconstruct()`` method :ref:`for custom classes <custom-deconstruct-method>` +which returns a tuple of three things. As a custom field author, you don't need to care about the first two values; the base ``Field`` class has all the code to work out the field's attribute @@ -307,8 +307,8 @@ mind that people will be reconstructing your field from the serialized version for quite a while (possibly years), depending how long your migrations live for. You can see the results of deconstruction by looking in migrations that include -the field, and you can test deconstruction in unit tests by just deconstructing -and reconstructing the field:: +the field, and you can test deconstruction in unit tests by deconstructing and +reconstructing the field:: name, path, args, kwargs = my_field_instance.deconstruct() new_instance = MyField(*args, **kwargs) @@ -349,10 +349,10 @@ As always, you should document your field type, so users will know what it is. In addition to providing a docstring for it, which is useful for developers, you can also allow users of the admin app to see a short description of the field type via the :doc:`django.contrib.admindocs -</ref/contrib/admin/admindocs>` application. To do this simply provide -descriptive text in a :attr:`~Field.description` class attribute of your custom -field. In the above example, the description displayed by the ``admindocs`` -application for a ``HandField`` will be 'A hand of cards (bridge style)'. +</ref/contrib/admin/admindocs>` application. To do this provide descriptive +text in a :attr:`~Field.description` class attribute of your custom field. In +the above example, the description displayed by the ``admindocs`` application +for a ``HandField`` will be 'A hand of cards (bridge style)'. In the :mod:`django.contrib.admindocs` display, the field description is interpolated with ``field.__dict__`` which allows the description to @@ -393,8 +393,8 @@ Once you have ``MytypeField``, you can use it in any model, just like any other If you aim to build a database-agnostic application, you should account for differences in database column types. For example, the date/time column type in PostgreSQL is called ``timestamp``, while the same column in MySQL is called -``datetime``. The simplest way to handle this in a :meth:`~Field.db_type` -method is to check the ``connection.settings_dict['ENGINE']`` attribute. +``datetime``. You can handle this in a :meth:`~Field.db_type` method by +checking the ``connection.settings_dict['ENGINE']`` attribute. For example:: @@ -431,7 +431,7 @@ sense to have a ``CharMaxlength25Field``, shown here:: my_field = CharMaxlength25Field() The better way of doing this would be to make the parameter specifiable at run -time -- i.e., when the class is instantiated. To do that, just implement +time -- i.e., when the class is instantiated. To do that, implement ``Field.__init__()``, like so:: # This is a much more flexible example. @@ -730,7 +730,7 @@ accessed, and what methods are available. It lives at :doc:`file documentation </ref/files/file>`. Once a subclass of ``File`` is created, the new ``FileField`` subclass must be -told to use it. To do so, simply assign the new ``File`` subclass to the special +told to use it. To do so, assign the new ``File`` subclass to the special ``attr_class`` attribute of the ``FileField`` subclass. A few suggestions diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 2ff0cc56f9..977e00b4a3 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -89,7 +89,7 @@ an application. Writing custom template filters =============================== -Custom filters are just Python functions that take one or two arguments: +Custom filters are Python functions that take one or two arguments: * The value of the variable (input) -- not necessarily a string. * The value of the argument -- this can have a default value, or be left @@ -117,8 +117,8 @@ And here's an example of how that filter would be used: {{ somevariable|cut:"0" }} -Most filters don't take arguments. In this case, just leave the argument out of -your function. Example:: +Most filters don't take arguments. In this case, leave the argument out of your +function:: def lower(value): # Only one argument. """Converts a string into all lowercase""" @@ -312,11 +312,11 @@ Template filter code falls into one of two situations: that our function will know whether automatic escaping is in effect when the filter is called. We use ``autoescape`` to decide whether the input data needs to be passed through ``django.utils.html.conditional_escape`` or not. - (In the latter case, we just use the identity function as the "escape" - function.) The ``conditional_escape()`` function is like ``escape()`` except - it only escapes input that is **not** a ``SafeData`` instance. If a - ``SafeData`` instance is passed to ``conditional_escape()``, the data is - returned unchanged. + (In the latter case, we use the identity function as the "escape" function.) + The ``conditional_escape()`` function is like ``escape()`` except it only + escapes input that is **not** a ``SafeData`` instance. If a ``SafeData`` + instance is passed to ``conditional_escape()``, the data is returned + unchanged. Finally, in the above example, we remember to mark the result as safe so that our HTML is inserted directly into the template without further @@ -428,7 +428,7 @@ A few things to note about the ``simple_tag`` helper function: * Checking for the required number of arguments, etc., has already been done by the time our function is called, so we don't need to do that. * The quotes around the argument (if any) have already been stripped away, - so we just receive a plain string. + so we receive a plain string. * If the argument was a template variable, our function is passed the current value of the variable, not the variable itself. @@ -539,7 +539,7 @@ for the template fragment. Example:: Next, create the template used to render the tag's output. This template is a fixed feature of the tag: the tag writer specifies it, not the template -designer. Following our example, the template is very simple: +designer. Following our example, the template is very short: .. code-block:: html+django @@ -645,10 +645,10 @@ the rendering works. When Django compiles a template, it splits the raw template text into ''nodes''. Each node is an instance of ``django.template.Node`` and has -a ``render()`` method. A compiled template is, simply, a list of ``Node`` -objects. When you call ``render()`` on a compiled template object, the template -calls ``render()`` on each ``Node`` in its node list, with the given context. -The results are all concatenated together to form the output of the template. +a ``render()`` method. A compiled template is a list of ``Node`` objects. When +you call ``render()`` on a compiled template object, the template calls +``render()`` on each ``Node`` in its node list, with the given context. The +results are all concatenated together to form the output of the template. Thus, to define a custom template tag, you specify how the raw template tag is converted into a ``Node`` (the compilation function), and what the node's @@ -661,7 +661,7 @@ For each template tag the template parser encounters, it calls a Python function with the tag contents and the parser object itself. This function is responsible for returning a ``Node`` instance based on the contents of the tag. -For example, let's write a full implementation of our simple template tag, +For example, let's write a full implementation of our template tag, ``{% current_time %}``, that displays the current date/time, formatted according to a parameter given in the tag, in :func:`~time.strftime` syntax. It's a good idea to decide the tag syntax before anything else. In our case, let's say the @@ -715,7 +715,7 @@ Notes: arguments. * The function returns a ``CurrentTimeNode`` with everything the node needs - to know about this tag. In this case, it just passes the argument -- + to know about this tag. In this case, it passes the argument -- ``"%Y-%m-%d %I:%M %p"``. The leading and trailing quotes from the template tag are removed in ``format_string[1:-1]``. @@ -853,7 +853,7 @@ the same time: The CycleNode is iterating, but it's iterating globally. As far as Thread 1 and Thread 2 are concerned, it's always returning the same value. This is -obviously not what we want! +not what we want! To address this problem, Django provides a ``render_context`` that's associated with the ``context`` of the template that is currently being rendered. The @@ -965,9 +965,8 @@ You also have to change the renderer to retrieve the actual contents of the ``date_updated`` property of the ``blog_entry`` object. This can be accomplished by using the ``Variable()`` class in ``django.template``. -To use the ``Variable`` class, simply instantiate it with the name of the -variable to be resolved, and then call ``variable.resolve(context)``. So, -for example:: +To use the ``Variable`` class, instantiate it with the name of the variable to +be resolved, and then call ``variable.resolve(context)``. So, for example:: class FormatTimeNode(template.Node): def __init__(self, date_to_be_formatted, format_string): @@ -987,11 +986,11 @@ cannot resolve the string passed to it in the current context of the page. Setting a variable in the context --------------------------------- -The above examples simply output a value. Generally, it's more flexible if your +The above examples output a value. Generally, it's more flexible if your template tags set template variables instead of outputting values. That way, template authors can reuse the values that your template tags create. -To set a variable in the context, just use dictionary assignment on the context +To set a variable in the context, use dictionary assignment on the context object in the ``render()`` method. Here's an updated version of ``CurrentTimeNode`` that sets a template variable ``current_time`` instead of outputting it:: @@ -1116,7 +1115,7 @@ After ``parser.parse()`` is called, the parser hasn't yet "consumed" the ``{% endcomment %}`` tag, so the code needs to explicitly call ``parser.delete_first_token()``. -``CommentNode.render()`` simply returns an empty string. Anything between +``CommentNode.render()`` returns an empty string. Anything between ``{% comment %}`` and ``{% endcomment %}`` is ignored. Parsing until another block tag, and saving contents diff --git a/docs/howto/deployment/wsgi/gunicorn.txt b/docs/howto/deployment/wsgi/gunicorn.txt index bcdff4879e..6091120488 100644 --- a/docs/howto/deployment/wsgi/gunicorn.txt +++ b/docs/howto/deployment/wsgi/gunicorn.txt @@ -5,14 +5,14 @@ How to use Django with Gunicorn .. highlight:: bash Gunicorn_ ('Green Unicorn') is a pure-Python WSGI server for UNIX. It has no -dependencies and is easy to install and use. +dependencies and can be installed using ``pip``. .. _Gunicorn: https://gunicorn.org/ Installing Gunicorn =================== -Installing gunicorn is as easy as ``python -m pip install gunicorn``. For more +Install gunicorn by running ``python -m pip install gunicorn``. For more details, see the `gunicorn documentation`_. .. _gunicorn documentation: https://docs.gunicorn.org/en/latest/install.html @@ -21,10 +21,9 @@ Running Django in Gunicorn as a generic WSGI application ======================================================== When Gunicorn is installed, a ``gunicorn`` command is available which starts -the Gunicorn server process. At its simplest, gunicorn just needs to be called -with the location of a module containing a WSGI application object named -`application`. So for a typical Django project, invoking gunicorn would look -like:: +the Gunicorn server process. The simplest invocation of gunicorn is to pass the +location of a module containing a WSGI application object named +``application``, which for a typical Django project would look like:: gunicorn myproject.wsgi diff --git a/docs/howto/deployment/wsgi/index.txt b/docs/howto/deployment/wsgi/index.txt index ffc0fbe09a..c7416b84fd 100644 --- a/docs/howto/deployment/wsgi/index.txt +++ b/docs/howto/deployment/wsgi/index.txt @@ -7,7 +7,7 @@ servers and applications. .. _WSGI: https://wsgi.readthedocs.io/en/latest/ -Django's :djadmin:`startproject` management command sets up a simple default +Django's :djadmin:`startproject` management command sets up a minimal default WSGI configuration for you, which you can tweak as needed for your project, and direct any WSGI-compliant application server to use. @@ -70,8 +70,8 @@ If this variable isn't set, the default :file:`wsgi.py` sets it to Applying WSGI middleware ======================== -To apply `WSGI middleware`_ you can simply wrap the application object. For -instance you could add these lines at the bottom of :file:`wsgi.py`:: +To apply `WSGI middleware`_ you can wrap the application object. For instance +you could add these lines at the bottom of :file:`wsgi.py`:: from helloworld.wsgi import HelloWorldApplication application = HelloWorldApplication(application) diff --git a/docs/howto/deployment/wsgi/modwsgi.txt b/docs/howto/deployment/wsgi/modwsgi.txt index c2e74d3bae..b2ab1555df 100644 --- a/docs/howto/deployment/wsgi/modwsgi.txt +++ b/docs/howto/deployment/wsgi/modwsgi.txt @@ -57,8 +57,8 @@ virtualenv guide`_ for more details. The ``WSGIPythonPath`` line ensures that your project package is available for import on the Python path; in other words, that ``import mysite`` works. -The ``<Directory>`` piece just ensures that Apache can access your -:file:`wsgi.py` file. +The ``<Directory>`` piece ensures that Apache can access your :file:`wsgi.py` +file. Next we'll need to ensure this :file:`wsgi.py` with a WSGI application object exists. As of Django version 1.4, :djadmin:`startproject` will have created one diff --git a/docs/howto/error-reporting.txt b/docs/howto/error-reporting.txt index 90918dffe4..f71de5b136 100644 --- a/docs/howto/error-reporting.txt +++ b/docs/howto/error-reporting.txt @@ -8,9 +8,9 @@ also prevent malicious users from seeing details of your application that can be revealed by the error pages. However, running with :setting:`DEBUG` set to ``False`` means you'll never see -errors generated by your site -- everyone will just see your public error pages. -You need to keep track of errors that occur in deployed sites, so Django can be -configured to create reports with details about those errors. +errors generated by your site -- everyone will instead see your public error +pages. You need to keep track of errors that occur in deployed sites, so Django +can be configured to create reports with details about those errors. Email reports ============= @@ -63,7 +63,7 @@ not found" errors). Django sends emails about 404 errors when: If those conditions are met, Django will email the users listed in the :setting:`MANAGERS` setting whenever your code raises a 404 and the request has a referer. It doesn't bother to email for 404s that don't have a referer -- -those are usually just people typing in broken URLs or broken Web bots. It also +those are usually people typing in broken URLs or broken Web bots. It also ignores 404s when the referer is equal to the requested URL, since this behavior is from broken Web bots too. diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt index 4ec2b0bae3..b999f037fe 100644 --- a/docs/howto/initial-data.txt +++ b/docs/howto/initial-data.txt @@ -32,8 +32,8 @@ Or, you can write fixtures by hand; fixtures can be written as JSON, XML or YAML .. _PyYAML: https://pyyaml.org/ -As an example, though, here's what a fixture for a simple ``Person`` model might -look like in JSON: +As an example, though, here's what a fixture for a ``Person`` model might look +like in JSON: .. code-block:: js @@ -73,7 +73,7 @@ And here's that same fixture as YAML: You'll store this data in a ``fixtures`` directory inside your app. -Loading data is easy: just call :djadmin:`manage.py loaddata <loaddata>` +You can load data by calling :djadmin:`manage.py loaddata <loaddata>` ``<fixturename>``, where ``<fixturename>`` is the name of the fixture file you've created. Each time you run :djadmin:`loaddata`, the data will be read from the fixture and re-loaded into the database. Note this means that if you diff --git a/docs/howto/legacy-databases.txt b/docs/howto/legacy-databases.txt index 06867eab21..957b33fc65 100644 --- a/docs/howto/legacy-databases.txt +++ b/docs/howto/legacy-databases.txt @@ -62,7 +62,7 @@ each table's creation, modification, and deletion:: If you do want to allow Django to manage the table's lifecycle, you'll need to change the :attr:`~django.db.models.Options.managed` option above to ``True`` -(or simply remove it because ``True`` is its default value). +(or remove it because ``True`` is its default value). Install the core Django tables ============================== diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt index 4d614b6ab8..7c3d1d0a8e 100644 --- a/docs/howto/outputting-csv.txt +++ b/docs/howto/outputting-csv.txt @@ -41,17 +41,16 @@ mention: contains the name of the CSV file. This filename is arbitrary; call it whatever you want. It'll be used by browsers in the "Save as..." dialog, etc. -* Hooking into the CSV-generation API is easy: Just pass ``response`` as the - first argument to ``csv.writer``. The ``csv.writer`` function expects a - file-like object, and :class:`~django.http.HttpResponse` objects fit the - bill. +* You can hook into the CSV-generation API by passing ``response`` as the first + argument to ``csv.writer``. The ``csv.writer`` function expects a file-like + object, and :class:`~django.http.HttpResponse` objects fit the bill. * For each row in your CSV file, call ``writer.writerow``, passing it an :term:`iterable`. * The CSV module takes care of quoting for you, so you don't have to worry - about escaping strings with quotes or commas in them. Just pass - ``writerow()`` your raw strings, and it'll do the right thing. + about escaping strings with quotes or commas in them. Pass ``writerow()`` + your raw strings, and it'll do the right thing. .. _streaming-csv-files: @@ -137,9 +136,9 @@ Then, create the template ``my_template_name.txt``, with this template code: {% for row in data %}"{{ row.0|addslashes }}", "{{ row.1|addslashes }}", "{{ row.2|addslashes }}", "{{ row.3|addslashes }}", "{{ row.4|addslashes }}" {% endfor %} -This template is quite basic. It just iterates over the given data and displays -a line of CSV for each row. It uses the :tfilter:`addslashes` template filter to -ensure there aren't any problems with quotes. +This short template iterates over the given data and displays a line of CSV for +each row. It uses the :tfilter:`addslashes` template filter to ensure there +aren't any problems with quotes. Other text-based formats ======================== diff --git a/docs/howto/outputting-pdf.txt b/docs/howto/outputting-pdf.txt index 8549b0e380..4d75eb9e7c 100644 --- a/docs/howto/outputting-pdf.txt +++ b/docs/howto/outputting-pdf.txt @@ -88,7 +88,7 @@ mention: * You can provide an arbitrary ``filename`` parameter. It'll be used by browsers in the "Save as..." dialog. -* Hooking into the ReportLab API is easy: The same buffer passed as the first +* You can hook into the ReportLab API: The same buffer passed as the first argument to ``canvas.Canvas`` can be fed to the :class:`~django.http.FileResponse` class. diff --git a/docs/howto/static-files/deployment.txt b/docs/howto/static-files/deployment.txt index a9777c0f1b..1b4135e037 100644 --- a/docs/howto/static-files/deployment.txt +++ b/docs/howto/static-files/deployment.txt @@ -12,13 +12,14 @@ Deploying static files Serving static files in production ================================== -The basic outline of putting static files into production is simple: run the -:djadmin:`collectstatic` command when static files change, then arrange for -the collected static files directory (:setting:`STATIC_ROOT`) to be moved to -the static file server and served. Depending on :setting:`STATICFILES_STORAGE`, -files may need to be moved to a new location manually or the :func:`post_process -<django.contrib.staticfiles.storage.StaticFilesStorage.post_process>` method -of the ``Storage`` class might take care of that. +The basic outline of putting static files into production consists of two +steps: run the :djadmin:`collectstatic` command when static files change, then +arrange for the collected static files directory (:setting:`STATIC_ROOT`) to be +moved to the static file server and served. Depending on +:setting:`STATICFILES_STORAGE`, files may need to be moved to a new location +manually or the :func:`post_process +<django.contrib.staticfiles.storage.StaticFilesStorage.post_process>` method of +the ``Storage`` class might take care of that. Of course, as with all deployment tasks, the devil's in the details. Every production setup will be a bit different, so you'll need to adapt the basic @@ -80,11 +81,11 @@ When using these services, the basic workflow would look a bit like the above, except that instead of using ``rsync`` to transfer your static files to the server you'd need to transfer the static files to the storage provider or CDN. -There's any number of ways you might do this, but if the provider has an API a -:doc:`custom file storage backend </howto/custom-file-storage>` will make the -process incredibly simple. If you've written or are using a 3rd party custom -storage backend, you can tell :djadmin:`collectstatic` to use it by setting -:setting:`STATICFILES_STORAGE` to the storage engine. +There's any number of ways you might do this, but if the provider has an API, +you can use a :doc:`custom file storage backend </howto/custom-file-storage>` +to integrate the CDN with your Django project. If you've written or are using a +3rd party custom storage backend, you can tell :djadmin:`collectstatic` to use +it by setting :setting:`STATICFILES_STORAGE` to the storage engine. For example, if you've written an S3 storage backend in ``myproject.storage.S3Storage`` you could use it with:: @@ -93,8 +94,8 @@ For example, if you've written an S3 storage backend in Once that's done, all you have to do is run :djadmin:`collectstatic` and your static files would be pushed through your storage package up to S3. If you -later needed to switch to a different storage provider, it could be as simple -as changing your :setting:`STATICFILES_STORAGE` setting. +later needed to switch to a different storage provider, you may only have to +change your :setting:`STATICFILES_STORAGE` setting. For details on how you'd write one of these backends, see :doc:`/howto/custom-file-storage`. There are 3rd party apps available that diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt index c21c75a8d1..7b8366e66e 100644 --- a/docs/howto/static-files/index.txt +++ b/docs/howto/static-files/index.txt @@ -67,7 +67,7 @@ details on how ``staticfiles`` finds your files. first static file it finds whose name matches, and if you had a static file with the same name in a *different* application, Django would be unable to distinguish between them. We need to be able to point Django at the right - one, and the easiest way to ensure this is by *namespacing* them. That is, + one, and the best way to ensure this is by *namespacing* them. That is, by putting those static files inside *another* directory named for the application itself. diff --git a/docs/howto/windows.txt b/docs/howto/windows.txt index 9c1705f90a..c0750ab713 100644 --- a/docs/howto/windows.txt +++ b/docs/howto/windows.txt @@ -57,7 +57,7 @@ Install ``virtualenv`` and ``virtualenvwrapper`` `virtualenv`_ and `virtualenvwrapper`_ provide a dedicated environment for each Django project you create. While not mandatory, this is considered a best practice and will save you time in the future when you're ready to deploy your -project. Simply type:: +project. To do this, run:: ...\> py -m pip install virtualenvwrapper-win diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 858de4ad08..89c11c3a32 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -46,13 +46,13 @@ particular: include a clear, concise description of the problem, and a set of instructions for replicating it. Add as much debug information as you can: code snippets, test cases, exception backtraces, screenshots, etc. A nice - small test case is the best way to report a bug, as it gives us an easy - way to confirm the bug quickly. + small test case is the best way to report a bug, as it gives us a + helpful way to confirm the bug quickly. -* **Don't** post to |django-developers| just to announce that you have - filed a bug report. All the tickets are mailed to another list, - |django-updates|, which is tracked by developers and interested - community members; we see them as they are filed. +* **Don't** post to |django-developers| only to announce that you have filed a + bug report. All the tickets are mailed to another list, |django-updates|, + which is tracked by developers and interested community members; we see them + as they are filed. To understand the lifecycle of your ticket once you have created it, refer to :doc:`triaging-tickets`. @@ -116,8 +116,8 @@ ticket description. As with most open-source projects, code talks. If you are willing to write the code for the feature yourself or, even better, if you've already written it, -it's much more likely to be accepted. Just fork Django on GitHub, create a -feature branch, and show us your work! +it's much more likely to be accepted. Fork Django on GitHub, create a feature +branch, and show us your work! See also: :ref:`documenting-new-features`. diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index 64e5dfebcd..13c139c5c5 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -11,8 +11,8 @@ contribute code to Django, look at :doc:`writing-code/working-with-git` instead. Handling pull requests ====================== -Since Django is now hosted at GitHub, most patches are provided in the form of -pull requests. +Since Django is hosted on GitHub, patches are provided in the form of pull +requests. When committing a pull request, make sure each individual commit matches the commit guidelines described below. Contributors are expected to provide the @@ -26,14 +26,14 @@ builders that doesn't run automatically, such as Oracle or Selenium. See the .. _Jenkins wiki page: https://code.djangoproject.com/wiki/Jenkins -An easy way to checkout a pull request locally is to add an alias to your -``~/.gitconfig`` (``upstream`` is assumed to be ``django/django``):: +If you find yourself checking out pull requests locally more often, this git +alias will be helpful:: [alias] pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\" -Now you can simply run ``git pr ####`` to checkout the corresponding pull -request. +Add it to your ``~/.gitconfig``, and set ``upstream`` to be ``django/django``. +Then you can run ``git pr ####`` to checkout the corresponding pull request. At this point, you can work on the code. Use ``git rebase -i`` and ``git commit --amend`` to make sure the commits have the expected level of quality. @@ -243,8 +243,8 @@ When a mistaken commit is discovered, please follow these guidelines: * The release branch maintainer may back out commits to the release branch without permission if the commit breaks the release branch. -* If you mistakenly push a topic branch to ``django/django``, just delete it. +* If you mistakenly push a topic branch to ``django/django``, delete it. For instance, if you did: ``git push upstream feature_antigravity``, - just do a reverse push: ``git push upstream :feature_antigravity``. + do a reverse push: ``git push upstream :feature_antigravity``. .. _ticket tracker: https://code.djangoproject.com/ diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt index c7f2d3726b..e2f47da2a3 100644 --- a/docs/internals/contributing/index.txt +++ b/docs/internals/contributing/index.txt @@ -36,7 +36,7 @@ development: on the `#django-dev IRC channel`_. * :doc:`Submit patches <writing-code/submitting-patches>` for new and/or - fixed behavior. If you're looking for an easy way to start contributing + fixed behavior. If you're looking for a way to get started contributing to Django read the :doc:`/intro/contributing` tutorial and have a look at the `easy pickings`_ tickets. The :ref:`patch-review-checklist` will also be helpful. diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index 90fa97cf28..79a1b11809 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -13,7 +13,7 @@ to get started? This is the section for you. First steps =========== -Start with these easy tasks to discover Django's development process. +Start with these steps to discover Django's development process. * **Sign the Contributor License Agreement** @@ -45,7 +45,7 @@ Start with these easy tasks to discover Django's development process. Oftentimes the codebase will change between a patch being submitted and the time it gets reviewed. Make sure it still applies cleanly and functions as - expected. Simply updating a patch is both useful and important! See more on + expected. Updating a patch is both useful and important! See more on :doc:`writing-code/submitting-patches`. * **Write some documentation** diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index 043ad93154..10098cbfca 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -17,12 +17,11 @@ community as a whole to self-manage, keep the problems to a minimum, and educate those coming into the community so that they can become valuable contributing members. -Similarly, while we aim for Trac to be a perfect representation of the state -of Django's progress, we acknowledge that this simply will not happen. By -distributing the load of Trac maintenance to the community, we accept that -there will be mistakes. Trac is "mostly accurate", and we give allowances for -the fact that sometimes it will be wrong. That's okay. We're perfectionists -with deadlines. +Similarly, while we aim for Trac to be a perfect representation of the state of +Django's progress, we acknowledge that this will not happen. By distributing +the load of Trac maintenance to the community, we accept that there will be +mistakes. Trac is "mostly accurate", and we give allowances for the fact that +sometimes it will be wrong. That's okay. We're perfectionists with deadlines. We rely on the community to keep participating, keep tickets as accurate as possible, and raise issues for discussion on our mailing lists when there is @@ -269,8 +268,8 @@ When a ticket has completed its useful lifecycle, it's time for it to be closed. Closing a ticket is a big responsibility, though. You have to be sure that the issue is really resolved, and you need to keep in mind that the reporter of the ticket may not be happy to have their ticket closed (unless -it's fixed, of course). If you're not certain about closing a ticket, just -leave a comment with your thoughts instead. +it's fixed, of course). If you're not certain about closing a ticket, leave a +comment with your thoughts instead. If you do close a ticket, you should always make sure of the following: diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 5bfff59b52..d70bc428d1 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -85,10 +85,9 @@ Which tickets should be claimed? Of course, going through the steps of claiming tickets is overkill in some cases. -In the case of small changes, such as typos in the documentation or -small bugs that will only take a few minutes to fix, you don't need to jump -through the hoops of claiming tickets. Just submit your patch and be done with -it. +In the case of small changes, such as typos in the documentation or small bugs +that will only take a few minutes to fix, you don't need to jump through the +hoops of claiming tickets. Submit your patch directly and you're done! Of course, it is *always* acceptable, regardless whether someone has claimed it or not, to submit patches to a ticket if you happen to have a patch ready. @@ -145,14 +144,14 @@ Regardless of the way you submit your work, follow these steps. Non-trivial patches =================== -A "non-trivial" patch is one that is more than a simple bug fix. It's a patch +A "non-trivial" patch is one that is more than a small bug fix. It's a patch that introduces Django functionality and makes some sort of design decision. If you provide a non-trivial patch, include evidence that alternatives have been discussed on |django-developers|. -If you're not sure whether your patch should be considered non-trivial, just -ask. +If you're not sure whether your patch should be considered non-trivial, ask on +the ticket for opinions. .. _deprecating-a-feature: diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 291c50852c..a4c7ea09b0 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -45,10 +45,10 @@ test dependencies. If you don't have an optional dependency installed, the tests that require it will be skipped. Running the tests requires a Django settings module that defines the databases -to use. To make it easy to get started, Django provides and uses a sample -settings module that uses the SQLite database. See -:ref:`running-unit-tests-settings` to learn how to use a different settings -module to run the tests with a different database. +to use. To help you get started, Django provides and uses a sample settings +module that uses the SQLite database. See :ref:`running-unit-tests-settings` to +learn how to use a different settings module to run the tests with a different +database. Having problems? See :ref:`troubleshooting-unit-tests` for some common issues. @@ -199,7 +199,7 @@ internationalization, type: How do you find out the names of individual tests? Look in ``tests/`` — each directory name there is the name of a test. -If you just want to run a particular class of tests, you can specify a list of +If you want to run only a particular class of tests, you can specify a list of paths to individual test classes. For example, to run the ``TranslationTests`` of the ``i18n`` module, type: diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index 60ba1345a4..639f7719b8 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -98,7 +98,7 @@ necessary:: Publishing work --------------- -You can publish your work on GitHub just by doing:: +You can publish your work on GitHub by running:: git push origin ticket_xxxxx @@ -186,9 +186,9 @@ the changes:: git push -f origin ticket_xxxxx Note that this will rewrite history of ticket_xxxxx - if you check the commit -hashes before and after the operation at GitHub you will notice that the -commit hashes do not match anymore. This is acceptable, as the branch is merely -a topic branch, and nobody should be basing their work on it. +hashes before and after the operation at GitHub you will notice that the commit +hashes do not match anymore. This is acceptable, as the branch is a topic +branch, and nobody should be basing their work on it. After upstream has changed -------------------------- diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 9e52e55563..577a611d8d 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -201,15 +201,15 @@ documentation: This is because Sphinx will generate proper links for the latter, which greatly helps readers. - You can prefix the target with a ``~`` (that's a tilde) to get just the - "last bit" of that path. So ``:mod:`~django.contrib.auth``` will just + You can prefix the target with a ``~`` (that's a tilde) to get only the + "last bit" of that path. So ``:mod:`~django.contrib.auth``` will display a link with the title "auth". * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' documentation. * Add ``.. code-block:: <lang>`` to literal blocks so that they get - highlighted. Prefer relying on automatic highlighting simply using ``::`` + highlighted. Prefer relying on automatic highlighting using ``::`` (two colons). This has the benefit that if the code contains some invalid syntax, it won't be highlighted. Adding ``.. code-block:: python``, for example, will force highlighting despite invalid syntax. @@ -383,8 +383,8 @@ If a function, attribute, etc. is added, it's also okay to use a An author's middle name. -We can simply remove the ``.. versionadded:: A.B`` annotation without any -indentation changes when the time comes. +We can remove the ``.. versionadded:: A.B`` annotation without any indentation +changes when the time comes. Minimizing images ================= diff --git a/docs/internals/git.txt b/docs/internals/git.txt index 90ff3ff3c5..9782f59888 100644 --- a/docs/internals/git.txt +++ b/docs/internals/git.txt @@ -70,10 +70,10 @@ documentation, test suite, packaging scripts and other miscellaneous bits. Django's code will be present in your clone as a directory named ``django``. -To try out the in-development code with your own applications, simply place -the directory containing your clone on your Python import path. Then -``import`` statements which look for Django will find the ``django`` module -within your clone. +To try out the in-development code with your own applications, place the +directory containing your clone on your Python import path. Then ``import`` +statements which look for Django will find the ``django`` module within your +clone. If you're going to be working on Django's code (say, to fix a bug or develop a new feature), you can probably stop reading here and move diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt index d201f60d8e..9803558805 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -172,7 +172,7 @@ OK, this is the fun part, where we actually push out a release! #. If this is a security release, merge the appropriate patches from ``django-security``. Rebase these patches as necessary to make each one a - simple commit on the release branch rather than a merge commit. To ensure + plain commit on the release branch rather than a merge commit. To ensure this, merge them with the ``--ff-only`` flag; for example:: $ git checkout stable/1.5.x diff --git a/docs/internals/security.txt b/docs/internals/security.txt index 8fb9583b63..438325b330 100644 --- a/docs/internals/security.txt +++ b/docs/internals/security.txt @@ -163,8 +163,8 @@ notification of security issues is not and will not be made public. We also aim to keep this list as small as effectively possible, in order to better manage the flow of confidential information prior to disclosure. As such, our notification list is *not* simply a list of -users of Django, and merely being a user of Django is not sufficient -reason to be placed on the notification list. +users of Django, and being a user of Django is not sufficient reason +to be placed on the notification list. In broad terms, recipients of security notifications fall into three groups: diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index 013f631f0a..b21ec57f6d 100644 --- a/docs/intro/contributing.txt +++ b/docs/intro/contributing.txt @@ -10,8 +10,9 @@ in Django that you'd like to see fixed, or maybe there's a small feature you want added. Contributing back to Django itself is the best way to see your own concerns -addressed. This may seem daunting at first, but it's really pretty simple. -We'll walk you through the entire process, so you can learn by example. +addressed. This may seem daunting at first, but it's a well-traveled path with +documentation, tooling, and a community to support you. We'll walk you through +the entire process, so you can learn by example. Who's this tutorial for? ------------------------ @@ -387,7 +388,7 @@ Running Django's test suite for the second time =============================================== Once you've verified that your patch and your test are working correctly, it's -a good idea to run the entire Django test suite just to verify that your change +a good idea to run the entire Django test suite to verify that your change hasn't introduced any bugs into other areas of Django. While successfully passing the entire test suite doesn't guarantee your code is bug free, it does help identify many bugs and regressions that might otherwise go unnoticed. @@ -592,7 +593,7 @@ If you just want to get started already (and nobody would blame you!), try taking a look at the list of `easy tickets that need patches`__ and the `easy tickets that have patches which need improvement`__. If you're familiar with writing tests, you can also look at the list of -`easy tickets that need tests`__. Just remember to follow the guidelines about +`easy tickets that need tests`__. Remember to follow the guidelines about claiming tickets that were mentioned in the link to Django's documentation on :doc:`claiming tickets and submitting patches </internals/contributing/writing-code/submitting-patches>`. diff --git a/docs/intro/install.txt b/docs/intro/install.txt index d1ac700372..dc8399d933 100644 --- a/docs/intro/install.txt +++ b/docs/intro/install.txt @@ -4,8 +4,8 @@ Quick install guide Before you can use Django, you'll need to get it installed. We have a :doc:`complete installation guide </topics/install>` that covers all the -possibilities; this guide will guide you to a simple, minimal installation -that'll work while you walk through the introduction. +possibilities; this guide will guide you to a minimal installation that'll work +while you walk through the introduction. Install Python ============== @@ -37,7 +37,7 @@ the :ref:`database installation information <database-installation>`. Install Django ============== -You've got three easy options to install Django: +You've got three options to install Django: * :ref:`Install an official release <installing-official-release>`. This is the best approach for most users. diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 47af40533c..a1d82137ad 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -144,8 +144,8 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house Once your models are defined, Django can automatically create a professional, production ready :doc:`administrative interface </ref/contrib/admin/index>` -- -a website that lets authenticated users add, change and delete objects. It's -as easy as registering your model in the admin site: +a website that lets authenticated users add, change and delete objects. The +only step required is to register your model in the admin site: .. code-block:: python :caption: mysite/news/models.py @@ -169,7 +169,7 @@ as easy as registering your model in the admin site: The philosophy here is that your site is edited by a staff, or a client, or maybe just you -- and you don't want to have to deal with creating backend -interfaces just to manage content. +interfaces only to manage content. One typical workflow in creating Django apps is to create models and get the admin sites up and running as fast as possible, so your staff (or clients) can @@ -183,9 +183,9 @@ application. Django encourages beautiful URL design and doesn't put any cruft in URLs, like ``.php`` or ``.asp``. To design URLs for an app, you create a Python module called a :doc:`URLconf -</topics/http/urls>`. A table of contents for your app, it contains a simple -mapping between URL patterns and Python callback functions. URLconfs also serve -to decouple URLs from Python code. +</topics/http/urls>`. A table of contents for your app, it contains a mapping +between URL patterns and Python callback functions. URLconfs also serve to +decouple URLs from Python code. Here's what a URLconf might look like for the ``Reporter``/``Article`` example above: @@ -315,12 +315,12 @@ Here's what the "base.html" template, including the use of :doc:`static files </html> Simplistically, it defines the look-and-feel of the site (with the site's logo), -and provides "holes" for child templates to fill. This makes a site redesign as -easy as changing a single file -- the base template. +and provides "holes" for child templates to fill. This means that a site redesign +can be done by changing a single file -- the base template. It also lets you create multiple versions of a site, with different base templates, while reusing child templates. Django's creators have used this -technique to create strikingly different mobile versions of sites -- simply by +technique to create strikingly different mobile versions of sites by only creating a new base template. Note that you don't have to use Django's template system if you prefer another @@ -340,15 +340,14 @@ features: * A :doc:`caching framework </topics/cache>` that integrates with memcached or other backends. -* A :doc:`syndication framework </ref/contrib/syndication>` that makes - creating RSS and Atom feeds as easy as writing a small Python class. +* A :doc:`syndication framework </ref/contrib/syndication>` that lets you + create RSS and Atom feeds by writing a small Python class. * More attractive automatically-generated admin features -- this overview barely scratched the surface. -The next obvious steps are for you to `download Django`_, read :doc:`the -tutorial </intro/tutorial01>` and join `the community`_. Thanks for your -interest! +The next steps are for you to `download Django`_, read :doc:`the tutorial +</intro/tutorial01>` and join `the community`_. Thanks for your interest! .. _download Django: https://www.djangoproject.com/download/ .. _the community: https://www.djangoproject.com/community/ diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index 2777c0b104..ba6f1ddd07 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -20,7 +20,7 @@ Reusability is the way of life in Python. `The Python Package Index (PyPI) <https://pypi.org/>`_ has a vast range of packages you can use in your own Python programs. Check out `Django Packages <https://djangopackages.org>`_ for existing reusable apps you could incorporate in your project. Django itself is -also just a Python package. This means that you can take existing Python +also a normal Python package. This means that you can take existing Python packages or Django apps and compose them into your own web project. You only need to write the parts that make your project unique. @@ -41,8 +41,8 @@ projects and ready to publish for others to install and use. bar``. For a directory (like ``polls``) to form a package, it must contain a special file ``__init__.py``, even if this file is empty. - A Django *application* is just a Python package that is specifically - intended for use in a Django project. An application may use common Django + A Django *application* is a Python package that is specifically intended + for use in a Django project. An application may use common Django conventions, such as having ``models``, ``tests``, ``urls``, and ``views`` submodules. @@ -148,8 +148,8 @@ this. For a small app like polls, this process isn't too difficult. Polls ===== - Polls is a simple Django app to conduct Web-based polls. For each - question, visitors can choose between a fixed number of answers. + Polls is a Django app to conduct Web-based polls. For each question, + visitors can choose between a fixed number of answers. Detailed documentation is in the "docs" directory. @@ -206,7 +206,7 @@ this. For a small app like polls, this process isn't too difficult. packages=find_packages(), include_package_data=True, license='BSD License', # example license - description='A simple Django app to conduct Web-based polls.', + description='A Django app to conduct Web-based polls.', long_description=README, url='https://www.example.com/', author='Your Name', diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index b3358de26b..2f4c59be18 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -90,9 +90,8 @@ Let's look at what :djadmin:`startproject` created:: These files are: -* The outer :file:`mysite/` root directory is just a container for your - project. Its name doesn't matter to Django; you can rename it to anything - you like. +* The outer :file:`mysite/` root directory is a container for your project. Its + name doesn't matter to Django; you can rename it to anything you like. * :file:`manage.py`: A command-line utility that lets you interact with this Django project in various ways. You can read all the details about @@ -207,7 +206,7 @@ rather than creating directories. What's the difference between a project and an app? An app is a Web application that does something -- e.g., a Weblog system, a database of - public records or a simple poll app. A project is a collection of + public records or a small poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps. An app can be in multiple projects. diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index 4b66ea16c2..f8ff294573 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -123,16 +123,16 @@ additional metadata. place and automatically derive things from it. This includes the migrations - unlike in Ruby On Rails, for example, migrations - are entirely derived from your models file, and are essentially just a + are entirely derived from your models file, and are essentially a history that Django can roll through to update your database schema to match your current models. -In our simple poll app, we'll create two models: ``Question`` and ``Choice``. -A ``Question`` has a question and a publication date. A ``Choice`` has two +In our poll app, we'll create two models: ``Question`` and ``Choice``. A +``Question`` has a question and a publication date. A ``Choice`` has two fields: the text of the choice and a vote tally. Each ``Choice`` is associated with a ``Question``. -These concepts are represented by simple Python classes. Edit the +These concepts are represented by Python classes. Edit the :file:`polls/models.py` file so it looks like this: .. code-block:: python @@ -151,9 +151,9 @@ These concepts are represented by simple Python classes. Edit the choice_text = models.CharField(max_length=200) votes = models.IntegerField(default=0) -The code is straightforward. Each model is represented by a class that -subclasses :class:`django.db.models.Model`. Each model has a number of class -variables, each of which represents a database field in the model. +Here, each model is represented by a class that subclasses +:class:`django.db.models.Model`. Each model has a number of class variables, +each of which represents a database field in the model. Each field is represented by an instance of a :class:`~django.db.models.Field` class -- e.g., :class:`~django.db.models.CharField` for character fields and @@ -245,11 +245,11 @@ some changes to your models (in this case, you've made new ones) and that you'd like the changes to be stored as a *migration*. Migrations are how Django stores changes to your models (and thus your -database schema) - they're just files on disk. You can read the migration -for your new model if you like; it's the file -``polls/migrations/0001_initial.py``. Don't worry, you're not expected to read -them every time Django makes one, but they're designed to be human-editable -in case you want to manually tweak how Django changes things. +database schema) - they're files on disk. You can read the migration for your +new model if you like; it's the file ``polls/migrations/0001_initial.py``. +Don't worry, you're not expected to read them every time Django makes one, but +they're designed to be human-editable in case you want to manually tweak how +Django changes things. There's a command that will run the migrations for you and manage your database schema automatically - that's called :djadmin:`migrate`, and we'll come to it in a @@ -311,7 +311,7 @@ Note the following: (Yes, you can override this, as well.) * The foreign key relationship is made explicit by a ``FOREIGN KEY`` - constraint. Don't worry about the ``DEFERRABLE`` parts; that's just telling + constraint. Don't worry about the ``DEFERRABLE`` parts; it's telling PostgreSQL to not enforce the foreign key until the end of the transaction. * It's tailored to the database you're using, so database-specific field types @@ -321,7 +321,7 @@ Note the following: single quotes. * The :djadmin:`sqlmigrate` command doesn't actually run the migration on your - database - it just prints it to the screen so that you can see what SQL + database - instead, it prints it to the screen so that you can see what SQL Django thinks is required. It's useful for checking what Django is going to do or if you have database administrators who require SQL scripts for changes. @@ -640,9 +640,9 @@ Make the poll app modifiable in the admin But where's our poll app? It's not displayed on the admin index page. -Just one thing to do: we need to tell the admin that ``Question`` -objects have an admin interface. To do this, open the :file:`polls/admin.py` -file, and edit it to look like this: +Only one more thing to do: we need to tell the admin that ``Question`` objects +have an admin interface. To do this, open the :file:`polls/admin.py` file, and +edit it to look like this: .. code-block:: python :caption: polls/admin.py diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index 1a9d21c3c5..1d775e844b 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -40,16 +40,16 @@ In our poll application, we'll have the following four views: question. In Django, web pages and other content are delivered by views. Each view is -represented by a simple Python function (or method, in the case of class-based -views). Django will choose a view by examining the URL that's requested (to be -precise, the part of the URL after the domain name). +represented by a Python function (or method, in the case of class-based views). +Django will choose a view by examining the URL that's requested (to be precise, +the part of the URL after the domain name). Now in your time on the web you may have come across such beauties as "ME2/Sites/dirmod.asp?sid=&type=gen&mod=Core+Pages&gid=A6CD4967199A42D9B65B1B". You will be pleased to know that Django allows us much more elegant *URL patterns* than that. -A URL pattern is simply the general form of a URL - for example: +A URL pattern is the general form of a URL - for example: ``/newsarchive/<year>/<month>/``. To get from a URL to a view, Django uses what are known as 'URLconfs'. A @@ -181,7 +181,7 @@ directory called ``polls``, and within that create a file called ``index.html``. In other words, your template should be at ``polls/templates/polls/index.html``. Because of how the ``app_directories`` template loader works as described above, you can refer to this template within -Django simply as ``polls/index.html``. +Django as ``polls/index.html``. .. admonition:: Template namespacing @@ -190,7 +190,7 @@ Django simply as ``polls/index.html``. but it would actually be a bad idea. Django will choose the first template it finds whose name matches, and if you had a template with the same name in a *different* application, Django would be unable to distinguish between - them. We need to be able to point Django at the right one, and the easiest + them. We need to be able to point Django at the right one, and the best way to ensure this is by *namespacing* them. That is, by putting those templates inside *another* directory named for the application itself. @@ -455,4 +455,5 @@ to point at the namespaced detail view: <li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li> When you're comfortable with writing views, read :doc:`part 4 of this tutorial -</intro/tutorial04>` to learn about simple form processing and generic views. +</intro/tutorial04>` to learn the basics about form processing and generic +views. diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index 6bfe506d70..c707ba6967 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -3,11 +3,11 @@ Writing your first Django app, part 4 ===================================== This tutorial begins where :doc:`Tutorial 3 </intro/tutorial03>` left off. We're -continuing the Web-poll application and will focus on simple form processing and +continuing the Web-poll application and will focus on form processing and cutting down our code. -Write a simple form -=================== +Write a minimal form +==================== Let's update our poll detail template ("polls/detail.html") from the last tutorial, so that the template contains an HTML ``<form>`` element: @@ -42,17 +42,17 @@ A quick rundown: ``method="get"``) is very important, because the act of submitting this form will alter data server-side. Whenever you create a form that alters data server-side, use ``method="post"``. This tip isn't specific to - Django; it's just good Web development practice. + Django; it's good Web development practice in general. * ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone through its loop * Since we're creating a POST form (which can have the effect of modifying data), we need to worry about Cross Site Request Forgeries. - Thankfully, you don't have to worry too hard, because Django comes with - a very easy-to-use system for protecting against it. In short, all POST - forms that are targeted at internal URLs should use the - :ttag:`{% csrf_token %}<csrf_token>` template tag. + Thankfully, you don't have to worry too hard, because Django comes with a + helpful system for protecting against it. In short, all POST forms that are + targeted at internal URLs should use the :ttag:`{% csrf_token %}<csrf_token>` + template tag. Now, let's create a Django view that handles the submitted data and does something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we @@ -121,8 +121,8 @@ This code includes a few things we haven't covered yet in this tutorial: As the Python comment above points out, you should always return an :class:`~django.http.HttpResponseRedirect` after successfully dealing with - POST data. This tip isn't specific to Django; it's just good Web - development practice. + POST data. This tip isn't specific to Django; it's good Web development + practice in general. * We are using the :func:`~django.urls.reverse` function in the :class:`~django.http.HttpResponseRedirect` constructor in this example. @@ -196,7 +196,7 @@ Use generic views: Less code is better ====================================== The ``detail()`` (from :doc:`Tutorial 3 </intro/tutorial03>`) and ``results()`` -views are very simple -- and, as mentioned above, redundant. The ``index()`` +views are very short -- and, as mentioned above, redundant. The ``index()`` view, which displays a list of polls, is similar. These views represent a common case of basic Web development: getting data from @@ -208,8 +208,8 @@ Generic views abstract common patterns to the point where you don't even need to write Python code to write an app. Let's convert our poll app to use the generic views system, so we can delete a -bunch of our own code. We'll just have to take a few steps to make the -conversion. We will: +bunch of our own code. We'll have to take a few steps to make the conversion. +We will: #. Convert the URLconf. @@ -331,8 +331,8 @@ However, for ListView, the automatically generated context variable is ``question_list``. To override this we provide the ``context_object_name`` attribute, specifying that we want to use ``latest_question_list`` instead. As an alternative approach, you could change your templates to match -the new default context variables -- but it's a lot easier to just -tell Django to use the variable you want. +the new default context variables -- but it's a lot easier to tell Django to +use the variable you want. Run the server, and use your new polling app based on generic views. diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt index c59a0db155..96438734b4 100644 --- a/docs/intro/tutorial05.txt +++ b/docs/intro/tutorial05.txt @@ -12,7 +12,7 @@ Introducing automated testing What are automated tests? ------------------------- -Tests are simple routines that check the operation of your code. +Tests are routines that check the operation of your code. Testing operates at different levels. Some tests might apply to a tiny detail (*does a particular model method return values as expected?*) while others @@ -51,7 +51,7 @@ interactions between components. A change in any of those components could have unexpected consequences on the application's behavior. Checking that it still 'seems to work' could mean running through your code's functionality with twenty different variations of -your test data just to make sure you haven't broken something - not a good use +your test data to make sure you haven't broken something - not a good use of your time. That's especially true when automated tests could do this for you in seconds. @@ -83,9 +83,9 @@ Tests make your code more attractive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You might have created a brilliant piece of software, but you will find that -many other developers will simply refuse to look at it because it lacks tests; -without tests, they won't trust it. Jacob Kaplan-Moss, one of Django's -original developers, says "Code without tests is broken by design." +many other developers will refuse to look at it because it lacks tests; without +tests, they won't trust it. Jacob Kaplan-Moss, one of Django's original +developers, says "Code without tests is broken by design." That other developers want to see tests in your software before they take it seriously is yet another reason for you to start writing tests. @@ -108,7 +108,7 @@ Some programmers follow a discipline called "`test-driven development`_"; they actually write their tests before they write their code. This might seem counter-intuitive, but in fact it's similar to what most people will often do anyway: they describe a problem, then create some code to solve it. Test-driven -development simply formalizes the problem in a Python test case. +development formalizes the problem in a Python test case. More often, a newcomer to testing will create some code and later decide that it should have some tests. Perhaps it would have been better to write some @@ -270,9 +270,9 @@ After identifying a bug, we wrote a test that exposes it and corrected the bug in the code so our test passes. Many other things might go wrong with our application in the future, but we can -be sure that we won't inadvertently reintroduce this bug, because simply -running the test will warn us immediately. We can consider this little portion -of the application pinned down safely forever. +be sure that we won't inadvertently reintroduce this bug, because running the +test will warn us immediately. We can consider this little portion of the +application pinned down safely forever. More comprehensive tests ------------------------ @@ -308,7 +308,7 @@ more comprehensively: And now we have three tests that confirm that ``Question.was_published_recently()`` returns sensible values for past, recent, and future questions. -Again, ``polls`` is a simple application, but however complex it grows in the +Again, ``polls`` is a minimal application, but however complex it grows in the future and whatever other code it interacts with, we now have some guarantee that the method we have written tests for will behave in expected ways. @@ -324,8 +324,8 @@ A test for a view ----------------- When we fixed the bug above, we wrote the test first and then the code to fix -it. In fact that was a simple example of test-driven development, but it -doesn't really matter in which order we do the work. +it. In fact that was an example of test-driven development, but it doesn't +really matter in which order we do the work. In our first test, we focused closely on the internal behavior of the code. For this test, we want to check its behavior as it would be experienced by a user diff --git a/docs/intro/tutorial06.txt b/docs/intro/tutorial06.txt index e8b1d02764..91a0a10f24 100644 --- a/docs/intro/tutorial06.txt +++ b/docs/intro/tutorial06.txt @@ -11,11 +11,10 @@ to serve additional files — such as images, JavaScript, or CSS — necessary t render the complete web page. In Django, we refer to these files as "static files". -For small projects, this isn't a big deal, because you can just keep the -static files somewhere your web server can find it. However, in bigger -projects -- especially those comprised of multiple apps -- dealing with the -multiple sets of static files provided by each application starts to get -tricky. +For small projects, this isn't a big deal, because you can keep the static +files somewhere your web server can find it. However, in bigger projects -- +especially those comprised of multiple apps -- dealing with the multiple sets +of static files provided by each application starts to get tricky. That's what ``django.contrib.staticfiles`` is for: it collects static files from each of your applications (and any other places you specify) into a @@ -39,8 +38,8 @@ Within the ``static`` directory you have just created, create another directory called ``polls`` and within that create a file called ``style.css``. In other words, your stylesheet should be at ``polls/static/polls/style.css``. Because of how the ``AppDirectoriesFinder`` staticfile finder works, you can refer to -this static file in Django simply as ``polls/style.css``, similar to how you -reference the path for templates. +this static file in Django as ``polls/style.css``, similar to how you reference +the path for templates. .. admonition:: Static file namespacing @@ -50,8 +49,8 @@ reference the path for templates. first static file it finds whose name matches, and if you had a static file with the same name in a *different* application, Django would be unable to distinguish between them. We need to be able to point Django at the right - one, and the easiest way to ensure this is by *namespacing* them. That is, - by putting those static files inside *another* directory named for the + one, and the best way to ensure this is by *namespacing* them. That is, by + putting those static files inside *another* directory named for the application itself. Put the following code in that stylesheet (``polls/static/polls/style.css``): diff --git a/docs/intro/tutorial07.txt b/docs/intro/tutorial07.txt index 001c6ec998..2325ac8074 100644 --- a/docs/intro/tutorial07.txt +++ b/docs/intro/tutorial07.txt @@ -79,7 +79,7 @@ OK, we have our Question admin page, but a ``Question`` has multiple Yet. There are two ways to solve this problem. The first is to register ``Choice`` -with the admin just as we did with ``Question``. That's easy: +with the admin just as we did with ``Question``: .. code-block:: python :caption: polls/admin.py @@ -159,8 +159,8 @@ that you can't remove the original three slots. This image shows an added slot: One small problem, though. It takes a lot of screen space to display all the fields for entering related ``Choice`` objects. For that reason, Django offers a -tabular way of displaying inline related objects; you just need to change -the ``ChoiceInline`` declaration to read: +tabular way of displaying inline related objects. To use it, change the +``ChoiceInline`` declaration to read: .. code-block:: python :caption: polls/admin.py @@ -201,8 +201,8 @@ object: # ... list_display = ('question_text', 'pub_date') -Just for good measure, let's also include the ``was_published_recently()`` -method from :doc:`Tutorial 2 </intro/tutorial02>`: +For good measure, let's also include the ``was_published_recently()`` method +from :doc:`Tutorial 2 </intro/tutorial02>`: .. code-block:: python :caption: polls/admin.py @@ -284,9 +284,8 @@ Customize the admin look and feel Clearly, having "Django administration" at the top of each admin page is ridiculous. It's just placeholder text. -That's easy to change, though, using Django's template system. The Django admin -is powered by Django itself, and its interfaces use Django's own template -system. +You can change it, though, using Django's template system. The Django admin is +powered by Django itself, and its interfaces use Django's own template system. .. _ref-customizing-your-projects-templates: @@ -346,7 +345,7 @@ template directory in the source code of Django itself $ python -c "import django; print(django.__path__)" -Then, just edit the file and replace +Then, edit the file and replace ``{{ site_header|default:_('Django administration') }}`` (including the curly braces) with your own site's name as you see fit. You should end up with a section of code like: @@ -369,9 +368,8 @@ template language will be evaluated to produce the final HTML page, just like we saw in :doc:`Tutorial 3 </intro/tutorial03>`. Note that any of Django's default admin templates can be overridden. To -override a template, just do the same thing you did with ``base_site.html`` -- -copy it from the default directory into your custom directory, and make -changes. +override a template, do the same thing you did with ``base_site.html`` -- copy +it from the default directory into your custom directory, and make changes. Customizing your *application's* templates ------------------------------------------ diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 7b3a574f17..0222050827 100644 --- a/docs/intro/whatsnext.txt +++ b/docs/intro/whatsnext.txt @@ -13,9 +13,9 @@ Well, we've always been big fans of learning by doing. At this point you should know enough to start a project of your own and start fooling around. As you need to learn new tricks, come back to the documentation. -We've put a lot of effort into making Django's documentation useful, easy to -read and as complete as possible. The rest of this document explains more about -how the documentation works so that you can get the most out of it. +We've put a lot of effort into making Django's documentation useful, clear and +as complete as possible. The rest of this document explains more about how the +documentation works so that you can get the most out of it. (Yes, this is documentation about documentation. Rest assured we have no plans to write a document about how to read the document about documentation.) @@ -74,8 +74,8 @@ different needs: * Finally, there's some "specialized" documentation not usually relevant to most developers. This includes the :doc:`release notes </releases/index>` and :doc:`internals documentation </internals/index>` for those who want to add - code to Django itself, and a :doc:`few other things that simply don't fit - elsewhere </misc/index>`. + code to Django itself, and a :doc:`few other things that don't fit elsewhere + </misc/index>`. How documentation is updated @@ -155,7 +155,7 @@ Django document: As HTML, locally ---------------- -You can get a local copy of the HTML documentation following a few easy steps: +You can get a local copy of the HTML documentation following a few steps: * Django's documentation uses a system called Sphinx__ to convert from plain text to HTML. You'll need to install Sphinx by either downloading @@ -165,8 +165,7 @@ You can get a local copy of the HTML documentation following a few easy steps: $ python -m pip install Sphinx -* Then, just use the included ``Makefile`` to turn the documentation into - HTML: +* Then, use the included ``Makefile`` to turn the documentation into HTML: .. code-block:: console diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index e735fce951..89ba64e691 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -8,7 +8,7 @@ Django contains a registry of installed applications that stores configuration and provides introspection. It also maintains a list of available :doc:`models </topics/db/models>`. -This registry is simply called :attr:`~django.apps.apps` and it's available in +This registry is called :attr:`~django.apps.apps` and it's available in :mod:`django.apps`:: >>> from django.apps import apps @@ -40,7 +40,7 @@ projects with the :setting:`INSTALLED_APPS` setting and optionally with other mechanisms such as URLconfs, the :setting:`MIDDLEWARE` setting, or template inheritance. -It is important to understand that a Django application is just a set of code +It is important to understand that a Django application is a set of code that interacts with various parts of the framework. There's no such thing as an ``Application`` object. However, there's a few places where Django needs to interact with installed applications, mainly for configuration and also for @@ -59,9 +59,8 @@ Configuring applications To configure an application, subclass :class:`~django.apps.AppConfig` and put the dotted path to that subclass in :setting:`INSTALLED_APPS`. -When :setting:`INSTALLED_APPS` simply contains the dotted path to an -application module, Django checks for a ``default_app_config`` variable in -that module. +When :setting:`INSTALLED_APPS` contains the dotted path to an application +module, Django checks for a ``default_app_config`` variable in that module. If it's defined, it's the dotted path to the :class:`~django.apps.AppConfig` subclass for that application. @@ -99,11 +98,11 @@ subclass by default as follows:: default_app_config = 'rock_n_roll.apps.RockNRollConfig' That will cause ``RockNRollConfig`` to be used when :setting:`INSTALLED_APPS` -just contains ``'rock_n_roll'``. This allows you to make use of -:class:`~django.apps.AppConfig` features without requiring your users to -update their :setting:`INSTALLED_APPS` setting. Besides this use case, it's -best to avoid using ``default_app_config`` and instead specify the app config -class in :setting:`INSTALLED_APPS` as described next. +contains ``'rock_n_roll'``. This allows you to make use of +:class:`~django.apps.AppConfig` features without requiring your users to update +their :setting:`INSTALLED_APPS` setting. Besides this use case, it's best to +avoid using ``default_app_config`` and instead specify the app config class in +:setting:`INSTALLED_APPS` as described next. Of course, you can also tell your users to put ``'rock_n_roll.apps.RockNRollConfig'`` in their :setting:`INSTALLED_APPS` diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index 515d75d91a..88b09b008d 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -325,8 +325,8 @@ Security The security checks do not make your site secure. They do not audit code, do intrusion detection, or do anything particularly complex. Rather, they help -perform an automated, low-hanging-fruit checklist. They help you remember the -simple things that improve your site's security. +perform an automated, low-hanging-fruit checklist, that can help you to improve +your site's security. Some of these checks may not be appropriate for your particular deployment configuration. For instance, if you do your HTTP to HTTPS redirection in a load diff --git a/docs/ref/class-based-views/mixins-date-based.txt b/docs/ref/class-based-views/mixins-date-based.txt index 31697226f9..471e222a6e 100644 --- a/docs/ref/class-based-views/mixins-date-based.txt +++ b/docs/ref/class-based-views/mixins-date-based.txt @@ -332,5 +332,5 @@ Date-based mixins return the list of years for which ``qs`` has entries. If ``date_type`` isn't provided, the result of :meth:`~BaseDateListView.get_date_list_period` is used. ``date_type`` - and ``ordering`` are simply passed to + and ``ordering`` are passed to :meth:`QuerySet.dates()<django.db.models.query.QuerySet.dates>`. diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt index 9cde8b9834..4b20e9498c 100644 --- a/docs/ref/class-based-views/mixins-editing.txt +++ b/docs/ref/class-based-views/mixins-editing.txt @@ -209,8 +209,8 @@ The following mixins are used to construct Django's editing views: .. method:: put(*args, **kwargs) - The ``PUT`` action is also handled and just passes all parameters - through to :meth:`post`. + The ``PUT`` action is also handled and passes all parameters through to + :meth:`post`. ``DeletionMixin`` diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt index 8f6fcb8d48..52d5d976db 100644 --- a/docs/ref/class-based-views/mixins-multiple-object.txt +++ b/docs/ref/class-based-views/mixins-multiple-object.txt @@ -136,8 +136,7 @@ Multiple object mixins .. method:: get_paginate_by(queryset) Returns the number of items to paginate by, or ``None`` for no - pagination. By default this simply returns the value of - :attr:`paginate_by`. + pagination. By default this returns the value of :attr:`paginate_by`. .. method:: get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True) @@ -147,7 +146,7 @@ Multiple object mixins .. method:: get_paginate_orphans() An integer specifying the number of "overflow" objects the last page - can contain. By default this simply returns the value of + can contain. By default this returns the value of :attr:`paginate_orphans`. .. method:: get_allow_empty() diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index d220737340..b865308491 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -12,7 +12,7 @@ Simple mixins .. attribute:: extra_context A dictionary to include in the context. This is a convenient way of - specifying some simple context in + specifying some context in :meth:`~django.views.generic.base.View.as_view`. Example usage:: from django.views.generic import TemplateView diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt index 2801b9964b..4fb33f6ce8 100644 --- a/docs/ref/class-based-views/mixins-single-object.txt +++ b/docs/ref/class-based-views/mixins-single-object.txt @@ -63,7 +63,7 @@ Single object mixins with access to individual objects should be prevented from obtaining this list, setting ``query_pk_and_slug`` to ``True`` will help prevent the guessing of URLs as each URL will require two correct, - non-sequential arguments. Simply using a unique slug may serve the same + non-sequential arguments. Using a unique slug may serve the same purpose, but this scheme allows you to have non-unique slugs. .. _insecure direct object reference: https://www.owasp.org/index.php/Top_10_2013-A4-Insecure_Direct_Object_References @@ -128,7 +128,7 @@ Single object mixins .. method:: get_slug_field() Returns the name of a slug field to be used to look up by slug. By - default this simply returns the value of :attr:`slug_field`. + default this returns the value of :attr:`slug_field`. ``SingleObjectTemplateResponseMixin`` diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index 6fba3eaea8..88b45fd63b 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -37,10 +37,9 @@ loading in a frame no matter which site made the request. .. _X-Frame-Options: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options -Django provides a few simple ways to include this header in responses from your -site: +Django provides a few ways to include this header in responses from your site: -#. A simple middleware that sets the header in all responses. +#. A middleware that sets the header in all responses. #. A set of view decorators that can be used to override the middleware or to only set the header for certain views. diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index 3956ecb93c..2cb6e8957c 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -9,7 +9,7 @@ then change it." This works well for a majority of use cases. However, if you need to make the same change to many objects at once, this workflow can be quite tedious. -In these cases, Django's admin lets you write and register "actions" -- simple +In these cases, Django's admin lets you write and register "actions" -- functions that get called with a list of objects selected on the change list page. @@ -43,7 +43,7 @@ Writing actions The easiest way to explain actions is by example, so let's dive in. A common use case for admin actions is the bulk updating of a model. Imagine a -simple news application with an ``Article`` model:: +news application with an ``Article`` model:: from django.db import models @@ -71,7 +71,7 @@ Writing action functions ------------------------ First, we'll need to write a function that gets called when the action is -triggered from the admin. Action functions are just regular functions that take +triggered from the admin. Action functions are regular functions that take three arguments: * The current :class:`ModelAdmin` @@ -89,7 +89,7 @@ request object, but we will use the queryset:: For the best performance, we're using the queryset's :ref:`update method <topics-db-queries-update>`. Other types of actions might need to deal - with each object individually; in these cases we'd just iterate over the + with each object individually; in these cases we'd iterate over the queryset:: for obj in queryset: @@ -138,7 +138,7 @@ That code will give us an admin change list that looks something like this: .. image:: _images/adding-actions-to-the-modeladmin.png That's really all there is to it! If you're itching to write your own actions, -you now know enough to get started. The rest of this document just covers more +you now know enough to get started. The rest of this document covers more advanced techniques. Handling errors in actions @@ -159,12 +159,12 @@ advanced options. Actions as :class:`ModelAdmin` methods -------------------------------------- -The example above shows the ``make_published`` action defined as a simple -function. That's perfectly fine, but it's not perfect from a code design point -of view: since the action is tightly coupled to the ``Article`` object, it -makes sense to hook the action to the ``ArticleAdmin`` object itself. +The example above shows the ``make_published`` action defined as a function. +That's perfectly fine, but it's not perfect from a code design point of view: +since the action is tightly coupled to the ``Article`` object, it makes sense +to hook the action to the ``ArticleAdmin`` object itself. -That's easy enough to do:: +You can do it like this:: class ArticleAdmin(admin.ModelAdmin): ... @@ -180,9 +180,9 @@ Notice first that we've moved ``make_published`` into a method and renamed the ``'make_published'`` in ``actions`` instead of a direct function reference. This tells the :class:`ModelAdmin` to look up the action as a method. -Defining actions as methods gives the action more straightforward, idiomatic -access to the :class:`ModelAdmin` itself, allowing the action to call any of the -methods provided by the admin. +Defining actions as methods gives the action more idiomatic access to the +:class:`ModelAdmin` itself, allowing the action to call any of the methods +provided by the admin. .. _custom-admin-action: @@ -208,17 +208,15 @@ performing an action: Actions that provide intermediate pages --------------------------------------- -By default, after an action is performed the user is simply redirected back -to the original change list page. However, some actions, especially more -complex ones, will need to return intermediate pages. For example, the -built-in delete action asks for confirmation before deleting the selected -objects. +By default, after an action is performed the user is redirected back to the +original change list page. However, some actions, especially more complex ones, +will need to return intermediate pages. For example, the built-in delete action +asks for confirmation before deleting the selected objects. -To provide an intermediary page, simply return an -:class:`~django.http.HttpResponse` (or subclass) from your action. For -example, you might write a simple export function that uses Django's -:doc:`serialization functions </topics/serialization>` to dump some selected -objects as JSON:: +To provide an intermediary page, return an :class:`~django.http.HttpResponse` +(or subclass) from your action. For example, you might write a export function +that uses Django's :doc:`serialization functions </topics/serialization>` to +dump some selected objects as JSON:: from django.core import serializers from django.http import HttpResponse @@ -236,7 +234,7 @@ This allows you to provide complex interaction logic on the intermediary pages. For example, if you wanted to provide a more complete export function, you'd want to let the user choose a format, and possibly a list of fields to include in the export. The best thing to do would be to write a small action -that simply redirects to your custom export view:: +that redirects to your custom export view:: from django.contrib import admin from django.contrib.contenttypes.models import ContentType @@ -247,9 +245,9 @@ that simply redirects to your custom export view:: ct = ContentType.objects.get_for_model(queryset.model) return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected))) -As you can see, the action is the simple part; all the complex logic would -belong in your export view. This would need to deal with objects of any type, -hence the business with the ``ContentType``. +As you can see, the action is rather short; all the complex logic would belong +in your export view. This would need to deal with objects of any type, hence +the business with the ``ContentType``. Writing this view is left as an exercise to the reader. @@ -303,8 +301,7 @@ Disabling a site-wide action site-wide. If, however, you need to re-enable a globally-disabled action for one - particular model, simply list it explicitly in your ``ModelAdmin.actions`` - list:: + particular model, list it explicitly in your ``ModelAdmin.actions`` list:: # Globally disable delete selected admin.site.disable_action('delete_selected') @@ -323,8 +320,8 @@ Disabling a site-wide action Disabling all actions for a particular :class:`ModelAdmin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you want *no* bulk actions available for a given :class:`ModelAdmin`, simply -set :attr:`ModelAdmin.actions` to ``None``:: +If you want *no* bulk actions available for a given :class:`ModelAdmin`, set +:attr:`ModelAdmin.actions` to ``None``:: class MyModelAdmin(admin.ModelAdmin): actions = None diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 45bf9f3b48..68221ede5e 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -83,8 +83,7 @@ Other topics The ``ModelAdmin`` class is the representation of a model in the admin interface. Usually, these are stored in a file named ``admin.py`` in your - application. Let's take a look at a very simple example of - the ``ModelAdmin``:: + application. Let's take a look at an example of the ``ModelAdmin``:: from django.contrib import admin from myproject.myapp.models import Author @@ -1195,8 +1194,8 @@ subclass:: A read-only field can not only display data from a model's field, it can also display the output of a model's method or a method of the ``ModelAdmin`` class itself. This is very similar to the way - :attr:`ModelAdmin.list_display` behaves. This provides an easy way to use - the admin interface to provide feedback on the status of the objects being + :attr:`ModelAdmin.list_display` behaves. This provides a way to use the + admin interface to provide feedback on the status of the objects being edited, for example:: from django.contrib import admin @@ -1742,7 +1741,7 @@ templates used by the :class:`ModelAdmin` views: kwargs['form'] = MySuperuserForm return super().get_form(request, obj, **kwargs) - You may also simply return a custom :class:`~django.forms.ModelForm` class + You may also return a custom :class:`~django.forms.ModelForm` class directly. .. method:: ModelAdmin.get_formsets_with_inlines(request, obj=None) @@ -2159,9 +2158,9 @@ return the uncompressed versions of the various JavaScript files, including Adding custom validation to the admin ------------------------------------- -Adding custom validation of data in the admin is quite easy. The automatic -admin interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives -you the ability define your own form:: +You can also add custom validation of data in the admin. The automatic admin +interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you +the ability define your own form:: class ArticleAdmin(admin.ModelAdmin): form = MyArticleAdminForm @@ -2535,8 +2534,7 @@ layout required for multiple widgets will vary depending on the intermediate model. However, we still want to be able to edit that information inline. Fortunately, -this is easy to do with inline admin models. Suppose we have the following -models:: +we can do this with inline admin models. Suppose we have the following models:: from django.db import models @@ -2560,7 +2558,7 @@ define an inline class for the ``Membership`` model:: model = Membership extra = 1 -This simple example uses the default ``InlineModelAdmin`` values for the +This example uses the default ``InlineModelAdmin`` values for the ``Membership`` model, and limits the extra add forms to one. This could be customized using any of the options available to ``InlineModelAdmin`` classes. @@ -2633,9 +2631,9 @@ specific information. Overriding admin templates ========================== -It is relatively easy to override many of the templates which the admin module -uses to generate the various pages of an admin site. You can even override a -few of these templates for a specific app, or a specific model. +You can override many of the templates which the admin module uses to generate +the various pages of an admin site. You can even override a few of these +templates for a specific app, or a specific model. Set up your projects admin template directories ----------------------------------------------- @@ -2732,7 +2730,7 @@ app or per model. The following can: * ``submit_line.html`` For those templates that cannot be overridden in this way, you may still -override them for your entire project. Just place the new version in your +override them for your entire project by placing the new version in your ``templates/admin`` directory. This is particularly useful to create custom 404 and 500 pages. @@ -2923,11 +2921,11 @@ Customizing the :class:`AdminSite` class ---------------------------------------- If you'd like to set up your own admin site with custom behavior, you're free -to subclass ``AdminSite`` and override or add anything you like. Then, simply -create an instance of your ``AdminSite`` subclass (the same way you'd -instantiate any other Python class) and register your models and -``ModelAdmin`` subclasses with it instead of with the default site. Finally, -update :file:`myproject/urls.py` to reference your :class:`AdminSite` subclass. +to subclass ``AdminSite`` and override or add anything you like. Then, create +an instance of your ``AdminSite`` subclass (the same way you'd instantiate any +other Python class) and register your models and ``ModelAdmin`` subclasses with +it instead of with the default site. Finally, update :file:`myproject/urls.py` +to reference your :class:`AdminSite` subclass. .. code-block:: python :caption: myapp/admin.py @@ -3000,9 +2998,9 @@ returns a site instance. Multiple admin sites in the same URLconf ---------------------------------------- -It's easy to create multiple instances of the admin site on the same -Django-powered website. Just create multiple instances of ``AdminSite`` and -root each one at a different URL. +You can create multiple instances of the admin site on the same Django-powered +website. Create multiple instances of ``AdminSite`` and place each one at a +different URL. In this example, the URLs ``/basic-admin/`` and ``/advanced-admin/`` feature separate versions of the admin site -- using the ``AdminSite`` instances diff --git a/docs/ref/contrib/admin/javascript.txt b/docs/ref/contrib/admin/javascript.txt index bf94655f38..089ef0e618 100644 --- a/docs/ref/contrib/admin/javascript.txt +++ b/docs/ref/contrib/admin/javascript.txt @@ -55,9 +55,9 @@ Two points to keep in mind: various operations in the change form and we need that to be rendered too. Sometimes you'll need to work with ``jQuery`` plugins that are not registered -in the ``django.jQuery`` namespace. To do that, simply change how the code -listens for events. Instead of wrapping the listener in the ``django.jQuery`` -namespace, just listen to the event triggered from there. For example: +in the ``django.jQuery`` namespace. To do that, change how the code listens for +events. Instead of wrapping the listener in the ``django.jQuery`` namespace, +listen to the event triggered from there. For example: .. code-block:: html+django diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 75202ebe4b..d967d24927 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -648,8 +648,8 @@ The following backends are available in :mod:`django.contrib.auth.backends`: .. method:: authenticate(request, remote_user) The username passed as ``remote_user`` is considered trusted. This - method simply returns the user object with the given username, creating - a new user object if :attr:`~RemoteUserBackend.create_unknown_user` is + method returns the user object with the given username, creating a new + user object if :attr:`~RemoteUserBackend.create_unknown_user` is ``True``. Returns ``None`` if :attr:`~RemoteUserBackend.create_unknown_user` is diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 70eefe5117..43502c2e2e 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -240,7 +240,7 @@ to go one step further and use :class:`~django.contrib.contenttypes.models.ContentType` to enable truly generic (sometimes called "polymorphic") relationships between models. -A simple example is a tagging system, which might look like this:: +For example, it could be used for a tagging system like so:: from django.contrib.contenttypes.fields import GenericForeignKey from django.contrib.contenttypes.models import ContentType @@ -438,7 +438,7 @@ it would be deleted at the same time. Unlike :class:`~django.db.models.ForeignKey`, :class:`~django.contrib.contenttypes.fields.GenericForeignKey` does not accept an :attr:`~django.db.models.ForeignKey.on_delete` argument to customize this -behavior; if desired, you can avoid the cascade-deletion simply by not using +behavior; if desired, you can avoid the cascade-deletion by not using :class:`~django.contrib.contenttypes.fields.GenericRelation`, and alternate behavior can be provided via the :data:`~django.db.models.signals.pre_delete` signal. diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 61ff6dceb1..83cab038e4 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -5,14 +5,14 @@ The flatpages app .. module:: django.contrib.flatpages :synopsis: A framework for managing simple ?flat? HTML content in a database. -Django comes with an optional "flatpages" application. It lets you store simple -"flat" HTML content in a database and handles the management for you via -Django's admin interface and a Python API. +Django comes with an optional "flatpages" application. It lets you store "flat" +HTML content in a database and handles the management for you via Django's +admin interface and a Python API. -A flatpage is a simple object with a URL, title and content. Use it for -one-off, special-case pages, such as "About" or "Privacy Policy" pages, that -you want to store in a database but for which you don't want to develop a -custom Django application. +A flatpage is a object with a URL, title and content. Use it for one-off, +special-case pages, such as "About" or "Privacy Policy" pages, that you want to +store in a database but for which you don't want to develop a custom Django +application. A flatpage can use a custom template or a default, systemwide flatpage template. It can be associated with one, or multiple, sites. @@ -58,9 +58,9 @@ How it works ============ ``manage.py migrate`` creates two tables in your database: ``django_flatpage`` -and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table -that simply maps a URL to a title and bunch of text content. -``django_flatpage_sites`` associates a flatpage with a site. +and ``django_flatpage_sites``. ``django_flatpage`` is a lookup table that maps +a URL to a title and bunch of text content. ``django_flatpage_sites`` +associates a flatpage with a site. Using the URLconf ----------------- @@ -229,12 +229,12 @@ By default, flatpages are rendered via the template particular flatpage: in the admin, a collapsed fieldset titled "Advanced options" (clicking will expand it) contains a field for specifying a template name. If you're creating a flat page via the -Python API you can simply set the template name as the field -``template_name`` on the ``FlatPage`` object. +Python API you can set the template name as the field ``template_name`` on the +``FlatPage`` object. Creating the :file:`flatpages/default.html` template is your responsibility; -in your template directory, just create a :file:`flatpages` directory -containing a file :file:`default.html`. +in your template directory, create a :file:`flatpages` directory containing a +file :file:`default.html`. Flatpage templates are passed a single context variable, ``flatpage``, which is the flatpage object. diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index 14c0d9522f..857f2e0de1 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -284,10 +284,10 @@ Then distance queries may be performed as follows:: >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20))) >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100))) -Raster queries work the same way by simply replacing the geometry field -``point`` with a raster field, or the ``pnt`` object with a raster object, or -both. To specify the band index of a raster input on the right hand side, a -3-tuple can be passed to the lookup as follows:: +Raster queries work the same way by replacing the geometry field ``point`` with +a raster field, or the ``pnt`` object with a raster object, or both. To specify +the band index of a raster input on the right hand side, a 3-tuple can be +passed to the lookup as follows:: >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(rst, 2, D(km=7))) diff --git a/docs/ref/contrib/gis/forms-api.txt b/docs/ref/contrib/gis/forms-api.txt index 1320815ad6..daa46716ad 100644 --- a/docs/ref/contrib/gis/forms-api.txt +++ b/docs/ref/contrib/gis/forms-api.txt @@ -88,7 +88,7 @@ Form widgets GeoDjango form widgets allow you to display and edit geographic data on a visual map. Note that none of the currently available widgets supports 3D geometries, hence -geometry fields will fallback using a simple ``Textarea`` widget for such data. +geometry fields will fallback using a ``Textarea`` widget for such data. Widget attributes ----------------- diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index 99dcb54341..879ed855f6 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/docs/ref/contrib/gis/gdal.txt @@ -36,7 +36,7 @@ The GDAL/OGR tools described here are designed to help you read in your geospatial data, in order for most of them to be useful you have to have some data to work with. If you're starting out and don't yet have any data of your own to use, GeoDjango tests contain a number of -simple data sets that you can use for testing. You can download them here:: +data sets that you can use for testing. You can download them here:: $ wget https://raw.githubusercontent.com/django/django/master/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf} $ wget https://raw.githubusercontent.com/django/django/master/tests/gis_tests/data/rasters/raster.tif @@ -49,7 +49,7 @@ Vector Data Source Objects :class:`DataSource` is a wrapper for the OGR data source object that supports reading data from a variety of OGR-supported geospatial file -formats and data sources using a simple, consistent interface. Each +formats and data sources using a consistent interface. Each data source is represented by a :class:`DataSource` object which contains one or more layers of data. Each layer, represented by a :class:`Layer` object, contains some number of geographic features (:class:`Feature`), @@ -1085,7 +1085,7 @@ Raster Data Objects :class:`GDALRaster` is a wrapper for the GDAL raster source object that supports reading data from a variety of GDAL-supported geospatial file -formats and data sources using a simple, consistent interface. Each +formats and data sources using a consistent interface. Each data source is represented by a :class:`GDALRaster` object which contains one or more layers of data named bands. Each band, represented by a :class:`GDALBand` object, contains georeferenced image data. For example, an RGB diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index 1211c2c173..ff9dccaa4d 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -887,8 +887,8 @@ SpatiaLite Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry column. This is analogous to a simplified version of the :class:`Union` aggregate, except it can be several orders of magnitude faster than performing -a union because it simply rolls up geometries into a collection or multi object, -not caring about dissolving boundaries. +a union because it rolls up geometries into a collection or multi object, not +caring about dissolving boundaries. ``Extent`` ~~~~~~~~~~ diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index 068fe7d006..fda1b5cc3d 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -833,7 +833,7 @@ Geometry Collections Prepared Geometries =================== -In order to obtain a prepared geometry, just access the +In order to obtain a prepared geometry, access the :attr:`GEOSGeometry.prepared` property. Once you have a ``PreparedGeometry`` instance its spatial predicate methods, listed below, may be used with other ``GEOSGeometry`` objects. An operation with a prepared @@ -911,8 +911,8 @@ I/O Objects Reader Objects -------------- -The reader I/O classes simply return a :class:`GEOSGeometry` instance from the -WKB and/or WKT input given to their ``read(geom)`` method. +The reader I/O classes return a :class:`GEOSGeometry` instance from the WKB +and/or WKT input given to their ``read(geom)`` method. .. class:: WKBReader diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index 8a9ea2485f..0454124887 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -39,7 +39,7 @@ totally fine with GeoDjango. Your mileage may vary. The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used independently of Django. In other words, no database or settings file - required -- just import them as normal from :mod:`django.contrib.gis`. + required -- import them as normal from :mod:`django.contrib.gis`. .. _PROJ.4: https://github.com/OSGeo/proj.4/wiki/ __ https://postgis.net/ diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index 26019c98ab..b6621f518c 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -272,9 +272,9 @@ KyngChaos packages ~~~~~~~~~~~~~~~~~~ William Kyngesburye provides a number of `geospatial library binary packages`__ -that make it simple to get GeoDjango installed on macOS without compiling -them from source. However, `Xcode`_ is still necessary for compiling the -Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS). +that help to get GeoDjango installed on macOS without compiling them from +source. However, `Xcode`_ is still necessary for compiling the Python database +adapters :ref:`psycopg2_kyngchaos` (for PostGIS). .. note:: @@ -385,9 +385,9 @@ PostgreSQL ~~~~~~~~~~ First, download the latest `PostgreSQL 9.x installer`__ from the -`EnterpriseDB`__ website. After downloading, simply run the installer, -follow the on-screen directions, and keep the default options unless -you know the consequences of changing them. +`EnterpriseDB`__ website. After downloading, run the installer, follow the +on-screen directions, and keep the default options unless you know the +consequences of changing them. .. note:: @@ -446,14 +446,13 @@ __ http://www.stickpeople.com/projects/python/win-psycopg/ OSGeo4W ~~~~~~~ -The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS -libraries required by GeoDjango. First, download the `OSGeo4W installer`_, -and run it. Select :menuselection:`Express Web-GIS Install` and click next. -In the 'Select Packages' list, ensure that GDAL is selected; MapServer and -Apache are also enabled by default, but are not required by GeoDjango and -may be unchecked safely. After clicking next, the packages will be -automatically downloaded and installed, after which you may exit the -installer. +The `OSGeo4W installer`_ helps to install the PROJ.4, GDAL, and GEOS libraries +required by GeoDjango. First, download the `OSGeo4W installer`_, and run it. +Select :menuselection:`Express Web-GIS Install` and click next. In the 'Select +Packages' list, ensure that GDAL is selected; MapServer and Apache are also +enabled by default, but are not required by GeoDjango and may be unchecked +safely. After clicking next, the packages will be automatically downloaded and +installed, after which you may exit the installer. .. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/ diff --git a/docs/ref/contrib/gis/install/spatialite.txt b/docs/ref/contrib/gis/install/spatialite.txt index 494a2caff7..9386168ce3 100644 --- a/docs/ref/contrib/gis/install/spatialite.txt +++ b/docs/ref/contrib/gis/install/spatialite.txt @@ -38,7 +38,7 @@ command line interface and enter the following query:: sqlite> CREATE VIRTUAL TABLE testrtree USING rtree(id,minX,maxX,minY,maxY); If you obtain an error, you will have to recompile SQLite from source. Otherwise, -just skip this section. +skip this section. To install from sources, download the latest amalgamation source archive from the `SQLite download page`__, and extract:: diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index 8aef4a1614..9d9fee988f 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -25,8 +25,8 @@ then inserting into a GeoDjango model. that :class:`LayerMapping` is using too much memory, set :setting:`DEBUG` to ``False`` in your settings. When :setting:`DEBUG` is set to ``True``, Django :ref:`automatically logs <faq-see-raw-sql-queries>` - *every* SQL query -- thus, when SQL statements contain geometries, it is - easy to consume more memory than is typical. + *every* SQL query -- and when SQL statements contain geometries, this may + consume more memory than is typical. Example ======= @@ -75,10 +75,10 @@ Example Saved: Name: 2 Saved: Name: 3 -Here, :class:`LayerMapping` just transformed the three geometries from the -shapefile in their original spatial reference system (WGS84) to the spatial -reference system of the GeoDjango model (NAD83). If no spatial reference -system is defined for the layer, use the ``source_srs`` keyword with a +Here, :class:`LayerMapping` transformed the three geometries from the shapefile +in their original spatial reference system (WGS84) to the spatial reference +system of the GeoDjango model (NAD83). If no spatial reference system is +defined for the layer, use the ``source_srs`` keyword with a :class:`~django.contrib.gis.gdal.SpatialReference` object to specify one. ``LayerMapping`` API diff --git a/docs/ref/contrib/gis/measure.txt b/docs/ref/contrib/gis/measure.txt index ddf091e05d..f7b13c1b81 100644 --- a/docs/ref/contrib/gis/measure.txt +++ b/docs/ref/contrib/gis/measure.txt @@ -26,8 +26,8 @@ instantiated in units of kilometers (``km``) and miles (``mi``):: >>> print(d2) 5.0 mi -Conversions are easy, just access the preferred unit attribute to get a -converted distance quantity:: +For conversions, access the preferred unit attribute to get a converted +distance quantity:: >>> print(d1.mi) # Converting 5 kilometers to miles 3.10685596119 diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index 6e8ae89665..d77971bb5a 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -73,8 +73,8 @@ is done from an existing superuser account):: Windows ------- -On Windows platforms the pgAdmin III utility may also be used as -a simple way to add superuser privileges to your database user. +On Windows platforms you can use the pgAdmin III utility to add superuser +privileges to your database user. By default, the PostGIS installer on Windows includes a template spatial database entitled ``template_postgis``. diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 299fb36082..8fd8d60b62 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -758,8 +758,8 @@ available with the :class:`~django.contrib.gis.admin.GeoModelAdmin` The PROJ.4 datum shifting files must be installed (see the :ref:`PROJ.4 installation instructions <proj4>` for more details). -If you meet this requirement, then just substitute the ``OSMGeoAdmin`` -option class in your ``admin.py`` file:: +If you meet this requirement, then substitute the ``OSMGeoAdmin`` option class +in your ``admin.py`` file:: admin.site.register(WorldBorder, admin.OSMGeoAdmin) diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index 3ae8c4af05..1890b35cf6 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -61,7 +61,7 @@ See the :doc:`contenttypes documentation </ref/contrib/contenttypes>`. ``flatpages`` ============= -A framework for managing simple "flat" HTML content in a database. +A framework for managing "flat" HTML content in a database. See the :doc:`flatpages documentation </ref/contrib/flatpages>`. diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 3343707d69..2f05ce7370 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -194,9 +194,9 @@ If you're using the context processor, your template should be rendered with a ``RequestContext``. Otherwise, ensure ``messages`` is available to the template context. -Even if you know there is only just one message, you should still iterate over -the ``messages`` sequence, because otherwise the message storage will not be cleared -for the next request. +Even if you know there is only one message, you should still iterate over the +``messages`` sequence, because otherwise the message storage will not be +cleared for the next request. The context processor also provides a ``DEFAULT_MESSAGE_LEVELS`` variable which is a mapping of the message level names to their numeric value:: @@ -235,8 +235,7 @@ The ``Message`` class .. class:: storage.base.Message When you loop over the list of messages in a template, what you get are - instances of the ``Message`` class. It's quite a simple object, with only a - few attributes: + instances of the ``Message`` class. They have only a few attributes: * ``message``: The actual text of the message. diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index 150187b0bc..5ae5a2e2ce 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -24,7 +24,7 @@ may be a good choice for the :ref:`range fields <range-fields>` and .. class:: ArrayField(base_field, size=None, **options) - A field for storing lists of data. Most field types can be used, you simply + A field for storing lists of data. Most field types can be used, and you pass another field instance as the :attr:`base_field <ArrayField.base_field>`. You may also specify a :attr:`size <ArrayField.size>`. ``ArrayField`` can be nested to store multi-dimensional @@ -333,7 +333,7 @@ We will use the following example model:: Key lookups ~~~~~~~~~~~ -To query based on a given key, you simply use that key as the lookup name:: +To query based on a given key, you can use that key as the lookup name:: >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie'}) @@ -537,8 +537,7 @@ We will use the following example model:: Key, index, and path lookups ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To query based on a given dictionary key, simply use that key as the lookup -name:: +To query based on a given dictionary key, use that key as the lookup name:: >>> Dog.objects.create(name='Rufus', data={ ... 'breed': 'labrador', diff --git a/docs/ref/contrib/postgres/forms.txt b/docs/ref/contrib/postgres/forms.txt index b5effb520c..bb78e5bc05 100644 --- a/docs/ref/contrib/postgres/forms.txt +++ b/docs/ref/contrib/postgres/forms.txt @@ -15,8 +15,7 @@ Fields .. class:: SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None) - A simple field which maps to an array. It is represented by an HTML - ``<input>``. + A field which maps to an array. It is represented by an HTML ``<input>``. .. attribute:: base_field diff --git a/docs/ref/contrib/postgres/search.txt b/docs/ref/contrib/postgres/search.txt index 026336960e..367171d128 100644 --- a/docs/ref/contrib/postgres/search.txt +++ b/docs/ref/contrib/postgres/search.txt @@ -21,7 +21,7 @@ The ``search`` lookup .. fieldlookup:: search -The simplest way to use full text search is to search a single term against a +A common way to use full text search is to search a single term against a single column in the database. For example:: >>> Entry.objects.filter(body_text__search='Cheese') @@ -111,9 +111,9 @@ See :ref:`postgresql-fts-search-configuration` for an explanation of the .. class:: SearchRank(vector, query, weights=None) -So far, we've just returned the results for which any match between the vector -and the query are possible. It's likely you may wish to order the results by -some sort of relevancy. PostgreSQL provides a ranking function which takes into +So far, we've returned the results for which any match between the vector and +the query are possible. It's likely you may wish to order the results by some +sort of relevancy. PostgreSQL provides a ranking function which takes into account how often the query terms appear in the document, how close together the terms are in the document, and how important the part of the document is where they occur. The better the match, the higher the value of the rank. To diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index a37aee8711..6fa5fc51eb 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -5,7 +5,7 @@ The redirects app .. module:: django.contrib.redirects :synopsis: A framework for managing redirects. -Django comes with an optional redirects application. It lets you store simple +Django comes with an optional redirects application. It lets you store redirects in a database and handles the redirecting for you. It uses the HTTP response status code ``301 Moved Permanently`` by default. @@ -25,7 +25,7 @@ How it works ============ ``manage.py migrate`` creates a ``django_redirect`` table in your database. This -is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields. +is a lookup table with ``site_id``, ``old_path`` and ``new_path`` fields. The :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` does all of the work. Each time any Django application raises a 404 diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 166013659d..0dc4d48bd5 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -5,8 +5,8 @@ The sitemap framework .. module:: django.contrib.sitemaps :synopsis: A framework for generating Google sitemap XML files. -Django comes with a high-level sitemap-generating framework that makes -creating sitemap_ XML files easy. +Django comes with a high-level sitemap-generating framework to create sitemap_ +XML files. .. _sitemap: https://www.sitemaps.org/ @@ -22,7 +22,7 @@ The Django sitemap framework automates the creation of this XML file by letting you express this information in Python code. It works much like Django's :doc:`syndication framework -</ref/contrib/syndication>`. To create a sitemap, just write a +</ref/contrib/syndication>`. To create a sitemap, write a :class:`~django.contrib.sitemaps.Sitemap` class and point to it in your :doc:`URLconf </topics/http/urls>`. @@ -76,11 +76,11 @@ a :class:`~django.contrib.sitemaps.Sitemap` class (e.g., ``Sitemap`` classes =================== -A :class:`~django.contrib.sitemaps.Sitemap` class is a simple Python -class that represents a "section" of entries in your sitemap. For example, -one :class:`~django.contrib.sitemaps.Sitemap` class could represent -all the entries of your Weblog, while another could represent all of the -events in your events calendar. +A :class:`~django.contrib.sitemaps.Sitemap` class is a Python class that +represents a "section" of entries in your sitemap. For example, one +:class:`~django.contrib.sitemaps.Sitemap` class could represent all the entries +of your Weblog, while another could represent all of the events in your events +calendar. In the simplest case, all these sections get lumped together into one :file:`sitemap.xml`, but it's also possible to use the framework to generate a @@ -90,8 +90,8 @@ sitemap index that references individual sitemap files, one per section. (See :class:`~django.contrib.sitemaps.Sitemap` classes must subclass ``django.contrib.sitemaps.Sitemap``. They can live anywhere in your codebase. -A simple example -================ +An example +========== Let's assume you have a blog system, with an ``Entry`` model, and you want your sitemap to include all the links to your individual blog entries. Here's how @@ -116,11 +116,10 @@ Note: attributes corresponding to ``<changefreq>`` and ``<priority>`` elements, respectively. They can be made callable as functions, as :attr:`~Sitemap.lastmod` was in the example. -* :attr:`~Sitemap.items()` is simply a method that returns a list of - objects. The objects returned will get passed to any callable methods - corresponding to a sitemap property (:attr:`~Sitemap.location`, - :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and - :attr:`~Sitemap.priority`). +* :attr:`~Sitemap.items()` is a method that returns a list of objects. The + objects returned will get passed to any callable methods corresponding to a + sitemap property (:attr:`~Sitemap.location`, :attr:`~Sitemap.lastmod`, + :attr:`~Sitemap.changefreq`, and :attr:`~Sitemap.priority`). * :attr:`~Sitemap.lastmod` should return a :class:`~datetime.datetime`. * There is no :attr:`~Sitemap.location` method in this example, but you can provide it in order to specify the URL for your object. By default, diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 0a808f23a9..ee2ea15ef2 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -13,7 +13,7 @@ the domain names and "verbose" names of your Django-powered sites. Use it if your single Django installation powers more than one site and you need to differentiate between those sites in some way. -The sites framework is mainly based on a simple model: +The sites framework is mainly based on this model: .. class:: models.Site @@ -37,7 +37,7 @@ try to get the current site by comparing the the :meth:`request.get_host() <django.http.HttpRequest.get_host>` method. How you use this is up to you, but Django uses it in a couple of ways -automatically via simple conventions. +automatically via a couple of conventions. Example usage ============= @@ -58,10 +58,10 @@ publish the same story twice: once for LJWorld.com and again for Lawrence.com. But that's inefficient for site producers, and it's redundant to store multiple copies of the same story in the database. -The better solution is simple: Both sites use the same article database, and an -article is associated with one or more sites. In Django model terminology, -that's represented by a :class:`~django.db.models.ManyToManyField` in the -``Article`` model:: +A better solution removes the content duplication: Both sites use the same +article database, and an article is associated with one or more sites. In +Django model terminology, that's represented by a +:class:`~django.db.models.ManyToManyField` in the ``Article`` model:: from django.contrib.sites.models import Site from django.db import models @@ -80,8 +80,8 @@ This accomplishes several things quite nicely: database; it only has a single record in the database. * It lets the site developers use the same Django view code for both sites. - The view code that displays a given story just checks to make sure the - requested story is on the current site. It looks something like this:: + The view code that displays a given story checks to make sure the requested + story is on the current site. It looks something like this:: from django.contrib.sites.shortcuts import get_current_site @@ -215,7 +215,7 @@ subscribing to LJWorld.com alerts." Same goes for the email's message body. Note that an even more flexible (but more heavyweight) way of doing this would be to use Django's template system. Assuming Lawrence.com and LJWorld.com have different template directories (:setting:`DIRS <TEMPLATES-DIRS>`), you could -simply farm out to the template system like so:: +farm out to the template system like so:: from django.core.mail import send_mail from django.template import Context, loader @@ -243,7 +243,7 @@ Getting the current domain for full URLs Django's ``get_absolute_url()`` convention is nice for getting your objects' URL without the domain name, but in some cases you might want to display the full URL -- with ``http://`` and the domain and everything -- for an object. -To do this, you can use the sites framework. A simple example:: +To do this, you can use the sites framework. An example:: >>> from django.contrib.sites.models import Site >>> obj = MyModel.objects.get(id=3) @@ -401,7 +401,7 @@ If you often use this pattern:: site = Site.objects.get_current() ... -there is simple way to avoid repetitions. Add +To avoid repetitions, add :class:`django.contrib.sites.middleware.CurrentSiteMiddleware` to :setting:`MIDDLEWARE`. The middleware sets the ``site`` attribute on every request object, so you can use ``request.site`` to get the current site. diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 9da8f6eb4e..6fb6f55a0b 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -387,7 +387,7 @@ hashed names of processed files instead of a static manifest file called have access to the file system. If you want to override certain options of the cache backend the storage uses, -simply specify a custom entry in the :setting:`CACHES` setting named +specify a custom entry in the :setting:`CACHES` setting named ``'staticfiles'``. It falls back to using the ``'default'`` cache backend. .. warning:: diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index aedf942a4d..ad41ebd68e 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -6,8 +6,8 @@ The syndication feed framework :synopsis: A framework for generating syndication feeds, in RSS and Atom, quite easily. -Django comes with a high-level syndication-feed-generating framework -that makes creating RSS_ and Atom_ feeds easy. +Django comes with a high-level syndication-feed-generating framework for +creating RSS_ and Atom_ feeds. To create any syndication feed, all you have to do is write a short Python class. You can create as many feeds as you want. @@ -94,13 +94,12 @@ Note: standard RSS ``<title>``, ``<link>`` and ``<description>`` elements, respectively. -* ``items()`` is, simply, a method that returns a list of objects that - should be included in the feed as ``<item>`` elements. Although this - example returns ``NewsItem`` objects using Django's - :doc:`object-relational mapper </ref/models/querysets>`, ``items()`` - doesn't have to return model instances. Although you get a few bits of - functionality "for free" by using Django models, ``items()`` can - return any type of object you want. +* ``items()`` is, a method that returns a list of objects that should be + included in the feed as ``<item>`` elements. Although this example returns + ``NewsItem`` objects using Django's :doc:`object-relational mapper + </ref/models/querysets>`, ``items()`` doesn't have to return model instances. + Although you get a few bits of functionality "for free" by using Django + models, ``items()`` can return any type of object you want. * If you're creating an Atom feed, rather than an RSS feed, set the ``subtitle`` attribute instead of the ``description`` attribute. @@ -246,7 +245,7 @@ Here's the code for these beat-specific feeds:: To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django uses the ``title()``, ``link()`` and ``description()`` methods. In -the previous example, they were simple string class attributes, but this example +the previous example, they were string class attributes, but this example illustrates that they can be either strings *or* methods. For each of ``title``, ``link`` and ``description``, Django follows this algorithm: @@ -262,7 +261,8 @@ Also note that ``items()`` also follows the same algorithm -- first, it tries ``items(obj)``, then ``items()``, then finally an ``items`` class attribute (which should be a list). -We are using a template for the item descriptions. It can be very simple: +We are using a template for the item descriptions. It can be as minimal as +this: .. code-block:: html+django @@ -333,10 +333,9 @@ Publishing Atom and RSS feeds in tandem --------------------------------------- Some developers like to make available both Atom *and* RSS versions of their -feeds. That's easy to do with Django: Just create a subclass of your -:class:`~django.contrib.syndication.views.Feed` -class and set the ``feed_type`` to something different. Then update your -URLconf to add the extra versions. +feeds. To do that, you can create a subclass of your +:class:`~django.contrib.syndication.views.Feed` class and set the ``feed_type`` +to something different. Then update your URLconf to add the extra versions. Here's a full example:: @@ -367,8 +366,8 @@ Here's a full example:: subtitle and description are not necessarily the same thing. Instead, you should define a ``subtitle`` attribute. - In the above example, we simply set the Atom feed's ``subtitle`` to the - RSS feed's ``description``, because it's quite short already. + In the above example, we set the Atom feed's ``subtitle`` to the RSS feed's + ``description``, because it's quite short already. And the accompanying URLconf:: @@ -1073,5 +1072,5 @@ For example, you might start implementing an iTunes RSS feed generator like so:: super().add_root_elements(handler) handler.addQuickElement('itunes:explicit', 'clean') -Obviously there's a lot more work to be done for a complete custom feed class, -but the above example should demonstrate the basic idea. +There's a lot more work to be done for a complete custom feed class, but the +above example should demonstrate the basic idea. diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt index e961d76a02..e2f9d30703 100644 --- a/docs/ref/csrf.txt +++ b/docs/ref/csrf.txt @@ -80,7 +80,7 @@ set if you've enabled CSRF protection for your views as outlined above. The CSRF token cookie is named ``csrftoken`` by default, but you can control the cookie name via the :setting:`CSRF_COOKIE_NAME` setting. -Acquiring the token is straightforward: +You can acquire the token like this: .. code-block:: javascript @@ -227,7 +227,7 @@ when, due to a programming error, the CSRF token has not been included with a POST form. The error page, however, is not very friendly, so you may want to provide your -own view for handling this condition. To do this, simply set the +own view for handling this condition. To do this, set the :setting:`CSRF_FAILURE_VIEW` setting. CSRF failures are logged as warnings to the :ref:`django.security.csrf diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 3109146136..d5f30d6c9e 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -710,8 +710,8 @@ If you're getting this error, you can solve it by: # ... } - This will simply make SQLite wait a bit longer before throwing "database - is locked" errors; it won't really do anything to solve them. + This will make SQLite wait a bit longer before throwing "database is locked" + errors; it won't really do anything to solve them. ``QuerySet.select_for_update()`` not supported ---------------------------------------------- diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index b38740669f..eaba4d437d 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -213,7 +213,7 @@ specified in your :setting:`USER`, :setting:`PASSWORD`, etc., settings. * For SQLite, this runs the ``sqlite3`` command-line client. * For Oracle, this runs the ``sqlplus`` command-line client. -This command assumes the programs are on your ``PATH`` so that a simple call to +This command assumes the programs are on your ``PATH`` so that a call to the program name (``psql``, ``mysql``, ``sqlite3``, ``sqlplus``) will find the program in the right place. There's no way to specify the location of the program manually. @@ -400,7 +400,7 @@ By default, ``inspectdb`` creates unmanaged models. That is, ``managed = False`` in the model's ``Meta`` class tells Django not to manage each table's creation, modification, and deletion. If you do want to allow Django to manage the table's lifecycle, you'll need to change the -:attr:`~django.db.models.Options.managed` option to ``True`` (or simply remove +:attr:`~django.db.models.Options.managed` option to ``True`` (or remove it because ``True`` is its default value). Database-specific notes @@ -537,7 +537,7 @@ raise an exception:: post_save.connect(my_handler, sender=MyModel) -You could also write a simple decorator to encapsulate this logic:: +You could also write a decorator to encapsulate this logic:: from functools import wraps @@ -917,7 +917,7 @@ project for some common errors (see the :djadmin:`check` command). If any errors are found, they will be printed to standard output. You can run as many concurrent servers as you want, as long as they're on -separate ports. Just execute ``django-admin runserver`` more than once. +separate ports by executing ``django-admin runserver`` more than once. Note that the default IP address, ``127.0.0.1``, is not accessible from other machines on your network. To make your development server viewable to other @@ -1729,7 +1729,7 @@ Example usage:: .. django-admin-option:: --traceback Displays a full stack trace when a :exc:`~django.core.management.CommandError` -is raised. By default, ``django-admin`` will show a simple error message when a +is raised. By default, ``django-admin`` will show an error message when a ``CommandError`` occurs and a full stack trace for any other exception. Example usage:: diff --git a/docs/ref/files/uploads.txt b/docs/ref/files/uploads.txt index f67d9c9631..4b58d2a4e2 100644 --- a/docs/ref/files/uploads.txt +++ b/docs/ref/files/uploads.txt @@ -12,8 +12,8 @@ Uploaded files During file uploads, the actual file data is stored in :attr:`request.FILES <django.http.HttpRequest.FILES>`. Each entry in this dictionary is an -``UploadedFile`` object (or a subclass) -- a simple wrapper around an uploaded -file. You'll usually use one of these methods to access the uploaded content: +``UploadedFile`` object (or a subclass) -- a wrapper around an uploaded file. +You'll usually use one of these methods to access the uploaded content: .. method:: UploadedFile.read() @@ -33,9 +33,9 @@ file. You'll usually use one of these methods to access the uploaded content: A generator returning chunks of the file. If ``multiple_chunks()`` is ``True``, you should use this method in a loop instead of ``read()``. - In practice, it's often easiest simply to use ``chunks()`` all the time. - Looping over ``chunks()`` instead of using ``read()`` ensures that large - files don't overwhelm your system's memory. + In practice, it's often easiest to use ``chunks()`` all the time. Looping + over ``chunks()`` instead of using ``read()`` ensures that large files + don't overwhelm your system's memory. Here are some useful attributes of ``UploadedFile``: @@ -72,8 +72,8 @@ Here are some useful attributes of ``UploadedFile``: .. note:: - Like regular Python files, you can read the file line-by-line simply by - iterating over the uploaded file: + Like regular Python files, you can read the file line-by-line by iterating + over the uploaded file: .. code-block:: python diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 70f455fefe..23fbab9aff 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -25,7 +25,7 @@ A :class:`Form` instance is either **bound** to a set of data, or **unbound**. .. class:: Form -To create an unbound :class:`Form` instance, simply instantiate the class:: +To create an unbound :class:`Form` instance, instantiate the class:: >>> f = ContactForm() @@ -158,8 +158,9 @@ By default, ``as_json()`` does not escape its output. If you are using it for something like AJAX requests to a form view where the client interprets the response and inserts errors into the page, you'll want to be sure to escape the results on the client-side to avoid the possibility of a cross-site scripting -attack. It's trivial to do so using a JavaScript library like jQuery - simply -use ``$(el).text(errorText)`` rather than ``.html()``. +attack. You can do this in JavaScript with ``element.textContent = errorText`` +or with jQuery's ``$(el).text(errorText)`` (rather than its ``.html()`` +function). If for some reason you don't want to use client-side escaping, you can also set ``escape_html=True`` and error messages will be escaped so you can use them @@ -185,7 +186,7 @@ should be added. If its value is ``None`` the error will be treated as a non-field error as returned by :meth:`Form.non_field_errors() <django.forms.Form.non_field_errors>`. -The ``error`` argument can be a simple string, or preferably an instance of +The ``error`` argument can be a string, or preferably an instance of ``ValidationError``. See :ref:`raising-validation-error` for best practices when defining form errors. @@ -434,7 +435,7 @@ Outputting forms as HTML ======================== The second task of a ``Form`` object is to render itself as HTML. To do so, -simply ``print`` it:: +``print`` it:: >>> f = ContactForm() >>> print(f) @@ -563,7 +564,7 @@ errors. For example, you might want to present required form rows in bold and highlight errors in red. The :class:`Form` class has a couple of hooks you can use to add ``class`` -attributes to required rows or to rows with errors: simply set the +attributes to required rows or to rows with errors: set the :attr:`Form.error_css_class` and/or :attr:`Form.required_css_class` attributes:: @@ -634,7 +635,7 @@ tags nor ``id`` attributes:: <p>Cc myself: <input type="checkbox" name="cc_myself"></p> If ``auto_id`` is set to ``True``, then the form output *will* include -``<label>`` tags and will simply use the field name as its ``id`` for each form +``<label>`` tags and will use the field name as its ``id`` for each form field:: >>> f = ContactForm(auto_id=True) @@ -750,7 +751,7 @@ In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are displayed in the order in which you define them in your form class. For example, in the ``ContactForm`` example, the fields are defined in the order ``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML -output, just change the order in which those fields are listed in the class. +output, change the order in which those fields are listed in the class. There are several other ways to customize the order: @@ -833,7 +834,7 @@ pass that in at construction time:: More granular output ==================== -The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts -- +The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are shortcuts -- they're not the only way a form object can be displayed. .. class:: BoundField @@ -1121,8 +1122,8 @@ form data):: # Bound form with an image field, data from the request >>> f = ContactFormWithMugshot(request.POST, request.FILES) -Constructing an unbound form is the same as always -- just omit both -form data *and* file data:: +Constructing an unbound form is the same as always -- omit both form data *and* +file data:: # Unbound form with an image field >>> f = ContactFormWithMugshot() diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index aa13d4f021..82d42e2ab9 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -1239,12 +1239,11 @@ method:: Creating custom fields ====================== -If the built-in ``Field`` classes don't meet your needs, you can easily create -custom ``Field`` classes. To do this, just create a subclass of -``django.forms.Field``. Its only requirements are that it implement a -``clean()`` method and that its ``__init__()`` method accept the core arguments -mentioned above (``required``, ``label``, ``initial``, ``widget``, -``help_text``). +If the built-in ``Field`` classes don't meet your needs, you can create custom +``Field`` classes. To do this, create a subclass of ``django.forms.Field``. Its +only requirements are that it implement a ``clean()`` method and that its +``__init__()`` method accept the core arguments mentioned above (``required``, +``label``, ``initial``, ``widget``, ``help_text``). You can also customize how a field will be accessed by overriding :meth:`~django.forms.Field.get_bound_field()`. diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 72af31d907..188ccca736 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -19,10 +19,10 @@ for the best practice in raising ``ValidationError``. If no ``ValidationError`` is raised, the method should return the cleaned (normalized) data as a Python object. -Most validation can be done using `validators`_ - simple helpers that can be -reused easily. Validators are simple functions (or callables) that take a single -argument and raise ``ValidationError`` on invalid input. Validators are run -after the field's ``to_python`` and ``validate`` methods have been called. +Most validation can be done using `validators`_ - helpers that can be reused. +Validators are functions (or callables) that take a single argument and raise +``ValidationError`` on invalid input. Validators are run after the field's +``to_python`` and ``validate`` methods have been called. Validation of a form is split into several steps, which can be customized or overridden: @@ -65,9 +65,9 @@ overridden: For example, if you wanted to validate that the contents of a ``CharField`` called ``serialnumber`` was unique, ``clean_serialnumber()`` would be the right place to do this. You don't - need a specific field (it's just a ``CharField``), but you want a - formfield-specific piece of validation and, possibly, - cleaning/normalizing the data. + need a specific field (it's a ``CharField``), but you want a + formfield-specific piece of validation and, possibly, cleaning/normalizing + the data. The return value of this method replaces the existing value in ``cleaned_data``, so it must be the field's value from ``cleaned_data`` (even @@ -218,16 +218,16 @@ previous features. Using validators ---------------- -Django's form (and model) fields support use of simple utility functions and -classes known as validators. A validator is merely a callable object or -function that takes a value and simply returns nothing if the value is valid or -raises a :exc:`~django.core.exceptions.ValidationError` if not. These can be -passed to a field's constructor, via the field's ``validators`` argument, or -defined on the :class:`~django.forms.Field` class itself with the -``default_validators`` attribute. +Django's form (and model) fields support use of utility functions and classes +known as validators. A validator is a callable object or function that takes a +value and returns nothing if the value is valid or raises a +:exc:`~django.core.exceptions.ValidationError` if not. These can be passed to a +field's constructor, via the field's ``validators`` argument, or defined on the +:class:`~django.forms.Field` class itself with the ``default_validators`` +attribute. -Simple validators can be used to validate values inside the field, let's have -a look at Django's ``SlugField``:: +Validators can be used to validate values inside the field, let's have a look +at Django's ``SlugField``:: from django.core import validators from django.forms import CharField @@ -235,9 +235,9 @@ a look at Django's ``SlugField``:: class SlugField(CharField): default_validators = [validators.validate_slug] -As you can see, ``SlugField`` is just a ``CharField`` with a customized -validator that validates that submitted text obeys to some character rules. -This can also be done on field definition so:: +As you can see, ``SlugField`` is a ``CharField`` with a customized validator +that validates that submitted text obeys to some character rules. This can also +be done on field definition so:: slug = forms.SlugField() @@ -281,8 +281,7 @@ Every form that uses this field will have these methods run before anything else can be done with the field's data. This is cleaning that is specific to this type of field, regardless of how it is subsequently used. -Let's create a simple ``ContactForm`` to demonstrate how you'd use this -field:: +Let's create a ``ContactForm`` to demonstrate how you'd use this field:: class ContactForm(forms.Form): subject = forms.CharField(max_length=100) @@ -291,10 +290,10 @@ field:: recipients = MultiEmailField() cc_myself = forms.BooleanField(required=False) -Simply use ``MultiEmailField`` like any other form field. When the -``is_valid()`` method is called on the form, the ``MultiEmailField.clean()`` -method will be run as part of the cleaning process and it will, in turn, call -the custom ``to_python()`` and ``validate()`` methods. +Use ``MultiEmailField`` like any other form field. When the ``is_valid()`` +method is called on the form, the ``MultiEmailField.clean()`` method will be +run as part of the cleaning process and it will, in turn, call the custom +``to_python()`` and ``validate()`` methods. Cleaning a specific field attribute ----------------------------------- @@ -403,7 +402,7 @@ work out what works effectively in your particular situation. Our new code self.add_error('cc_myself', msg) self.add_error('subject', msg) -The second argument of ``add_error()`` can be a simple string, or preferably -an instance of ``ValidationError``. See :ref:`raising-validation-error` for -more details. Note that ``add_error()`` automatically removes the field -from ``cleaned_data``. +The second argument of ``add_error()`` can be a string, or preferably an +instance of ``ValidationError``. See :ref:`raising-validation-error` for more +details. Note that ``add_error()`` automatically removes the field from +``cleaned_data``. diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index d649ece6ba..6b341620ee 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -34,8 +34,7 @@ which widget is used on which field, see the documentation about :ref:`built-in-fields`. However, if you want to use a different widget for a field, you can -just use the :attr:`~Field.widget` argument on the field definition. For -example:: +use the :attr:`~Field.widget` argument on the field definition. For example:: from django import forms @@ -127,7 +126,7 @@ need to specify additional attributes at the time when the widget object is instantiated and assigned to a form field (and perhaps add some rules to your CSS files). -For example, take the following simple form:: +For example, take the following form:: from django import forms @@ -770,8 +769,8 @@ that specifies the template used to render each choice. For example, for the </label> If you decide not to loop over the radio buttons -- e.g., if your template - simply includes ``{{ myform.beatles }}`` -- they'll be output in a ``<ul>`` - with ``<li>`` tags, as above. + includes ``{{ myform.beatles }}`` -- they'll be output in a ``<ul>`` with + ``<li>`` tags, as above. The outer ``<ul>`` container receives the ``id`` attribute of the widget, if defined, or :attr:`BoundField.auto_id` otherwise. diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt index f7778c2979..b5201b3219 100644 --- a/docs/ref/migration-operations.txt +++ b/docs/ref/migration-operations.txt @@ -20,10 +20,10 @@ manipulation. You can also write your own ``Operation`` classes if you want to encapsulate a custom change you commonly make. If you need an empty migration file to write your own ``Operation`` objects -into, just use ``python manage.py makemigrations --empty yourappname``, -but be aware that manually adding schema-altering operations can confuse the -migration autodetector and make resulting runs of :djadmin:`makemigrations` -output incorrect code. +into, use ``python manage.py makemigrations --empty yourappname``, but be aware +that manually adding schema-altering operations can confuse the migration +autodetector and make resulting runs of :djadmin:`makemigrations` output +incorrect code. All of the core Django operations are available from the ``django.db.migrations.operations`` module. @@ -53,8 +53,8 @@ The field instance should be an unbound field (so just ``bases`` is an optional list of other classes to have this model inherit from; it can contain both class objects as well as strings in the format ``"appname.ModelName"`` if you want to depend on another model (so you inherit -from the historical version). If it's not supplied, it defaults to just -inheriting from the standard ``models.Model``. +from the historical version). If it's not supplied, it defaults to inheriting +from the standard ``models.Model``. ``managers`` takes a list of 2-tuples of ``(manager_name, manager_instance)``. The first manager in the list will be the default manager for this model during @@ -318,9 +318,8 @@ The optional ``elidable`` argument determines whether or not the operation will be removed (elided) when :ref:`squashing migrations <migration-squashing>`. You are advised to write the code as a separate function above the ``Migration`` -class in the migration file, and just pass it to ``RunPython``. Here's an -example of using ``RunPython`` to create some initial objects on a ``Country`` -model:: +class in the migration file, and pass it to ``RunPython``. Here's an example of +using ``RunPython`` to create some initial objects on a ``Country`` model:: from django.db import migrations @@ -423,8 +422,8 @@ Writing your own ================ Operations have a relatively simple API, and they're designed so that you can -easily write your own to supplement the built-in Django ones. The basic structure -of an ``Operation`` looks like this:: +easily write your own to supplement the built-in Django ones. The basic +structure of an ``Operation`` looks like this:: from django.db.migrations.operations.base import Operation @@ -462,21 +461,21 @@ of an ``Operation`` looks like this:: return "Custom Operation" You can take this template and work from it, though we suggest looking at the -built-in Django operations in ``django.db.migrations.operations`` - they're -easy to read and cover a lot of the example usage of semi-internal aspects -of the migration framework like ``ProjectState`` and the patterns used to get -historical models, as well as ``ModelState`` and the patterns used to mutate -historical models in ``state_forwards()``. +built-in Django operations in ``django.db.migrations.operations`` - they cover +a lot of the example usage of semi-internal aspects of the migration framework +like ``ProjectState`` and the patterns used to get historical models, as well +as ``ModelState`` and the patterns used to mutate historical models in +``state_forwards()``. Some things to note: -* You don't need to learn too much about ``ProjectState`` to just write simple - migrations; just know that it has an ``apps`` property that gives access to - an app registry (which you can then call ``get_model`` on). +* You don't need to learn too much about ``ProjectState`` to write migrations; + just know that it has an ``apps`` property that gives access to an app + registry (which you can then call ``get_model`` on). * ``database_forwards`` and ``database_backwards`` both get two states passed - to them; these just represent the difference the ``state_forwards`` method - would have applied, but are given to you for convenience and speed reasons. + to them; these represent the difference the ``state_forwards`` method would + have applied, but are given to you for convenience and speed reasons. * If you want to work with model classes or model instances from the ``from_state`` argument in ``database_forwards()`` or @@ -506,9 +505,9 @@ Some things to note: for the :class:`~django.db.models.Manager` instances in ``ModelState.managers``. -As a simple example, let's make an operation that loads PostgreSQL extensions -(which contain some of PostgreSQL's more exciting features). It's simple enough; -there's no model state changes, and all it does is run one command:: +As an example, let's make an operation that loads PostgreSQL extensions (which +contain some of PostgreSQL's more exciting features). Since there's no model +state changes, all it does is run one command:: from django.db.migrations.operations.base import Operation diff --git a/docs/ref/models/conditional-expressions.txt b/docs/ref/models/conditional-expressions.txt index e88554dec6..69a45d662b 100644 --- a/docs/ref/models/conditional-expressions.txt +++ b/docs/ref/models/conditional-expressions.txt @@ -96,7 +96,7 @@ A ``Case()`` expression is like the :keyword:`if` ... :keyword:`elif` ... truthful value. The ``result`` expression from the matching ``When()`` object is returned. -A simple example:: +An example:: >>> >>> from datetime import date, timedelta diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 16dabf8177..85cab15e8d 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -98,8 +98,7 @@ into Python memory. Instead, Django uses the ``F()`` object to generate an SQL expression that describes the required operation at the database level. -This is easiest to understand through an example. Normally, one might do -something like this:: +Let's try this with an example. Normally, one might do something like this:: # Tintin filed a news story! reporter = Reporters.objects.get(name='Tintin') @@ -167,7 +166,7 @@ Python - update a field's value avoids a *race condition*. If two Python threads execute the code in the first example above, one thread could retrieve, increment, and save a field's value after the other has retrieved it from the database. The value that the second thread saves will be -based on the original value; the work of the first thread will simply be lost. +based on the original value; the work of the first thread will be lost. If the database is responsible for updating the field, the process is more robust: it will only ever update the field based on the value of the field in @@ -443,9 +442,9 @@ into the ``template`` attribute. Creating your own Aggregate Functions ------------------------------------- -Creating your own aggregate is extremely easy. At a minimum, you need -to define ``function``, but you can also completely customize the -SQL that is generated. Here's a brief example:: +You can create your own aggregate functions, too. At a minimum, you need to +define ``function``, but you can also completely customize the SQL that is +generated. Here's a brief example:: from django.db.models import Aggregate @@ -496,8 +495,8 @@ output value. .. class:: ExpressionWrapper(expression, output_field) -``ExpressionWrapper`` simply surrounds another expression and provides access -to properties, such as ``output_field``, that may not be available on other +``ExpressionWrapper`` surrounds another expression and provides access to +properties, such as ``output_field``, that may not be available on other expressions. ``ExpressionWrapper`` is necessary when using arithmetic on ``F()`` expressions with different types as described in :ref:`using-f-with-annotations`. @@ -754,8 +753,8 @@ The ``order_by`` argument accepts a sequence of expressions on which you can call :meth:`~django.db.models.Expression.asc` and :meth:`~django.db.models.Expression.desc`. The ordering controls the order in which the expression is applied. For example, if you sum over the rows in a -partition, the first result is just the value of the first row, the second is -the sum of first and second row. +partition, the first result is the value of the first row, the second is the +sum of first and second row. The ``frame`` parameter specifies which other rows that should be used in the computation. See :ref:`window-frames` for details. @@ -773,7 +772,7 @@ the same studio in the same genre and release year:: >>> ), >>> ) -This makes it easy to check if a movie is rated better or worse than its peers. +This allows you to check if a movie is rated better or worse than its peers. You may want to apply multiple expressions over the same window, i.e., the same partition and frame. For example, you could modify the previous example @@ -1061,7 +1060,7 @@ We do some basic validation on the parameters, including requiring at least the eventual result to. Now we implement the pre-processing and validation. Since we do not have -any of our own validation at this point, we just delegate to the nested +any of our own validation at this point, we delegate to the nested expressions:: def resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False): diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 49494186ce..0e907ca558 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -127,7 +127,7 @@ define a suitably-named constant for each value:: Though you can define a choices list outside of a model class and then refer to it, defining the choices and names for each choice inside the model class keeps all of that information with the class that uses it, -and makes the choices easy to reference (e.g, ``Student.SOPHOMORE`` +and helps reference the choices (e.g, ``Student.SOPHOMORE`` will work anywhere that the ``Student`` model has been imported). In addition, Django provides enumeration types that you can subclass to define @@ -634,10 +634,10 @@ Any combination of these options will result in an error. The ``auto_now`` and ``auto_now_add`` options will always use the date in the :ref:`default timezone <default-current-time-zone>` at the moment of creation or update. If you need something different, you may want to - consider simply using your own callable default or overriding ``save()`` - instead of using ``auto_now`` or ``auto_now_add``; or using a - ``DateTimeField`` instead of a ``DateField`` and deciding how to handle the - conversion from datetime to date at display time. + consider using your own callable default or overriding ``save()`` instead + of using ``auto_now`` or ``auto_now_add``; or using a ``DateTimeField`` + instead of a ``DateField`` and deciding how to handle the conversion from + datetime to date at display time. ``DateTimeField`` ----------------- @@ -1582,7 +1582,7 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in if it is a profile model designed specifically for your custom user model. Setting it to ``False`` does not mean you can reference a swappable model - even if it is swapped out - ``False`` just means that the migrations made + even if it is swapped out - ``False`` means that the migrations made with this ForeignKey will always reference the exact model you specify (so it will fail hard if the user tries to run with a User model you don't support, for example). diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 58557422e0..396300d035 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -16,14 +16,14 @@ Throughout this reference we'll use the :ref:`example Weblog models Creating objects ================ -To create a new instance of a model, just instantiate it like any other Python +To create a new instance of a model, instantiate it like any other Python class: .. class:: Model(**kwargs) -The keyword arguments are simply the names of the fields you've defined on your -model. Note that instantiating a model in no way touches your database; for -that, you need to :meth:`~Model.save()`. +The keyword arguments are the names of the fields you've defined on your model. +Note that instantiating a model in no way touches your database; for that, you +need to :meth:`~Model.save()`. .. note:: @@ -116,8 +116,8 @@ are loaded from the database:: super().save(*args, **kwargs) The example above shows a full ``from_db()`` implementation to clarify how that -is done. In this case it would of course be possible to just use ``super()`` call -in the ``from_db()`` method. +is done. In this case it would of course be possible to use ``super()`` call in +the ``from_db()`` method. Refreshing objects from database ================================ @@ -396,8 +396,8 @@ Explicitly specifying auto-primary-key values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If a model has an :class:`~django.db.models.AutoField` but you want to define a -new object's ID explicitly when saving, just define it explicitly before -saving, rather than relying on the auto-assignment of the ID:: +new object's ID explicitly when saving, define it explicitly before saving, +rather than relying on the auto-assignment of the ID:: >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') >>> b3.id # Returns 3. @@ -500,8 +500,8 @@ In some rare circumstances, it's necessary to be able to force the doing an ``UPDATE``. Or vice-versa: update, if possible, but not insert a new row. In these cases you can pass the ``force_insert=True`` or ``force_update=True`` parameters to the :meth:`~Model.save()` method. -Obviously, passing both parameters is an error: you cannot both insert *and* -update at the same time! +Passing both parameters is an error: you cannot both insert *and* update at the +same time! It should be very rare that you'll need to use these parameters. Django will almost always do the right thing and trying to override that will lead to @@ -749,9 +749,9 @@ This template code is much better: <a href="{{ object.get_absolute_url }}">{{ object.name }}</a> The logic here is that if you change the URL structure of your objects, even -for something simple such as correcting a spelling error, you don't want to -have to track down every place that the URL might be created. Specify it once, -in ``get_absolute_url()`` and have all your other code call that one place. +for something small like correcting a spelling error, you don't want to have to +track down every place that the URL might be created. Specify it once, in +``get_absolute_url()`` and have all your other code call that one place. .. note:: The string you return from ``get_absolute_url()`` **must** contain only diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index d4b1aa55ec..f9f84d9e5c 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -151,8 +151,8 @@ Here's the formal declaration of a ``QuerySet``: The ``query`` parameter to :class:`QuerySet` exists so that specialized query subclasses can reconstruct internal query state. The value of the parameter is an opaque representation of that query state and is not - part of a public API. To put it simply: if you need to ask, you don't - need to use it. + part of a public API. To put it another way: if you need to ask, you + don't need to use it. .. currentmodule:: django.db.models.query.QuerySet @@ -1943,7 +1943,7 @@ details. The internal implementation has some more error-checking than this and handles some extra edge-conditions; if you're interested, read the code. If you have a field named ``defaults`` and want to use it as an exact lookup in -``get_or_create()``, just use ``'defaults__exact'``, like so:: +``get_or_create()``, use ``'defaults__exact'``, like so:: Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'}) @@ -2418,8 +2418,8 @@ gains). Additionally, if a ``some_queryset`` has not yet been evaluated, but you know that it will be at some point, then using ``some_queryset.exists()`` will do more overall work (one query for the existence check plus an extra one to later -retrieve the results) than simply using ``bool(some_queryset)``, which -retrieves the results and then checks if any were returned. +retrieve the results) than using ``bool(some_queryset)``, which retrieves the +results and then checks if any were returned. ``update()`` ~~~~~~~~~~~~ diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index ac61164d54..67a6a41940 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -91,7 +91,7 @@ Related objects reference # No need to call e.save() at this point -- it's already been saved. - This is equivalent to (but much simpler than):: + This is equivalent to (but simpler than):: >>> b = Blog.objects.get(id=1) >>> e = Entry( diff --git a/docs/ref/schema-editor.txt b/docs/ref/schema-editor.txt index 20cd59ad6a..a80d45c573 100644 --- a/docs/ref/schema-editor.txt +++ b/docs/ref/schema-editor.txt @@ -34,10 +34,10 @@ If you are writing or maintaining a third-party database backend for Django, you will need to provide a ``SchemaEditor`` implementation in order to work with 1.7's migration functionality - however, as long as your database is relatively standard in its use of SQL and relational design, you should be able to -subclass one of the built-in Django ``SchemaEditor`` classes and just tweak the +subclass one of the built-in Django ``SchemaEditor`` classes and tweak the syntax a little. Also note that there are a few new database features that -migrations will look for: ``can_rollback_ddl`` and -``supports_combined_alters`` are the most important. +migrations will look for: ``can_rollback_ddl`` +and ``supports_combined_alters`` are the most important. Methods ======= @@ -48,8 +48,8 @@ Methods .. method:: BaseDatabaseSchemaEditor.execute(sql, params=[]) Executes the SQL statement passed in, with parameters if supplied. This -is a simple wrapper around the normal database cursors that allows -capture of the SQL to a ``.sql`` file if the user wishes. +is a wrapper around the normal database cursors that allows capture of the SQL +to a ``.sql`` file if the user wishes. ``create_model()`` ------------------ diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index f1d60d257b..493d99e92a 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -196,8 +196,8 @@ See the :ref:`cache documentation <cache_key_prefixing>` for more information. Default: ``''`` (Empty string) The location of the cache to use. This might be the directory for a -file system cache, a host and port for a memcache server, or simply an -identifying name for a local memory cache. e.g.:: +file system cache, a host and port for a memcache server, or an identifying +name for a local memory cache. e.g.:: CACHES = { 'default': { @@ -2443,8 +2443,8 @@ A list containing the settings for all template engines to be used with Django. Each item of the list is a dictionary containing the options for an individual engine. -Here's a simple setup that tells the Django template engine to load templates -from the ``templates`` subdirectory inside each installed application:: +Here's a setup that tells the Django template engine to load templates from the +``templates`` subdirectory inside each installed application:: TEMPLATES = [ { @@ -2657,7 +2657,7 @@ the correct environment. Default: ``True`` A boolean that specifies whether Django's translation system should be enabled. -This provides an easy way to turn it off, for performance. If this is set to +This provides a way to turn it off, for performance. If this is set to ``False``, Django will make some optimizations so as not to load the translation machinery. @@ -2759,7 +2759,7 @@ Default: ``None`` The full Python path of the WSGI application object that Django's built-in servers (e.g. :djadmin:`runserver`) will use. The :djadmin:`django-admin -startproject <startproject>` management command will create a simple +startproject <startproject>` management command will create a standard ``wsgi.py`` file with an ``application`` callable in it, and point this setting to that ``application``. @@ -3374,7 +3374,7 @@ setting. .. note:: When using the ``AppDirectoriesFinder`` finder, make sure your apps - can be found by staticfiles. Simply add the app to the + can be found by staticfiles by adding the app to the :setting:`INSTALLED_APPS` setting of your site. Static file finders are currently considered a private interface, and this diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index e51e99605e..decf055660 100644 --- a/docs/ref/template-response.txt +++ b/docs/ref/template-response.txt @@ -239,7 +239,7 @@ Some operations -- such as caching -- cannot be performed on an unrendered template. They must be performed on a fully complete and rendered response. -If you're using middleware, the solution is easy. Middleware provides +If you're using middleware, you can do that. Middleware provides multiple opportunities to process a response on exit from a view. If you put behavior in the response middleware, it's guaranteed to execute after template rendering has taken place. @@ -253,7 +253,7 @@ be invoked when rendering has completed. Using this callback, you can defer critical processing until a point where you can guarantee that rendered content will be available. -To define a post-render callback, just define a function that takes +To define a post-render callback, define a function that takes a single argument -- response -- and register that function with the template response:: @@ -285,8 +285,8 @@ A :class:`TemplateResponse` object can be used anywhere that a normal :class:`django.http.HttpResponse` can be used. It can also be used as an alternative to calling :func:`~django.shortcuts.render()`. -For example, the following simple view returns a :class:`TemplateResponse` -with a simple template and a context containing a queryset:: +For example, the following view returns a :class:`TemplateResponse` with a +template and a context containing a queryset:: from django.template.response import TemplateResponse diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index dbd8324ba2..becd34c545 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -5,7 +5,7 @@ The Django template language: for Python programmers .. currentmodule:: django.template This document explains the Django template system from a technical -perspective -- how it works and how to extend it. If you're just looking for +perspective -- how it works and how to extend it. If you're looking for reference on the language syntax, see :doc:`/ref/templates/language`. It assumes an understanding of templates, contexts, variables, tags, and @@ -41,12 +41,12 @@ lower level APIs: Configuring an engine ===================== -If you are simply using the -:class:`~django.template.backends.django.DjangoTemplates` backend, this -probably isn't the documentation you're looking for. An instance of the -``Engine`` class described below is accessible using the ``engine`` attribute -of that backend and any attribute defaults mentioned below are overridden by -what's passed by :class:`~django.template.backends.django.DjangoTemplates`. +If you are using the :class:`~django.template.backends.django.DjangoTemplates` +backend, this probably isn't the documentation you're looking for. An instance +of the ``Engine`` class described below is accessible using the ``engine`` +attribute of that backend and any attribute defaults mentioned below are +overridden by what's passed by +:class:`~django.template.backends.django.DjangoTemplates`. .. class:: Engine(dirs=None, app_dirs=False, context_processors=None, debug=False, loaders=None, string_if_invalid='', file_charset='utf-8', libraries=None, builtins=None, autoescape=True) @@ -315,9 +315,8 @@ straight lookups. Here are some things to keep in mind: .. _alters-data-description: -* Obviously, there can be side effects when calling some variables, and - it'd be either foolish or a security hole to allow the template system - to access them. +* There can be side effects when calling some variables, and it'd be either + foolish or a security hole to allow the template system to access them. A good example is the :meth:`~django.db.models.Model.delete` method on each Django model object. The template system shouldn't be allowed to do @@ -754,10 +753,10 @@ variables: Writing your own context processors ----------------------------------- -A context processor has a very simple interface: It's a Python function -that takes one argument, an :class:`~django.http.HttpRequest` object, and -returns a dictionary that gets added to the template context. Each context -processor *must* return a dictionary. +A context processor has a simple interface: It's a Python function that takes +one argument, an :class:`~django.http.HttpRequest` object, and returns a +dictionary that gets added to the template context. Each context processor +*must* return a dictionary. Custom context processors can live anywhere in your code base. All Django cares about is that your custom context processors are pointed to by the @@ -859,7 +858,7 @@ loaders that come with Django: subdirectory. If the directory exists, Django looks for templates in there. This means you can store templates with your individual apps. This also - makes it easy to distribute Django apps with default templates. + helps to distribute Django apps with default templates. For example, for this setting:: @@ -885,8 +884,8 @@ loaders that come with Django: it caches a list of which :setting:`INSTALLED_APPS` packages have a ``templates`` subdirectory. - You can enable this loader simply by setting - :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` to ``True``:: + You can enable this loader by setting :setting:`APP_DIRS + <TEMPLATES-APP_DIRS>` to ``True``:: TEMPLATES = [{ 'BACKEND': 'django.template.backends.django.DjangoTemplates', diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 5577131167..b5ebff2b73 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -123,7 +123,7 @@ You can mix variables and strings:: In some cases you might want to refer to the current value of a cycle without advancing to the next value. To do this, -just give the ``{% cycle %}`` tag a name, using "as", like this:: +give the ``{% cycle %}`` tag a name, using "as", like this:: {% cycle 'row1' 'row2' as rowcolors %} @@ -2182,9 +2182,9 @@ the output will be the string ``"01:23"`` (The ``"TIME_FORMAT"`` format specifier for the ``de`` locale as shipped with Django is ``"H:i"``). The ``time`` filter will only accept parameters in the format string that -relate to the time of day, not the date (for obvious reasons). If you need to -format a ``date`` value, use the :tfilter:`date` filter instead (or along -``time`` if you need to render a full :py:class:`~datetime.datetime` value). +relate to the time of day, not the date. If you need to format a ``date`` +value, use the :tfilter:`date` filter instead (or along with :tfilter:`time` if +you need to render a full :py:class:`~datetime.datetime` value). There is one exception the above rule: When passed a ``datetime`` value with attached timezone information (a :ref:`time-zone-aware diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt index 33687fc49d..62f866bbc0 100644 --- a/docs/ref/templates/language.txt +++ b/docs/ref/templates/language.txt @@ -36,8 +36,8 @@ Templates .. highlightlang:: html+django -A template is simply a text file. It can generate any text-based format (HTML, -XML, CSV, etc.). +A template is a text file. It can generate any text-based format (HTML, XML, +CSV, etc.). A template contains **variables**, which get replaced with values when the template is evaluated, and **tags**, which control the logic of the template. @@ -289,7 +289,7 @@ engine is template inheritance. Template inheritance allows you to build a base "skeleton" template that contains all the common elements of your site and defines **blocks** that child templates can override. -It's easiest to understand template inheritance by starting with an example:: +Let's look at template inheritance by starting with an example:: <!DOCTYPE html> <html lang="en"> @@ -314,9 +314,9 @@ It's easiest to understand template inheritance by starting with an example:: </body> </html> -This template, which we'll call ``base.html``, defines a simple HTML skeleton -document that you might use for a simple two-column page. It's the job of -"child" templates to fill the empty blocks with content. +This template, which we'll call ``base.html``, defines an HTML skeleton +document that you might use for a two-column page. It's the job of "child" +templates to fill the empty blocks with content. In this example, the :ttag:`block` tag defines three blocks that child templates can fill in. All the :ttag:`block` tag does is to tell the template @@ -386,8 +386,8 @@ inheritance is the following three-level approach: article or blog entry. These templates extend the appropriate section template. -This approach maximizes code reuse and makes it easy to add items to shared -content areas, such as section-wide navigation. +This approach maximizes code reuse and helps to add items to shared content +areas, such as section-wide navigation. Here are some tips for working with inheritance: @@ -533,8 +533,8 @@ the output will be:: For template blocks ~~~~~~~~~~~~~~~~~~~ -To control auto-escaping for a template, wrap the template (or just a -particular section of the template) in the :ttag:`autoescape` tag, like so:: +To control auto-escaping for a template, wrap the template (or a particular +section of the template) in the :ttag:`autoescape` tag, like so:: {% autoescape off %} Hello {{ name }} diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 06136da08f..1a0c36dc43 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -103,8 +103,8 @@ need to distinguish caches by the ``Accept-language`` header. The list of headers to use for cache key generation is stored in the same cache as the pages themselves. If the cache ages some data out of the - cache, this just means that we have to build the response once to get at - the Vary header and so at the list of headers to use for the cache key. + cache, this means that we have to build the response once to get at the + Vary header and so at the list of headers to use for the cache key. ``django.utils.dateparse`` ========================== @@ -491,9 +491,9 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 As well as offering potential performance advantages, ``@cached_property`` can ensure that an attribute's value does not change unexpectedly over the life of an instance. This could occur with a method whose computation is - based on ``datetime.now()``, or simply if a change were saved to the - database by some other process in the brief interval between subsequent - invocations of a method on the same instance. + based on ``datetime.now()``, or if a change were saved to the database by + some other process in the brief interval between subsequent invocations of + a method on the same instance. You can make cached properties of methods. For example, if you had an expensive ``get_friends()`` method and wanted to allow calling it without @@ -551,9 +551,9 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 The ``keep_lazy()`` decorator takes a number of extra arguments (``*args``) specifying the type(s) that the original function can return. A common - use case is to have functions that return text. For these, you can just - pass the ``str`` type to ``keep_lazy`` (or even simpler, use the - :func:`keep_lazy_text` decorator described in the next section). + use case is to have functions that return text. For these, you can pass the + ``str`` type to ``keep_lazy`` (or use the :func:`keep_lazy_text` decorator + described in the next section). Using this decorator means you can write your function and assume that the input is a proper string, then add support for lazy translation objects at @@ -564,7 +564,8 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 A shortcut for ``keep_lazy(str)(func)``. If you have a function that returns text and you want to be able to take - lazy arguments while delaying their evaluation, simply use this decorator:: + lazy arguments while delaying their evaluation, you can use this + decorator:: from django.utils.functional import keep_lazy, keep_lazy_text @@ -1060,7 +1061,7 @@ functions without the ``u``. :func:`django.utils.translation.activate` to fetch the translation object for a given language, activates it as the translation object for the current thread and reactivates the previous active language on exit. - Optionally, it can simply deactivate the temporary translation on exit with + Optionally, it can deactivate the temporary translation on exit with :func:`django.utils.translation.deactivate` if the ``deactivate`` argument is ``True``. If you pass ``None`` as the language argument, a ``NullTranslations()`` instance is activated within the context. diff --git a/docs/ref/views.txt b/docs/ref/views.txt index 37204e2fda..6aff0e3877 100644 --- a/docs/ref/views.txt +++ b/docs/ref/views.txt @@ -66,9 +66,9 @@ The 404 (page not found) view When you raise :exc:`~django.http.Http404` from within a view, Django loads a special view devoted to handling 404 errors. By default, it's the view -:func:`django.views.defaults.page_not_found`, which either produces a very -simple "Not Found" message or loads and renders the template ``404.html`` if -you created it in your root template directory. +:func:`django.views.defaults.page_not_found`, which either produces a "Not +Found" message or loads and renders the template ``404.html`` if you created it +in your root template directory. The default 404 view will pass two variables to the template: ``request_path``, which is the URL that resulted in the error, and ``exception``, which is a @@ -97,9 +97,9 @@ The 500 (server error) view Similarly, Django executes special-case behavior in the case of runtime errors in view code. If a view results in an exception, Django will, by default, call -the view ``django.views.defaults.server_error``, which either produces a very -simple "Server Error" message or loads and renders the template ``500.html`` if -you created it in your root template directory. +the view ``django.views.defaults.server_error``, which either produces a +"Server Error" message or loads and renders the template ``500.html`` if you +created it in your root template directory. The default 500 view passes no variables to the ``500.html`` template and is rendered with an empty ``Context`` to lessen the chance of additional errors. diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index 4c9515fe53..453566d4cf 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -82,8 +82,8 @@ backends that follow. authenticated user is needed. This effectively means that authentication sources are cached on a per-session basis, so if you change :setting:`AUTHENTICATION_BACKENDS`, you'll need to clear out session data if - you need to force users to re-authenticate using different methods. A simple - way to do that is simply to execute ``Session.objects.all().delete()``. + you need to force users to re-authenticate using different methods. A + simple way to do that is to execute ``Session.objects.all().delete()``. Writing an authentication backend --------------------------------- @@ -98,7 +98,7 @@ database ID or whatever, but has to be the primary key of your user object -- and returns a user object or ``None``. The ``authenticate`` method takes a ``request`` argument and credentials as -keyword arguments. Most of the time, it'll just look like this:: +keyword arguments. Most of the time, it'll look like this:: from django.contrib.auth.backends import BaseBackend @@ -197,7 +197,7 @@ exception in :meth:`~django.contrib.auth.models.User.has_perm()` or :meth:`~django.contrib.auth.models.User.has_module_perms()`, the authorization will immediately fail and Django won't check the backends that follow. -A backend could implement permissions for the magic admin fairly simply:: +A backend could implement permissions for the magic admin like this:: from django.contrib.auth.backends import BaseBackend @@ -729,7 +729,7 @@ Writing a manager for a custom user model You should also define a custom manager for your user model. If your user model defines ``username``, ``email``, ``is_staff``, ``is_active``, ``is_superuser``, ``last_login``, and ``date_joined`` fields the same as Django's default user, -you can just install Django's :class:`~django.contrib.auth.models.UserManager`; +you can install Django's :class:`~django.contrib.auth.models.UserManager`; however, if your user model defines different fields, you'll need to define a custom manager that extends :class:`~django.contrib.auth.models.BaseUserManager` providing two additional methods: @@ -793,10 +793,10 @@ Extending Django's default ``User`` ----------------------------------- If you're entirely happy with Django's :class:`~django.contrib.auth.models.User` -model and you just want to add some additional profile information, you could -simply subclass :class:`django.contrib.auth.models.AbstractUser` and add your -custom profile fields, although we'd recommend a separate model as described in -the "Model design considerations" note of :ref:`specifying-custom-user-model`. +model, but you want to add some additional profile information, you could +subclass :class:`django.contrib.auth.models.AbstractUser` and add your custom +profile fields, although we'd recommend a separate model as described in the +"Model design considerations" note of :ref:`specifying-custom-user-model`. ``AbstractUser`` provides the full implementation of the default :class:`~django.contrib.auth.models.User` as an :ref:`abstract model <abstract-base-classes>`. @@ -835,8 +835,8 @@ to work with a custom user model: * :class:`~django.contrib.auth.forms.UserCreationForm` * :class:`~django.contrib.auth.forms.UserChangeForm` -If your custom user model is a simple subclass of ``AbstractUser``, then you -can extend these forms in this manner:: +If your custom user model is a subclass of ``AbstractUser``, then you can +extend these forms in this manner:: from django.contrib.auth.forms import UserCreationForm from myapp.models import CustomUser @@ -1009,10 +1009,10 @@ A full example Here is an example of an admin-compliant custom user app. This user model uses an email address as the username, and has a required date of birth; it -provides no permission checking, beyond a simple ``admin`` flag on the user -account. This model would be compatible with all the built-in auth forms and -views, except for the user creation forms. This example illustrates how most of -the components work together, but is not intended to be copied directly into +provides no permission checking beyond an ``admin`` flag on the user account. +This model would be compatible with all the built-in auth forms and views, +except for the user creation forms. This example illustrates how most of the +components work together, but is not intended to be copied directly into projects for production use. This code would all live in a ``models.py`` file for a custom diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index 5f4c7a7a47..9f38fb70e4 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -150,7 +150,7 @@ Authenticating users Permissions and Authorization ============================= -Django comes with a simple permissions system. It provides a way to assign +Django comes with a built-in permissions system. It provides a way to assign permissions to specific users and groups of users. It's used by the Django admin site, but you're welcome to use it in your own @@ -473,7 +473,7 @@ Limiting access to logged-in users The raw way ~~~~~~~~~~~ -The simple, raw way to limit access to pages is to check +The raw way to limit access to pages is to check :attr:`request.user.is_authenticated <django.contrib.auth.models.User.is_authenticated>` and either redirect to a login page:: @@ -615,10 +615,9 @@ Limiting access to logged-in users that pass a test To limit access based on certain permissions or some other test, you'd do essentially the same thing as described in the previous section. -The simple way is to run your test on :attr:`request.user -<django.http.HttpRequest.user>` in the view directly. For example, this view -checks to make sure the user has an email in the desired domain and if not, -redirects to the login page:: +You can run your test on :attr:`request.user <django.http.HttpRequest.user>` in +the view directly. For example, this view checks to make sure the user has an +email in the desired domain and if not, redirects to the login page:: from django.shortcuts import redirect @@ -1015,8 +1014,8 @@ implementation details see :ref:`using-the-views`. * ``redirect_field_name``: The name of a ``GET`` field containing the URL to redirect to after login. Defaults to ``next``. - * ``authentication_form``: A callable (typically just a form class) to - use for authentication. Defaults to + * ``authentication_form``: A callable (typically a form class) to use for + authentication. Defaults to :class:`~django.contrib.auth.forms.AuthenticationForm`. * ``extra_context``: A dictionary of context data that will be added to the diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index 273ed33431..44e80911ba 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -423,8 +423,8 @@ Password validation Users often choose poor passwords. To help mitigate this problem, Django offers pluggable password validation. You can configure multiple password -validators at the same time. A few validators are included in Django, but it's -simple to write your own as well. +validators at the same time. A few validators are included in Django, but you +can write your own as well. Each password validator must provide a help text to explain the requirements to the user, validate a given password and return an error message if it does not @@ -434,7 +434,7 @@ Validators can also have optional settings to fine tune their behavior. Validation is controlled by the :setting:`AUTH_PASSWORD_VALIDATORS` setting. The default for the setting is an empty list, which means no validators are applied. In new projects created with the default :djadmin:`startproject` -template, a simple set of validators is enabled. +template, a set of validators is enabled by default. By default, validators are used in the forms to reset or change passwords and in the :djadmin:`createsuperuser` and :djadmin:`changepassword` management @@ -479,10 +479,9 @@ This example enables all four included validators: * ``UserAttributeSimilarityValidator``, which checks the similarity between the password and a set of attributes of the user. -* ``MinimumLengthValidator``, which simply checks whether the password meets a - minimum length. This validator is configured with a custom option: it now - requires the minimum length to be nine characters, instead of the default - eight. +* ``MinimumLengthValidator``, which checks whether the password meets a minimum + length. This validator is configured with a custom option: it now requires + the minimum length to be nine characters, instead of the default eight. * ``CommonPasswordValidator``, which checks whether the password occurs in a list of common passwords. By default, it compares to an included list of 20,000 common passwords. @@ -490,8 +489,8 @@ This example enables all four included validators: entirely numeric. For ``UserAttributeSimilarityValidator`` and ``CommonPasswordValidator``, -we're simply using the default settings in this example. -``NumericPasswordValidator`` has no settings. +we're using the default settings in this example. ``NumericPasswordValidator`` +has no settings. The help texts and any errors from password validators are always returned in the order they are listed in :setting:`AUTH_PASSWORD_VALIDATORS`. @@ -601,15 +600,15 @@ Writing your own validator -------------------------- If Django's built-in validators are not sufficient, you can write your own -password validators. Validators are fairly simple classes. They must implement -two methods: +password validators. Validators have a fairly small interface. They must +implement two methods: * ``validate(self, password, user=None)``: validate a password. Return ``None`` if the password is valid, or raise a :exc:`~django.core.exceptions.ValidationError` with an error message if the password is not valid. You must be able to deal with ``user`` being - ``None`` - if that means your validator can't run, simply return ``None`` - for no error. + ``None`` - if that means your validator can't run, return ``None`` for no + error. * ``get_help_text()``: provide a help text to explain the requirements to the user. diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 57c4a685eb..bbaa1e0ba6 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -10,9 +10,9 @@ processing-overhead perspective, than your standard read-a-file-off-the-filesystem server arrangement. For most Web applications, this overhead isn't a big deal. Most Web -applications aren't ``washingtonpost.com`` or ``slashdot.org``; they're simply -small- to medium-sized sites with so-so traffic. But for medium- to -high-traffic sites, it's essential to cut as much overhead as possible. +applications aren't ``washingtonpost.com`` or ``slashdot.org``; they're small- +to medium-sized sites with so-so traffic. But for medium- to high-traffic +sites, it's essential to cut as much overhead as possible. That's where caching comes in. @@ -366,7 +366,7 @@ as reference implementations. You'll find the code in the Note: Without a really compelling reason, such as a host that doesn't support them, you should stick to the cache backends included with Django. They've -been well-tested and are easy to use. +been well-tested and are well-documented. .. _cache_arguments: @@ -556,8 +556,7 @@ The per-view cache A more granular way to use the caching framework is by caching the output of individual views. ``django.views.decorators.cache`` defines a ``cache_page`` -decorator that will automatically cache the view's response for you. It's easy -to use:: +decorator that will automatically cache the view's response for you:: from django.views.decorators.cache import cache_page @@ -618,8 +617,8 @@ want to use them without being cached. The solution to these problems is to specify the per-view cache in the URLconf rather than next to the view functions themselves. -Doing so is easy: simply wrap the view function with ``cache_page`` when you -refer to it in the URLconf. Here's the old URLconf from earlier:: +You can do so by wrapping the view function with ``cache_page`` when you refer +to it in the URLconf. Here's the old URLconf from earlier:: urlpatterns = [ path('foo/<int:code>/', my_view), @@ -697,7 +696,7 @@ equivalent: {% cache my_timeout sidebar %} ... {% endcache %} This feature is useful in avoiding repetition in templates. You can set the -timeout in a variable, in one place, and just reuse that value. +timeout in a variable, in one place, and reuse that value. By default, the cache tag will try to use the cache called "template_fragments". If no such cache exists, it will fall back to using the default cache. You may @@ -743,11 +742,11 @@ per-site or per-view cache strategies offer, because you wouldn't want to cache the entire result (since some of the data changes often), but you'd still want to cache the results that rarely change. -For cases like this, Django exposes a simple, low-level cache API. You can use -this API to store objects in the cache with any level of granularity you like. -You can cache any Python object that can be pickled safely: strings, -dictionaries, lists of model objects, and so forth. (Most common Python objects -can be pickled; refer to the Python documentation for more information about +For cases like this, Django exposes a low-level cache API. You can use this API +to store objects in the cache with any level of granularity you like. You can +cache any Python object that can be pickled safely: strings, dictionaries, +lists of model objects, and so forth. (Most common Python objects can be +pickled; refer to the Python documentation for more information about pickling.) Accessing the cache @@ -840,7 +839,7 @@ check the return value. It will return ``True`` if the value was stored, If you want to get a key's value or set a value if the key isn't in the cache, there is the ``get_or_set()`` method. It takes the same parameters as ``get()`` -but the default is set as the new cache value for that key, rather than simply +but the default is set as the new cache value for that key, rather than returned:: >>> cache.get('my_new_key') # returns None @@ -881,8 +880,8 @@ failed to be inserted. .. method:: cache.delete(key, version=None) -You can delete keys explicitly with ``delete()``. This is an easy way of -clearing the cache for a particular object:: +You can delete keys explicitly with ``delete()`` to clear the cache for a +particular object:: >>> cache.delete('a') @@ -1111,11 +1110,11 @@ Many Web pages' contents differ based on authentication and a host of other variables, and cache systems that blindly save pages based purely on URLs could expose incorrect or sensitive data to subsequent visitors to those pages. -For example, say you operate a Web email system, and the contents of the -"inbox" page obviously depend on which user is logged in. If an ISP blindly -cached your site, then the first user who logged in through that ISP would have -their user-specific inbox page cached for subsequent visitors to the site. -That's not cool. +For example, if you operate a Web email system, then the contents of the +"inbox" page depend on which user is logged in. If an ISP blindly cached your +site, then the first user who logged in through that ISP would have their +user-specific inbox page cached for subsequent visitors to the site. That's +not cool. Fortunately, HTTP provides a solution to this problem. A number of HTTP headers exist to instruct downstream caches to differ their cache contents depending on diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt index 8e39ad6c14..ad5bb31b8e 100644 --- a/docs/topics/class-based-views/generic-display.txt +++ b/docs/topics/class-based-views/generic-display.txt @@ -29,8 +29,8 @@ Django ships with generic views to do the following: * Allow users to create, update, and delete objects -- with or without authorization. -Taken together, these views provide easy interfaces to perform the most common -tasks developers encounter. +Taken together, these views provide interfaces to perform the most common tasks +developers encounter. Extending generic views @@ -43,10 +43,10 @@ Django developers is how to make generic views handle a wider array of situations. This is one of the reasons generic views were redesigned for the 1.3 release - -previously, they were just view functions with a bewildering array of options; -now, rather than passing in a large amount of configuration in the URLconf, -the recommended way to extend generic views is to subclass them, and override -their attributes or methods. +previously, they were view functions with a bewildering array of options; now, +rather than passing in a large amount of configuration in the URLconf, the +recommended way to extend generic views is to subclass them, and override their +attributes or methods. That said, generic views will have a limit. If you find you're struggling to implement your view as a subclass of a generic view, then you may find it more @@ -63,8 +63,7 @@ Generic views of objects :class:`~django.views.generic.base.TemplateView` certainly is useful, but Django's generic views really shine when it comes to presenting views of your database content. Because it's such a common task, Django comes with a handful -of built-in generic views that make generating list and detail views of objects -incredibly easy. +of built-in generic views to help generate list and detail views of objects. Let's start by looking at some examples of showing a list of objects or an individual object. @@ -130,7 +129,7 @@ however. We could explicitly tell the view which template to use by adding a template Django will infer one from the object's name. In this case, the inferred template will be ``"books/publisher_list.html"`` -- the "books" part comes from the name of the app that defines the model, while the "publisher" -bit is just the lowercased version of the model's name. +bit is the lowercased version of the model's name. .. note:: @@ -139,8 +138,8 @@ bit is just the lowercased version of the model's name. be: /path/to/project/books/templates/books/publisher_list.html This template will be rendered against a context containing a variable called -``object_list`` that contains all the publisher objects. A very simple template -might look like the following: +``object_list`` that contains all the publisher objects. A template might look +like the this: .. code-block:: html+django @@ -197,17 +196,16 @@ coworkers who design templates will thank you. Adding extra context -------------------- -Often you simply need to present some extra information beyond that -provided by the generic view. For example, think of showing a list of -all the books on each publisher detail page. The -:class:`~django.views.generic.detail.DetailView` generic view provides -the publisher to the context, but how do we get additional information -in that template? +Often you need to present some extra information beyond that provided by the +generic view. For example, think of showing a list of all the books on each +publisher detail page. The :class:`~django.views.generic.detail.DetailView` +generic view provides the publisher to the context, but how do we get +additional information in that template? The answer is to subclass :class:`~django.views.generic.detail.DetailView` and provide your own implementation of the ``get_context_data`` method. -The default implementation simply adds the object being displayed to the -template, but you can override it to send more:: +The default implementation adds the object being displayed to the template, but +you can override it to send more:: from django.views.generic import DetailView from books.models import Book, Publisher @@ -261,16 +259,16 @@ specify the list of objects using the ``queryset`` argument:: context_object_name = 'publisher' queryset = Publisher.objects.all() -Specifying ``model = Publisher`` is really just shorthand for saying -``queryset = Publisher.objects.all()``. However, by using ``queryset`` -to define a filtered list of objects you can be more specific about the -objects that will be visible in the view (see :doc:`/topics/db/queries` -for more information about :class:`~django.db.models.query.QuerySet` objects, -and see the :doc:`class-based views reference </ref/class-based-views/index>` -for the complete details). +Specifying ``model = Publisher`` is shorthand for saying ``queryset = +Publisher.objects.all()``. However, by using ``queryset`` to define a filtered +list of objects you can be more specific about the objects that will be visible +in the view (see :doc:`/topics/db/queries` for more information about +:class:`~django.db.models.query.QuerySet` objects, and see the +:doc:`class-based views reference </ref/class-based-views/index>` for the +complete details). -To pick a simple example, we might want to order a list of books by -publication date, with the most recent first:: +To pick an example, we might want to order a list of books by publication date, +with the most recent first:: from django.views.generic import ListView from books.models import Book @@ -279,7 +277,7 @@ publication date, with the most recent first:: queryset = Book.objects.order_by('-publication_date') context_object_name = 'book_list' -That's a pretty simple example, but it illustrates the idea nicely. Of course, +That's a pretty minimal example, but it illustrates the idea nicely. Of course, you'll usually want to do more than just reorder objects. If you want to present a list of books by a particular publisher, you can use the same technique:: @@ -321,8 +319,8 @@ publisher? Handily, the ``ListView`` has a :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset` method we -can override. Previously, it has just been returning the value of the -``queryset`` attribute, but now we can add more logic. +can override. By default, it returns the value of the ``queryset`` attribute, +but we can use it to add more logic. The key part to making this work is that when class-based views are called, various useful things are stored on ``self``; as well as the request @@ -354,9 +352,10 @@ Next, we'll write the ``PublisherBookList`` view itself:: self.publisher = get_object_or_404(Publisher, name=self.kwargs['publisher']) return Book.objects.filter(publisher=self.publisher) -As you can see, it's quite easy to add more logic to the queryset selection; -if we wanted, we could use ``self.request.user`` to filter using the current -user, or other more complex logic. +Using ``get_queryset`` to add logic to the queryset selection is as convenient +as it is powerful. For instance, if we wanted, we could use +``self.request.user`` to filter using the current user, or other more complex +logic. We can also add the publisher into the context at the same time, so we can use it in the template:: @@ -407,7 +406,7 @@ custom view:: ] Then we'd write our new view -- ``get_object`` is the method that retrieves the -object -- so we simply override it and wrap the call:: +object -- so we override it and wrap the call:: from django.utils import timezone from django.views.generic import DetailView diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt index 7124b146ac..c1e73fc2fb 100644 --- a/docs/topics/class-based-views/generic-editing.txt +++ b/docs/topics/class-based-views/generic-editing.txt @@ -16,7 +16,7 @@ processing. Basic forms =========== -Given a simple contact form: +Given a contact form: .. code-block:: python :caption: forms.py @@ -85,7 +85,7 @@ You don't even need to provide a ``success_url`` for :meth:`~django.db.models.Model.get_absolute_url()` on the model object if available. If you want to use a custom :class:`~django.forms.ModelForm` (for instance to -add extra validation) simply set +add extra validation), set :attr:`~django.views.generic.edit.FormMixin.form_class` on your view. .. note:: @@ -132,8 +132,8 @@ here; we don't have to write any logic ourselves: success_url = reverse_lazy('author-list') .. note:: - We have to use :func:`~django.urls.reverse_lazy` here, not just - ``reverse()`` as the urls are not loaded when the file is imported. + We have to use :func:`~django.urls.reverse_lazy` instead of + ``reverse()``, as the urls are not loaded when the file is imported. The ``fields`` attribute works the same way as the ``fields`` attribute on the inner ``Meta`` class on :class:`~django.forms.ModelForm`. Unless you define the @@ -225,7 +225,7 @@ handle unauthorized users in :meth:`~.ModelFormMixin.form_valid()`. AJAX example ============ -Here is a simple example showing how you might go about implementing a form that +Here is an example showing how you might go about implementing a form that works for AJAX requests as well as 'normal' form POSTs:: from django.http import JsonResponse diff --git a/docs/topics/class-based-views/index.txt b/docs/topics/class-based-views/index.txt index 17e8b66f8f..364746a093 100644 --- a/docs/topics/class-based-views/index.txt +++ b/docs/topics/class-based-views/index.txt @@ -6,10 +6,10 @@ A view is a callable which takes a request and returns a response. This can be more than just a function, and Django provides an example of some classes which can be used as views. These allow you to structure your views and reuse code by harnessing inheritance and -mixins. There are also some generic views for simple tasks which we'll -get to later, but you may want to design your own structure of -reusable views which suits your use case. For full details, see the -:doc:`class-based views reference documentation</ref/class-based-views/index>`. +mixins. There are also some generic views for tasks which we'll get to later, +but you may want to design your own structure of reusable views which suits +your use case. For full details, see the :doc:`class-based views reference +documentation</ref/class-based-views/index>`. .. toctree:: :maxdepth: 1 @@ -25,18 +25,18 @@ Basic examples Django provides base view classes which will suit a wide range of applications. All views inherit from the :class:`~django.views.generic.base.View` class, which handles linking the view in to the URLs, HTTP method dispatching and other -simple features. :class:`~django.views.generic.base.RedirectView` is for a -simple HTTP redirect, and :class:`~django.views.generic.base.TemplateView` -extends the base class to make it also render a template. +common features. :class:`~django.views.generic.base.RedirectView` provides a +HTTP redirect, and :class:`~django.views.generic.base.TemplateView` extends the +base class to make it also render a template. -Simple usage in your URLconf -============================ +Usage in your URLconf +===================== -The simplest way to use generic views is to create them directly in your -URLconf. If you're only changing a few simple attributes on a class-based view, -you can simply pass them into the -:meth:`~django.views.generic.base.View.as_view` method call itself:: +The most direct way to use generic views is to create them directly in your +URLconf. If you're only changing a few attributes on a class-based view, you +can pass them into the :meth:`~django.views.generic.base.View.as_view` method +call itself:: from django.urls import path from django.views.generic import TemplateView @@ -59,8 +59,8 @@ existing view and override attributes (such as the ``template_name``) or methods (such as ``get_context_data``) in your subclass to provide new values or methods. Consider, for example, a view that just displays one template, ``about.html``. Django has a generic view to do this - -:class:`~django.views.generic.base.TemplateView` - so we can just subclass it, -and override the template name:: +:class:`~django.views.generic.base.TemplateView` - so we can subclass it, and +override the template name:: # some_app/views.py from django.views.generic import TemplateView @@ -68,11 +68,10 @@ and override the template name:: class AboutView(TemplateView): template_name = "about.html" -Then we just need to add this new view into our URLconf. -:class:`~django.views.generic.base.TemplateView` is a class, not a function, -so we point the URL to the :meth:`~django.views.generic.base.View.as_view` -class method instead, which provides a function-like entry to class-based -views:: +Then we need to add this new view into our URLconf. +:class:`~django.views.generic.base.TemplateView` is a class, not a function, so +we point the URL to the :meth:`~django.views.generic.base.View.as_view` class +method instead, which provides a function-like entry to class-based views:: # urls.py from django.urls import path @@ -123,9 +122,8 @@ And the view:: response['Last-Modified'] = last_book.publication_date.strftime('%a, %d %b %Y %H:%M:%S GMT') return response -If the view is accessed from a ``GET`` request, a plain-and-simple object -list is returned in the response (using ``book_list.html`` template). But if -the client issues a ``HEAD`` request, the response has an empty body and -the ``Last-Modified`` header indicates when the most recent book was published. -Based on this information, the client may or may not download the full object -list. +If the view is accessed from a ``GET`` request, an object list is returned in +the response (using the ``book_list.html`` template). But if the client issues +a ``HEAD`` request, the response has an empty body and the ``Last-Modified`` +header indicates when the most recent book was published. Based on this +information, the client may or may not download the full object list. diff --git a/docs/topics/class-based-views/intro.txt b/docs/topics/class-based-views/intro.txt index b1212af585..6b31180cf9 100644 --- a/docs/topics/class-based-views/intro.txt +++ b/docs/topics/class-based-views/intro.txt @@ -25,7 +25,7 @@ these patterns and ease view development for the common cases. The problem with function-based generic views is that while they covered the simple cases well, there was no way to extend or customize them beyond some -simple configuration options, limiting their usefulness in many real-world +configuration options, limiting their usefulness in many real-world applications. Class-based generic views were created with the same objective as @@ -35,9 +35,9 @@ results in class-based generic views being more extensible and flexible than their function-based counterparts. If you have tried function based generic views in the past and found them -lacking, you should not think of class-based generic views as simply a -class-based equivalent, but rather as a fresh approach to solving the original -problems that generic views were meant to solve. +lacking, you should not think of class-based generic views as a class-based +equivalent, but rather as a fresh approach to solving the original problems +that generic views were meant to solve. The toolkit of base classes and mixins that Django uses to build class-based generic views are built for maximum flexibility, and as such have many hooks in @@ -45,11 +45,11 @@ the form of default method implementations and attributes that you are unlikely to be concerned with in the simplest use cases. For example, instead of limiting you to a class-based attribute for ``form_class``, the implementation uses a ``get_form`` method, which calls a ``get_form_class`` method, which in -its default implementation just returns the ``form_class`` attribute of the -class. This gives you several options for specifying what form to use, from a -simple attribute, to a fully dynamic, callable hook. These options seem to add -hollow complexity for simple situations, but without them, more advanced -designs would be limited. +its default implementation returns the ``form_class`` attribute of the class. +This gives you several options for specifying what form to use, from an +attribute, to a fully dynamic, callable hook. These options seem to add hollow +complexity for simple situations, but without them, more advanced designs would +be limited. Using class-based views ======================= @@ -221,7 +221,7 @@ A similar class-based view might look like:: return render(request, self.template_name, {'form': form}) -This is a very simple case, but you can see that you would then have the option +This is a minimal case, but you can see that you would then have the option of customizing this view by overriding any of the class attributes, e.g. ``form_class``, via URLconf configuration, or subclassing and overriding one or more of the methods (or both!). @@ -236,9 +236,9 @@ differently depending on if you're using ``as_view()`` or creating a subclass. Decorating in URLconf --------------------- -The simplest way of decorating class-based views is to decorate the -result of the :meth:`~django.views.generic.base.View.as_view` method. -The easiest place to do this is in the URLconf where you deploy your view:: +You can adjust class-based views by decorating the result of the +:meth:`~django.views.generic.base.View.as_view` method. The easiest place to do +this is in the URLconf where you deploy your view:: from django.contrib.auth.decorators import login_required, permission_required from django.views.generic import TemplateView @@ -263,11 +263,11 @@ To decorate every instance of a class-based view, you need to decorate the class definition itself. To do this you apply the decorator to the :meth:`~django.views.generic.base.View.dispatch` method of the class. -A method on a class isn't quite the same as a standalone function, so -you can't just apply a function decorator to the method -- you need to -transform it into a method decorator first. The ``method_decorator`` -decorator transforms a function decorator into a method decorator so -that it can be used on an instance method. For example:: +A method on a class isn't quite the same as a standalone function, so you can't +just apply a function decorator to the method -- you need to transform it into +a method decorator first. The ``method_decorator`` decorator transforms a +function decorator into a method decorator so that it can be used on an +instance method. For example:: from django.contrib.auth.decorators import login_required from django.utils.decorators import method_decorator @@ -306,9 +306,9 @@ The decorators will process a request in the order they are passed to the decorator. In the example, ``never_cache()`` will process the request before ``login_required()``. -In this example, every instance of ``ProtectedView`` will have login protection. -These examples use ``login_required``, however, the same behavior can be -obtained more simply using +In this example, every instance of ``ProtectedView`` will have login +protection. These examples use ``login_required``, however, the same behavior +can be obtained by using :class:`~django.contrib.auth.mixins.LoginRequiredMixin`. .. note:: diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt index ad9fb7547b..fdc53e5c3b 100644 --- a/docs/topics/class-based-views/mixins.txt +++ b/docs/topics/class-based-views/mixins.txt @@ -46,7 +46,7 @@ interface to working with templates in class-based views. ``render_to_response()`` itself calls :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`, - which by default will just look up + which by default will look up :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` on the class-based view; two other mixins (:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin` @@ -61,8 +61,8 @@ interface to working with templates in class-based views. :meth:`~django.views.generic.base.ContextMixin.get_context_data()` passing any data they want to ensure is in there as keyword arguments. ``get_context_data()`` returns a dictionary; in ``ContextMixin`` it - simply returns its keyword arguments, but it is common to override this to - add more members to the dictionary. You can also use the + returns its keyword arguments, but it is common to override this to add + more members to the dictionary. You can also use the :attr:`~django.views.generic.base.ContextMixin.extra_context` attribute. Building up Django's generic class-based views @@ -142,7 +142,7 @@ and :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset`. Unlike with :class:`~django.views.generic.detail.SingleObjectMixin`, there's no need to key off parts of the URL to figure out the queryset to work with, so the -default just uses the +default uses the :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` or :attr:`~django.views.generic.list.MultipleObjectMixin.model` attribute on the view class. A common reason to override @@ -212,11 +212,10 @@ the box. Using ``SingleObjectMixin`` with View ------------------------------------- -If we want to write a simple class-based view that responds only to -``POST``, we'll subclass :class:`~django.views.generic.base.View` and -write a ``post()`` method in the subclass. However if we want our -processing to work on a particular object, identified from the URL, -we'll want the functionality provided by +If we want to write a class-based view that responds only to ``POST``, we'll +subclass :class:`~django.views.generic.base.View` and write a ``post()`` method +in the subclass. However if we want our processing to work on a particular +object, identified from the URL, we'll want the functionality provided by :class:`~django.views.generic.detail.SingleObjectMixin`. We'll demonstrate this with the ``Author`` model we used in the @@ -249,9 +248,8 @@ In practice you'd probably want to record the interest in a key-value store rather than in a relational database, so we've left that bit out. The only bit of the view that needs to worry about using :class:`~django.views.generic.detail.SingleObjectMixin` is where we want to -look up the author we're interested in, which it just does with a simple call -to ``self.get_object()``. Everything else is taken care of for us by the -mixin. +look up the author we're interested in, which it does with a call to +``self.get_object()``. Everything else is taken care of for us by the mixin. We can hook this into our URLs easily enough: @@ -288,8 +286,8 @@ object. In order to do this, we need to have two different querysets: ``Book`` queryset for use by :class:`~django.views.generic.list.ListView` Since we have access to the ``Publisher`` whose books we want to list, we - simply override ``get_queryset()`` and use the ``Publisher``’s - :ref:`reverse foreign key manager<backwards-related-objects>`. + override ``get_queryset()`` and use the ``Publisher``’s :ref:`reverse + foreign key manager<backwards-related-objects>`. ``Publisher`` queryset for use in :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` We'll rely on the default implementation of ``get_object()`` to fetch the @@ -476,24 +474,23 @@ Our new ``AuthorDetail`` looks like this:: # passed in form.cleaned_data['message'] return super().form_valid(form) -``get_success_url()`` is just providing somewhere to redirect to, +``get_success_url()`` is provides somewhere to redirect to, which gets used in the default implementation of ``form_valid()``. We have to provide our own ``post()`` as noted earlier. A better solution ----------------- -It should be obvious that the number of subtle interactions between +The number of subtle interactions between :class:`~django.views.generic.edit.FormMixin` and :class:`DetailView` is already testing our ability to manage things. It's unlikely you'd want to write this kind of class yourself. -In this case, it would be fairly easy to just write the ``post()`` -method yourself, keeping :class:`DetailView` as the only generic -functionality, although writing :class:`~django.forms.Form` handling code -involves a lot of duplication. +In this case, you could write the ``post()`` method yourself, keeping +:class:`DetailView` as the only generic functionality, although writing +:class:`~django.forms.Form` handling code involves a lot of duplication. -Alternatively, it would still be easier than the above approach to +Alternatively, it would still be less work than the above approach to have a separate view for processing the form, which could use :class:`~django.views.generic.edit.FormView` distinct from :class:`DetailView` without concerns. @@ -529,11 +526,11 @@ write our own ``get_context_data()`` to make the context['form'] = AuthorInterestForm() return context -Then the ``AuthorInterest`` is a simple :class:`FormView`, but we -have to bring in :class:`~django.views.generic.detail.SingleObjectMixin` so we -can find the author we're talking about, and we have to remember to set -``template_name`` to ensure that form errors will render the same -template as ``AuthorDisplay`` is using on ``GET``:: +Then the ``AuthorInterest`` is a :class:`FormView`, but we have to bring in +:class:`~django.views.generic.detail.SingleObjectMixin` so we can find the +author we're talking about, and we have to remember to set ``template_name`` to +ensure that form errors will render the same template as ``AuthorDisplay`` is +using on ``GET``:: from django.http import HttpResponseForbidden from django.urls import reverse @@ -593,7 +590,7 @@ rendered HTML. We can create a mixin class to use in all of our views, handling the conversion to JSON once. -For example, a simple JSON mixin might look something like this:: +For example, a JSON mixin might look something like this:: from django.http import JsonResponse @@ -628,8 +625,8 @@ For example, a simple JSON mixin might look something like this:: This mixin provides a ``render_to_json_response()`` method with the same signature as :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`. -To use it, we simply need to mix it into a ``TemplateView`` for example, -and override ``render_to_response()`` to call ``render_to_json_response()`` instead:: +To use it, we need to mix it into a ``TemplateView`` for example, and override +``render_to_response()`` to call ``render_to_json_response()`` instead:: from django.views.generic import TemplateView @@ -657,8 +654,8 @@ same behavior -- except for the format of the response. If you want to be really adventurous, you could even mix a :class:`~django.views.generic.detail.DetailView` subclass that is able to return *both* HTML and JSON content, depending on some property of -the HTTP request, such as a query argument or a HTTP header. Just mix -in both the ``JSONResponseMixin`` and a +the HTTP request, such as a query argument or a HTTP header. Mix in both the +``JSONResponseMixin`` and a :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`, and override the implementation of :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt index f5bd88acaf..aef77e7a00 100644 --- a/docs/topics/conditional-view-processing.txt +++ b/docs/topics/conditional-view-processing.txt @@ -71,7 +71,7 @@ if they are not already set by the view and if the request's method is safe (``GET`` or ``HEAD``). Using this feature usefully is probably best explained with an example. -Suppose you have this pair of models, representing a simple blog system:: +Suppose you have this pair of models, representing a small blog system:: import datetime from django.db import models @@ -205,10 +205,9 @@ every time. Comparison with middleware conditional processing ================================================= -Django provides simple and straightforward conditional ``GET`` handling via -:class:`django.middleware.http.ConditionalGetMiddleware`. While being easy to -use and suitable for many situations, the middleware has limitations for -advanced usage: +Django provides conditional ``GET`` handling via +:class:`django.middleware.http.ConditionalGetMiddleware`. While being suitable +for many situations, the middleware has limitations for advanced usage: * It's applied globally to all views in your project. * It doesn't save you from generating the response, which may be expensive. diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 505b3adf91..6e5c6271dd 100644 --- a/docs/topics/db/aggregation.txt +++ b/docs/topics/db/aggregation.txt @@ -135,9 +135,9 @@ by providing that name when you specify the aggregate clause:: >>> Book.objects.aggregate(average_price=Avg('price')) {'average_price': 34.35} -If you want to generate more than one aggregate, you just add another -argument to the ``aggregate()`` clause. So, if we also wanted to know -the maximum and minimum price of all books, we would issue the query:: +If you want to generate more than one aggregate, you add another argument to +the ``aggregate()`` clause. So, if we also wanted to know the maximum and +minimum price of all books, we would issue the query:: >>> from django.db.models import Avg, Max, Min >>> Book.objects.aggregate(Avg('price'), Max('price'), Min('price')) diff --git a/docs/topics/db/examples/one_to_one.txt b/docs/topics/db/examples/one_to_one.txt index 7588825a02..e400a9ff8a 100644 --- a/docs/topics/db/examples/one_to_one.txt +++ b/docs/topics/db/examples/one_to_one.txt @@ -102,9 +102,9 @@ raises ``ValueError``:: ... ValueError: save() prohibited to prevent data loss due to unsaved related object 'place'. -Restaurant.objects.all() just returns the Restaurants, not the Places. Note -that there are two restaurants - Ace Hardware the Restaurant was created in the -call to r.place = p2:: +Restaurant.objects.all() returns the Restaurants, not the Places. Note that +there are two restaurants - Ace Hardware the Restaurant was created in the call +to r.place = p2:: >>> Restaurant.objects.all() <QuerySet [<Restaurant: Demon Dogs the restaurant>, <Restaurant: Ace Hardware the restaurant>]> diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index a08dddd028..1b34bea69b 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -145,8 +145,8 @@ So these statements are all legal:: This example also pointed out another interesting technique: using multiple managers on the same model. You can attach as many ``Manager()`` instances to -a model as you'd like. This is an easy way to define common "filters" for your -models. +a model as you'd like. This is a non-repetitive way to define common "filters" +for your models. For example:: @@ -396,7 +396,7 @@ manager, you can provide the default manager on the child class:: default_manager = OtherManager() Here, ``default_manager`` is the default. The ``objects`` manager is -still available, since it's inherited. It just isn't used as the default. +still available, since it's inherited, but isn't used as the default. Finally for this example, suppose you want to add extra managers to the child class, but still use the default from ``AbstractBase``. You can't add the new diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 0aab0bb35f..a047f58b78 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -265,7 +265,7 @@ By default, Django gives each model the following field:: This is an auto-incrementing primary key. -If you'd like to specify a custom primary key, just specify +If you'd like to specify a custom primary key, specify :attr:`primary_key=True <Field.primary_key>` on one of your fields. If Django sees you've explicitly set :attr:`Field.primary_key`, it won't add the automatic ``id`` column. @@ -436,8 +436,8 @@ should work; all are optional. Extra fields on many-to-many relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When you're only dealing with simple many-to-many relationships such as -mixing and matching pizzas and toppings, a standard +When you're only dealing with many-to-many relationships such as mixing and +matching pizzas and toppings, a standard :class:`~django.db.models.ManyToManyField` is all you need. However, sometimes you may need to associate data with the relationship between two models. @@ -640,7 +640,7 @@ Models across files It's perfectly OK to relate a model to one from another app. To do this, import the related model at the top of the file where your model is defined. Then, -just refer to the other model class wherever needed. For example:: +refer to the other model class wherever needed. For example:: from django.db import models from geography.models import ZipCode @@ -1218,7 +1218,7 @@ accessible through ``MyPerson``, and vice-versa:: You could also use a proxy model to define a different default ordering on a model. You might not always want to order the ``Person`` model, but regularly -order by the ``last_name`` attribute when you use the proxy. This is easy:: +order by the ``last_name`` attribute when you use the proxy:: class OrderedPerson(Person): class Meta: diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index 095e228949..9550ca6e14 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -438,8 +438,8 @@ Manually selecting a database for a ``QuerySet`` ------------------------------------------------ You can select the database for a ``QuerySet`` at any point in the -``QuerySet`` "chain." Just call ``using()`` on the ``QuerySet`` to get -another ``QuerySet`` that uses the specified database. +``QuerySet`` "chain." Call ``using()`` on the ``QuerySet`` to get another +``QuerySet`` that uses the specified database. ``using()`` takes a single argument: the alias of the database on which you want to run the query. For example:: diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 9d22b980bd..e0ff14e0d6 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -53,7 +53,7 @@ Use standard DB optimization techniques * Appropriate use of field types. -We will assume you have done the obvious things above. The rest of this document +We will assume you have done the things listed above. The rest of this document focuses on how to use Django in such a way that you are not doing unnecessary work. This document also does not address other optimization techniques that apply to all expensive operations, such as :doc:`general purpose caching @@ -217,7 +217,7 @@ Don't retrieve things you don't need Use ``QuerySet.values()`` and ``values_list()`` ----------------------------------------------- -When you just want a ``dict`` or ``list`` of values, and don't need ORM model +When you only want a ``dict`` or ``list`` of values, and don't need ORM model objects, make appropriate usage of :meth:`~django.db.models.query.QuerySet.values()`. These can be useful for replacing model objects in template code - as long as @@ -260,7 +260,7 @@ But: Don't overuse ``count()`` and ``exists()`` ------------------------------------------ -If you are going to need other data from the QuerySet, just evaluate it. +If you are going to need other data from the QuerySet, evaluate it immediately. For example, assuming an Email model that has a ``body`` attribute and a many-to-many relation to User, the following template code is optimal: diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 7c2e6c1657..b76a940a14 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -96,10 +96,10 @@ Saving ``ForeignKey`` and ``ManyToManyField`` fields ---------------------------------------------------- Updating a :class:`~django.db.models.ForeignKey` field works exactly the same -way as saving a normal field -- simply assign an object of the right type to -the field in question. This example updates the ``blog`` attribute of an -``Entry`` instance ``entry``, assuming appropriate instances of ``Entry`` and -``Blog`` are already saved to the database (so we can retrieve them below):: +way as saving a normal field -- assign an object of the right type to the field +in question. This example updates the ``blog`` attribute of an ``Entry`` +instance ``entry``, assuming appropriate instances of ``Entry`` and ``Blog`` +are already saved to the database (so we can retrieve them below):: >>> from blog.models import Blog, Entry >>> entry = Entry.objects.get(pk=1) @@ -365,9 +365,9 @@ Further filtering or ordering of a sliced queryset is prohibited due to the ambiguous nature of how that might work. To retrieve a *single* object rather than a list -(e.g. ``SELECT foo FROM bar LIMIT 1``), use a simple index instead of a -slice. For example, this returns the first ``Entry`` in the database, after -ordering entries alphabetically by headline:: +(e.g. ``SELECT foo FROM bar LIMIT 1``), use an index instead of a slice. For +example, this returns the first ``Entry`` in the database, after ordering +entries alphabetically by headline:: >>> Entry.objects.order_by('headline')[0] @@ -484,7 +484,7 @@ Lookups that span relationships Django offers a powerful and intuitive way to "follow" relationships in lookups, taking care of the SQL ``JOIN``\s for you automatically, behind the -scenes. To span a relationship, just use the field name of related fields +scenes. To span a relationship, use the field name of related fields across models, separated by double underscores, until you get to the field you want. @@ -495,7 +495,7 @@ is ``'Beatles Blog'``:: This spanning can be as deep as you'd like. -It works backwards, too. To refer to a "reverse" relationship, just use the +It works backwards, too. To refer to a "reverse" relationship, use the lowercase name of the model. This example retrieves all ``Blog`` objects which have at least one ``Entry`` @@ -700,8 +700,8 @@ statement, the percent sign signifies a multiple-character wildcard and the underscore signifies a single-character wildcard.) This means things should work intuitively, so the abstraction doesn't leak. -For example, to retrieve all the entries that contain a percent sign, just use -the percent sign as any other character:: +For example, to retrieve all the entries that contain a percent sign, use the +percent sign as any other character:: >>> Entry.objects.filter(headline__contains='%') @@ -746,8 +746,8 @@ your database load. Also, there's a possibility the two lists may not include the same database records, because an ``Entry`` may have been added or deleted in the split second between the two requests. -To avoid this problem, simply save the -:class:`~django.db.models.query.QuerySet` and reuse it:: +To avoid this problem, save the :class:`~django.db.models.query.QuerySet` and +reuse it:: >>> queryset = Entry.objects.all() >>> print([p.headline for p in queryset]) # Evaluate the query set. @@ -875,7 +875,7 @@ precede the definition of any keyword arguments. For example:: Comparing objects ================= -To compare two model instances, just use the standard Python comparison operator, +To compare two model instances, use the standard Python comparison operator, the double equals sign: ``==``. Behind the scenes, that compares the primary key values of two models. @@ -954,7 +954,7 @@ Copying model instances Although there is no built-in method for copying model instances, it is possible to easily create new instance with all fields' values copied. In the -simplest case, you can just set ``pk`` to ``None``. Using our blog example:: +simplest case, you can set ``pk`` to ``None``. Using our blog example:: blog = Blog(name='My blog', tagline='Blogging is easy') blog.save() # blog.pk == 1 @@ -1040,8 +1040,8 @@ statement. It is a bulk operation for direct updates. It doesn't run any :attr:`~django.db.models.DateField.auto_now` field option. If you want to save every item in a :class:`~django.db.models.query.QuerySet` and make sure that the :meth:`~django.db.models.Model.save` method is called on -each instance, you don't need any special function to handle that. Just loop -over them and call :meth:`~django.db.models.Model.save`:: +each instance, you don't need any special function to handle that. Loop over +them and call :meth:`~django.db.models.Model.save`:: for item in my_queryset: item.save() @@ -1096,8 +1096,7 @@ Forward ~~~~~~~ If a model has a :class:`~django.db.models.ForeignKey`, instances of that model -will have access to the related (foreign) object via a simple attribute of the -model. +will have access to the related (foreign) object via an attribute of the model. Example:: @@ -1285,7 +1284,7 @@ One-to-one relationships One-to-one relationships are very similar to many-to-one relationships. If you define a :class:`~django.db.models.OneToOneField` on your model, instances of -that model will have access to the related object via a simple attribute of the +that model will have access to the related object via an attribute of the model. For example:: diff --git a/docs/topics/db/search.txt b/docs/topics/db/search.txt index b633fec1bf..08aa7d9136 100644 --- a/docs/topics/db/search.txt +++ b/docs/topics/db/search.txt @@ -16,8 +16,8 @@ Use Cases Standard textual queries ------------------------ -Text-based fields have a selection of simple matching operations. For example, -you may wish to allow lookup of an author like so:: +Text-based fields have a selection of matching operations. For example, you may +wish to allow lookup up an author like so:: >>> Author.objects.filter(name__contains='Terry') [<Author: Terry Gilliam>, <Author: Terry Jones>] @@ -77,7 +77,7 @@ enter something close (by varying definitions) to the source data. Document-based search --------------------- -Simple database operations are too simple an approach when you start +Standard database operations stop being a useful approach when you start considering large blocks of text. Whereas the examples above can be thought of as operations on a string of characters, full text search looks at the actual words. Depending on the system used, it's likely to use some of the following @@ -109,8 +109,8 @@ your database and so can easily be combined with other relational queries such as categorization. The :mod:`django.contrib.postgres` module provides some helpers to make these -queries. For example, a simple query might be to select all the blog entries -which mention "cheese":: +queries. For example, a query might select all the blog entries which mention +"cheese":: >>> Entry.objects.filter(body_text__search='cheese') [<Entry: Cheese on Toast recipes>, <Entry: Pizza recipes>] diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index 84420c7e4b..f0af7a4b44 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -46,8 +46,8 @@ return model instances: This method takes a raw SQL query, executes it, and returns a ``django.db.models.query.RawQuerySet`` instance. This ``RawQuerySet`` instance -can be iterated over just like a normal -:class:`~django.db.models.query.QuerySet` to provide object instances. +can be iterated over like a normal :class:`~django.db.models.query.QuerySet` to +provide object instances. This is best illustrated with an example. Suppose you have the following model:: diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index 272423d80c..aab61807cb 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -61,7 +61,7 @@ either all or none of the changes will be committed. generating a streaming response, since there's no sensible way to handle errors after starting to send the response. -In practice, this feature simply wraps every view function in the :func:`atomic` +In practice, this feature wraps every view function in the :func:`atomic` decorator described below. Note that only the execution of your view is enclosed in the transactions. @@ -410,7 +410,7 @@ For instance, if your database connection is dropped because your process was killed without a chance to shut down gracefully, your rollback hook will never run. -The solution is simple: instead of doing something during the atomic block +But there is a solution: instead of doing something during the atomic block (transaction) and then undoing it if the transaction fails, use :func:`on_commit` to delay doing it in the first place until after the transaction succeeds. It's a lot easier to undo something you never did in the @@ -432,8 +432,8 @@ Low-level APIs Autocommit ---------- -Django provides a straightforward API in the :mod:`django.db.transaction` -module to manage the autocommit state of each database connection. +Django provides an API in the :mod:`django.db.transaction` module to manage the +autocommit state of each database connection. .. function:: get_autocommit(using=None) @@ -622,7 +622,7 @@ Handling exceptions within PostgreSQL transactions Inside a transaction, when a call to a PostgreSQL cursor raises an exception (typically ``IntegrityError``), all subsequent SQL in the same transaction will fail with the error "current transaction is aborted, queries ignored -until end of transaction block". While simple use of ``save()`` is unlikely +until end of transaction block". While the basic use of ``save()`` is unlikely to raise an exception in PostgreSQL, there are more advanced usage patterns which might, such as saving objects with unique fields, saving using the force_insert/force_update flag, or invoking custom SQL. diff --git a/docs/topics/email.txt b/docs/topics/email.txt index 4cd106f5bc..bc983b4f2e 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -5,11 +5,10 @@ Sending email .. module:: django.core.mail :synopsis: Helpers to easily send email. -Although Python makes sending email relatively easy via the :mod:`smtplib` +Although Python provides a mail sending interface via the :mod:`smtplib` module, Django provides a couple of light wrappers over it. These wrappers are -provided to make sending email extra quick, to make it easy to test email -sending during development, and to provide support for platforms that can't use -SMTP. +provided to make sending email extra quick, to help test email sending during +development, and to provide support for platforms that can't use SMTP. The code lives in the ``django.core.mail`` module. @@ -45,8 +44,7 @@ a secure connection is used. .. function:: send_mail(subject, message, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None) -The simplest way to send email is using -``django.core.mail.send_mail()``. +In most cases, you can send email using ``django.core.mail.send_mail()``. The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters are required. @@ -186,7 +184,7 @@ will not send the email. It's your responsibility to validate all data before passing it to the email functions. If a ``message`` contains headers at the start of the string, the headers will -simply be printed as the first bit of the email message. +be printed as the first bit of the email message. Here's an example view that takes a ``subject``, ``message`` and ``from_email`` from the request's POST data, sends that to admin@example.com and redirects to @@ -239,9 +237,9 @@ recipients, file attachments, or multi-part email, you'll need to create message itself. The :ref:`email backend <topic-email-backends>` is then responsible for sending the email. -For convenience, :class:`~django.core.mail.EmailMessage` provides a simple -``send()`` method for sending a single email. If you need to send multiple -messages, the email backend API :ref:`provides an alternative +For convenience, :class:`~django.core.mail.EmailMessage` provides a ``send()`` +method for sending a single email. If you need to send multiple messages, the +email backend API :ref:`provides an alternative <topics-sending-multiple-emails>`. ``EmailMessage`` Objects @@ -360,7 +358,7 @@ The class has the following methods: * ``attach_file()`` creates a new attachment using a file from your filesystem. Call it with the path of the file to attach and, optionally, the MIME type to use for the attachment. If the MIME type is omitted, it - will be guessed from the filename. The simplest use would be:: + will be guessed from the filename. You can use it like this:: message.attach_file('/images/weather_map.png') @@ -672,9 +670,9 @@ anything. Python has a built-in way to accomplish this with a single command:: python -m smtpd -n -c DebuggingServer localhost:1025 -This command will start a simple SMTP server listening on port 1025 of -localhost. This server simply prints to standard output all email headers and -the email body. You then only need to set the :setting:`EMAIL_HOST` and +This command will start a minimal SMTP server listening on port 1025 of +localhost. This server prints to standard output all email headers and the +email body. You then only need to set the :setting:`EMAIL_HOST` and :setting:`EMAIL_PORT` accordingly. For a more detailed discussion of SMTP server options, see the Python documentation for the :mod:`smtpd` module. diff --git a/docs/topics/files.txt b/docs/topics/files.txt index 6da50f064c..2038dadd72 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -79,8 +79,8 @@ The ``File`` object Internally, Django uses a :class:`django.core.files.File` instance any time it needs to represent a file. -Most of the time you'll simply use a ``File`` that Django's given you (i.e. a -file attached to a model as above, or perhaps an uploaded file). +Most of the time you'll use a ``File`` that Django's given you (i.e. a file +attached to a model as above, or perhaps an uploaded file). If you need to construct a ``File`` yourself, the easiest way is to create one using a Python built-in ``file`` object:: diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index 84635457ff..8a630f6c9f 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -569,8 +569,8 @@ Adding additional fields to a formset If you need to add additional fields to the formset this can be easily accomplished. The formset base class provides an ``add_fields`` method. You -can simply override this method to add your own fields or even redefine the -default fields/attributes of the order and deletion fields:: +can override this method to add your own fields or even redefine the default +fields/attributes of the order and deletion fields:: >>> from django.forms import BaseFormSet >>> from django.forms import formset_factory @@ -651,9 +651,9 @@ This is useful if you want to :ref:`use more than one formset in a view Using a formset in views and templates ====================================== -Using a formset inside a view is as easy as using a regular ``Form`` class. -The only thing you will want to be aware of is making sure to use the -management form inside the template. Let's look at a sample view:: +Using a formset inside a view is not very different from using a regular +``Form`` class. The only thing you will want to be aware of is making sure to +use the management form inside the template. Let's look at a sample view:: from django.forms import formset_factory from django.shortcuts import render diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 6cf1570ab0..b6c6df0c16 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -26,11 +26,11 @@ allow a visitor to do things like enter text, select options, manipulate objects or controls, and so on, and then send that information back to the server. -Some of these form interface elements - text input or checkboxes - are fairly -simple and are built into HTML itself. Others are much more complex; an -interface that pops up a date picker or allows you to move a slider or -manipulate controls will typically use JavaScript and CSS as well as HTML form -``<input>`` elements to achieve these effects. +Some of these form interface elements - text input or checkboxes - are built +into HTML itself. Others are much more complex; an interface that pops up a +date picker or allows you to move a slider or manipulate controls will +typically use JavaScript and CSS as well as HTML form ``<input>`` elements to +achieve these effects. As well as its ``<input>`` elements, a form must specify two things: @@ -326,8 +326,7 @@ telling it where to go next. The template ~~~~~~~~~~~~ -We don't need to do much in our ``name.html`` template. The simplest example -is: +We don't need to do much in our ``name.html`` template: .. code-block:: html+django @@ -671,8 +670,7 @@ Useful attributes on ``{{ field }}`` include: Outputs a ``<ul class="errorlist">`` containing any validation errors corresponding to this field. You can customize the presentation of the errors with a ``{% for error in field.errors %}`` loop. In this - case, each object in the loop is a simple string containing the error - message. + case, each object in the loop is a string containing the error message. ``{{ field.is_hidden }}`` This attribute is ``True`` if the form field is a hidden field and diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt index 398a4538b1..c88679dda6 100644 --- a/docs/topics/forms/media.txt +++ b/docs/topics/forms/media.txt @@ -16,7 +16,7 @@ Calendar widget. This widget can then be associated with the CSS and JavaScript that is required to render the calendar. When the Calendar widget is used on a form, Django is able to identify the CSS and JavaScript files that are required, and provide the list of file names -in a form suitable for easy inclusion on your Web page. +in a form suitable for inclusion on your Web page. .. admonition:: Assets and Django Admin @@ -49,7 +49,7 @@ The easiest way to define assets is as a static definition. Using this method, the declaration is an inner ``Media`` class. The properties of the inner class define the requirements. -Here's a simple example:: +Here's an example:: from django import forms @@ -362,8 +362,7 @@ are part of the form:: <script type="text/javascript" src="http://static.example.com/whizbang.js"></script> If you want to associate additional assets with a form -- for example, -CSS for form layout -- simply add a ``Media`` declaration to the -form:: +CSS for form layout -- add a ``Media`` declaration to the form:: >>> class ContactForm(forms.Form): ... date = DateField(widget=CalendarWidget) diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index d8b137f624..56ab59fda2 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -389,9 +389,8 @@ you've manually saved the instance produced by the form, you can invoke >>> f.save_m2m() Calling ``save_m2m()`` is only required if you use ``save(commit=False)``. -When you use a simple ``save()`` on a form, all data -- including -many-to-many data -- is saved without the need for any additional method calls. -For example: +When you use a ``save()`` on a form, all data -- including many-to-many data -- +is saved without the need for any additional method calls. For example: .. code-block:: python @@ -731,8 +730,8 @@ to make:: >>> from myapp.models import Book >>> BookForm = modelform_factory(Book, fields=("author", "title")) -This can also be used to make simple modifications to existing forms, for -example by specifying the widgets to be used for a given field:: +This can also be used to make modifications to existing forms, for example by +specifying the widgets to be used for a given field:: >>> from django.forms import Textarea >>> Form = modelform_factory(Book, form=BookForm, @@ -755,8 +754,8 @@ Model formsets .. class:: models.BaseModelFormSet Like :doc:`regular formsets </topics/forms/formsets>`, Django provides a couple -of enhanced formset classes that make it easy to work with Django models. Let's -reuse the ``Author`` model from above:: +of enhanced formset classes to make working with Django models more +convenient. Let's reuse the ``Author`` model from above:: >>> from django.forms import modelformset_factory >>> from myapp.models import Author @@ -786,8 +785,8 @@ with the ``Author`` model. It works just like a regular formset:: :func:`~django.forms.models.modelformset_factory` uses :func:`~django.forms.formsets.formset_factory` to generate formsets. This - means that a model formset is just an extension of a basic formset that - knows how to interact with a particular model. + means that a model formset is an extension of a basic formset that knows + how to interact with a particular model. Changing the queryset --------------------- @@ -952,7 +951,7 @@ extra forms displayed. Also, ``extra=0`` doesn't prevent creation of new model instances as you can :ref:`add additional forms with JavaScript <understanding-the-managementform>` -or just send additional POST data. Formsets `don't yet provide functionality +or send additional POST data. Formsets `don't yet provide functionality <https://code.djangoproject.com/ticket/26142>`_ for an "edit only" view that prevents creation of new instances. diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt index 21a6f06853..534582cbf6 100644 --- a/docs/topics/http/file-uploads.txt +++ b/docs/topics/http/file-uploads.txt @@ -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)] diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 757e60c341..5921ba6625 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -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: diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index ed7257d847..4283d6ebe1 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -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: diff --git a/docs/topics/http/views.txt b/docs/topics/http/views.txt index baacd233b5..3076192676 100644 --- a/docs/topics/http/views.txt +++ b/docs/topics/http/views.txt @@ -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`:: diff --git a/docs/topics/i18n/formatting.txt b/docs/topics/i18n/formatting.txt index 4a0ce6d3e8..3dbb10f2dc 100644 --- a/docs/topics/i18n/formatting.txt +++ b/docs/topics/i18n/formatting.txt @@ -45,8 +45,8 @@ locales when guessing the format used by the user when inputting data on forms. ``%b`` (abbreviated month name), ``%B`` (full month name), or ``%p`` (AM/PM). -To enable a form field to localize input and output data simply use its -``localize`` argument:: +To enable a form field to localize input and output data use its ``localize`` +argument:: class CashRegisterForm(forms.Form): product = forms.CharField() @@ -152,8 +152,8 @@ want to create your own, because a format files doesn't exist for your locale, or because you want to overwrite some of the values. To use custom formats, specify the path where you'll place format files -first. To do that, just set your :setting:`FORMAT_MODULE_PATH` setting to -the package where format files will exist, for instance:: +first. To do that, set your :setting:`FORMAT_MODULE_PATH` setting to the +package where format files will exist, for instance:: FORMAT_MODULE_PATH = [ 'mysite.formats', diff --git a/docs/topics/i18n/index.txt b/docs/topics/i18n/index.txt index 5aad659033..a85d309bfc 100644 --- a/docs/topics/i18n/index.txt +++ b/docs/topics/i18n/index.txt @@ -28,9 +28,9 @@ Essentially, Django does two things: * It uses these hooks to localize Web apps for particular users according to their preferences. -Obviously, translation depends on the target language, and formatting usually -depends on the target country. This information is provided by browsers in -the ``Accept-Language`` header. However, the time zone isn't readily available. +Translation depends on the target language, and formatting usually depends on +the target country. This information is provided by browsers in the +``Accept-Language`` header. However, the time zone isn't readily available. Definitions =========== diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt index 86fd8b5062..c8a586a603 100644 --- a/docs/topics/i18n/timezones.txt +++ b/docs/topics/i18n/timezones.txt @@ -62,8 +62,8 @@ You can use :func:`~django.utils.timezone.is_aware` and aware or naive. When time zone support is disabled, Django uses naive datetime objects in local -time. This is simple and sufficient for many use cases. In this mode, to obtain -the current time, you would write:: +time. This is sufficient for many use cases. In this mode, to obtain the +current time, you would write:: import datetime @@ -155,11 +155,11 @@ time zone automatically. Instead, Django provides :ref:`time zone selection functions <time-zone-selection-functions>`. Use them to build the time zone selection logic that makes sense for you. -Most websites that care about time zones just ask users in which time zone they -live and store this information in the user's profile. For anonymous users, -they use the time zone of their primary audience or UTC. pytz_ provides -helpers_, like a list of time zones per country, that you can use to pre-select -the most likely choices. +Most websites that care about time zones ask users in which time zone they live +and store this information in the user's profile. For anonymous users, they use +the time zone of their primary audience or UTC. pytz_ provides helpers_, like a +list of time zones per country, that you can use to pre-select the most likely +choices. Here's an example that stores the current timezone in the session. (It skips error handling entirely for the sake of simplicity.) @@ -437,7 +437,7 @@ When serializing an aware datetime, the UTC offset is included, like this:: "2011-09-01T13:20:30+03:00" -For a naive datetime, it obviously isn't:: +While for a naive datetime, it isn't:: "2011-09-01T13:20:30" @@ -451,8 +451,8 @@ zone support, you'll see :exc:`RuntimeWarning`\ s when you load them. To get rid of the warnings, you must convert your fixtures to the "aware" format. You can regenerate fixtures with :djadmin:`loaddata` then :djadmin:`dumpdata`. -Or, if they're small enough, you can simply edit them to add the UTC offset -that matches your :setting:`TIME_ZONE` to each serialized datetime. +Or, if they're small enough, you can edit them to add the UTC offset that +matches your :setting:`TIME_ZONE` to each serialized datetime. .. _time-zones-faq: @@ -470,8 +470,8 @@ Setup When you enable time zone support, you'll encounter some errors because you're using naive datetimes where Django expects aware datetimes. Such - errors show up when running tests and they're easy to fix. You'll quickly - learn how to avoid invalid operations. + errors show up when running tests. You'll quickly learn how to avoid invalid + operations. On the other hand, bugs caused by the lack of time zone support are much harder to prevent, diagnose and fix. Anything that involves scheduled tasks @@ -613,7 +613,7 @@ Troubleshooting >>> from django.utils import timezone >>> timezone.activate(pytz.timezone("Asia/Singapore")) - # For this example, we just set the time zone to Singapore, but here's how + # For this example, we set the time zone to Singapore, but here's how # you would obtain the current time zone in the general case. >>> current_tz = timezone.get_current_timezone() # Again, this is the correct way to convert between time zones with pytz. diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 7432c7b3ff..f9bb27b6b7 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -91,8 +91,8 @@ string:: output = _("Welcome to my site.") return HttpResponse(output) -Obviously, you could code this without using the alias. This example is -identical to the previous one:: +You could code this without using the alias. This example is identical to the +previous one:: from django.http import HttpResponse from django.utils.translation import gettext @@ -439,8 +439,8 @@ strings before passing them to non-Django code:: requests.post('https://example.com/send', data={'body': str(body)}) -If you don't like the long ``gettext_lazy`` name, you can just alias it as -``_`` (underscore), like so:: +If you don't like the long ``gettext_lazy`` name, you can alias it as ``_`` +(underscore), like so:: from django.db import models from django.utils.translation import gettext_lazy as _ @@ -928,7 +928,7 @@ view <set_language-redirect-view>` for an example of how to display a language selector using ``{% get_language_info_list %}``. In addition to :setting:`LANGUAGES` style list of tuples, -``{% get_language_info_list %}`` supports simple lists of language codes. +``{% get_language_info_list %}`` supports lists of language codes. If you do this in your view: .. code-block:: python @@ -949,7 +949,7 @@ you can iterate over those languages in the template:: Template filters ~~~~~~~~~~~~~~~~ -There are also simple filters available for convenience: +There are also some filters available for convenience: * ``{{ LANGUAGE_CODE|language_name }}`` ("German") * ``{{ LANGUAGE_CODE|language_name_local }}`` ("Deutsch") @@ -1048,7 +1048,7 @@ Using the JavaScript translation catalog .. highlightlang:: javascript -To use the catalog, just pull in the dynamically generated script like this: +To use the catalog, pull in the dynamically generated script like this: .. code-block:: html+django @@ -1565,9 +1565,9 @@ multiple times:: If you don't have the ``gettext`` utilities installed, :djadmin:`makemessages` will create empty files. If that's the case, either - install the ``gettext`` utilities or just copy the English message file + install the ``gettext`` utilities or copy the English message file (``locale/en/LC_MESSAGES/django.po``) if available and use it as a starting - point; it's just an empty translation file. + point, which is an empty translation file. .. admonition:: Working on Windows? @@ -1575,11 +1575,10 @@ multiple times:: :djadmin:`makemessages` works, see :ref:`gettext_on_windows` for more information. -The format of ``.po`` files is straightforward. Each ``.po`` file contains a -small bit of metadata, such as the translation maintainer's contact -information, but the bulk of the file is a list of **messages** -- simple -mappings between translation strings and the actual translated text for the -particular language. +Each ``.po`` file contains a small bit of metadata, such as the translation +maintainer's contact information, but the bulk of the file is a list of +**messages** -- mappings between translation strings and the actual translated +text for the particular language. For example, if your Django app contained a translation string for the text ``"Welcome to my site."``, like so:: @@ -1693,7 +1692,7 @@ djangojs`` parameter, like this:: django-admin makemessages -d djangojs -l de This would create or update the message file for JavaScript for German. After -updating message files, just run :djadmin:`django-admin compilemessages +updating message files, run :djadmin:`django-admin compilemessages <compilemessages>` the same way as you do with normal Django message files. .. _gettext_on_windows: @@ -1702,9 +1701,9 @@ updating message files, just run :djadmin:`django-admin compilemessages ---------------------- This is only needed for people who either want to extract message IDs or compile -message files (``.po``). Translation work itself just involves editing existing -files of this type, but if you want to create your own message files, or want to -test or compile a changed message file, download `a precompiled binary +message files (``.po``). Translation work itself involves editing existing +files of this type, but if you want to create your own message files, or want +to test or compile a changed message file, download `a precompiled binary installer <https://mlocati.github.io/articles/gettext-iconv-windows.html>`_. You may also use ``gettext`` binaries you have obtained elsewhere, so long as @@ -1935,9 +1934,9 @@ way Django does translation: How Django discovers language preference ---------------------------------------- -Once you've prepared your translations -- or, if you just want to use the -translations that come with Django -- you'll just need to activate translation -for your app. +Once you've prepared your translations -- or, if you want to use the +translations that come with Django -- you'll need to activate translation for +your app. Behind the scenes, Django has a very flexible model of deciding which language should be used -- installation-wide, for a particular user, or both. @@ -2042,7 +2041,7 @@ Notes: Once ``LocaleMiddleware`` determines the user's preference, it makes this preference available as ``request.LANGUAGE_CODE`` for each :class:`~django.http.HttpRequest`. Feel free to read this value in your view -code. Here's a simple example:: +code. Here's an example:: from django.http import HttpResponse @@ -2098,8 +2097,8 @@ of the generic language. For example, untranslated ``pt_BR`` strings use ``pt`` translations. This way, you can write applications that include their own translations, and -you can override base translations in your project. Or, you can just build -a big project out of several apps and put all translations into one big common +you can override base translations in your project. Or, you can build a big +project out of several apps and put all translations into one big common message file specific to the project you are composing. The choice is yours. All message file repositories are structured the same way. They are: diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 3f58f5102e..c48364bcd7 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -72,10 +72,10 @@ sure a database server is running. Django supports many different database servers and is officially supported with PostgreSQL_, MariaDB_, MySQL_, Oracle_ and SQLite_. -If you are developing a simple project or something you don't plan to deploy -in a production environment, SQLite is generally the simplest option as it -doesn't require running a separate server. However, SQLite has many differences -from other databases, so if you are working on something substantial, it's +If you are developing a small project or something you don't plan to deploy in +a production environment, SQLite is generally the best option as it doesn't +require running a separate server. However, SQLite has many differences from +other databases, so if you are working on something substantial, it's recommended to develop with the same database that you plan on using in production. @@ -107,10 +107,10 @@ If you plan to use Django's ``manage.py migrate`` command to automatically create database tables for your models (after first installing Django and creating a project), you'll need to ensure that Django has permission to create and alter tables in the database you're using; if you plan to manually create -the tables, you can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and -``DELETE`` permissions. After creating a database user with these -permissions, you'll specify the details in your project's settings file, -see :setting:`DATABASES` for details. +the tables, you can grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and +``DELETE`` permissions. After creating a database user with these permissions, +you'll specify the details in your project's settings file, see +:setting:`DATABASES` for details. If you're using Django's :doc:`testing framework</topics/testing/index>` to test database queries, Django will need permission to create a test database. @@ -132,8 +132,6 @@ Installation instructions are slightly different depending on whether you're installing a distribution-specific package, downloading the latest official release, or fetching the latest development version. -It's easy, no matter which way you choose. - .. _installing-official-release: Installing an official release with ``pip`` @@ -171,7 +169,7 @@ Installing a distribution-specific package Check the :doc:`distribution specific notes </misc/distributions>` to see if your platform/distribution provides official Django packages/installers. Distribution-provided packages will typically allow for automatic installation -of dependencies and easy upgrade paths; however, these packages will rarely +of dependencies and supported upgrade paths; however, these packages will rarely contain the latest release of Django. .. _installing-development-version: @@ -221,8 +219,8 @@ latest bug fixes and improvements, follow these instructions: ``django-admin`` utility command available. In other words, you're all set! -When you want to update your copy of the Django source code, just run the -command ``git pull`` from within the ``django`` directory. When you do this, -Git will automatically download any changes. +When you want to update your copy of the Django source code, run the command +``git pull`` from within the ``django`` directory. When you do this, Git will +download any changes. .. _Git: https://git-scm.com/ diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt index ba73234fc1..7403bece62 100644 --- a/docs/topics/logging.txt +++ b/docs/topics/logging.txt @@ -122,7 +122,7 @@ Using logging Once you have configured your loggers, handlers, filters and formatters, you need to place logging calls into your code. Using the -logging framework is very simple. Here's an example:: +logging framework works like this:: # import the logging library import logging @@ -239,7 +239,7 @@ The full documentation for :ref:`dictConfig format <logging-config-dictschema>` is the best source of information about logging configuration dictionaries. However, to give you a taste of what is possible, here are several examples. -First, here's a simple configuration which writes all logging from the +First, here's a configuration which writes all logging from the :ref:`django-logger` logger to a local file:: .. code-block:: python @@ -363,8 +363,8 @@ This logging configuration does the following things: * Defines two formatters: - * ``simple``, that just outputs the log level name (e.g., - ``DEBUG``) and the log message. + * ``simple``, that outputs the log level name (e.g., ``DEBUG``) and the log + message. The ``format`` string is a normal Python formatting string describing the details that are to be output on each logging diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index 9f3260faa9..d7fa7fdd8a 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -114,8 +114,8 @@ Django projects without the need for a full database. Workflow ======== -Working with migrations is simple. Make changes to your models - say, add -a field and remove a model - and then run :djadmin:`makemigrations`:: +Django can create migrations for you. Make changes to your models - say, add a +field and remove a model - and then run :djadmin:`makemigrations`:: $ python manage.py makemigrations Migrations for 'books': @@ -173,10 +173,10 @@ Dependencies ============ While migrations are per-app, the tables and relationships implied by -your models are too complex to be created for just one app at a time. When -you make a migration that requires something else to run - for example, -you add a ``ForeignKey`` in your ``books`` app to your ``authors`` app - the -resulting migration will contain a dependency on a migration in ``authors``. +your models are too complex to be created for one app at a time. When you make +a migration that requires something else to run - for example, you add a +``ForeignKey`` in your ``books`` app to your ``authors`` app - the resulting +migration will contain a dependency on a migration in ``authors``. This means that when you run the migrations, the ``authors`` migration runs first and creates the table the ``ForeignKey`` references, and then the migration @@ -201,8 +201,8 @@ Migration files =============== Migrations are stored as an on-disk format, referred to here as -"migration files". These files are actually just normal Python files with -an agreed-upon object layout, written in a declarative style. +"migration files". These files are actually normal Python files with an +agreed-upon object layout, written in a declarative style. A basic migration file looks like this:: @@ -286,9 +286,8 @@ Initial migrations .. attribute:: Migration.initial The "initial migrations" for an app are the migrations that create the first -version of that app's tables. Usually an app will have just one initial -migration, but in some cases of complex model interdependencies it may have two -or more. +version of that app's tables. Usually an app will have one initial migration, +but in some cases of complex model interdependencies it may have two or more. Initial migrations are marked with an ``initial = True`` class attribute on the migration class. If an ``initial`` class attribute isn't found, a migration @@ -322,13 +321,12 @@ new migrations until it's fixed. When using multiple databases, you can use the Adding migrations to apps ========================= -Adding migrations to new apps is straightforward - they come preconfigured to -accept migrations, and so just run :djadmin:`makemigrations` once you've made -some changes. +New apps come preconfigured to accept migrations, and so you can add migrations +by running :djadmin:`makemigrations` once you've made some changes. If your app already has models and database tables, and doesn't have migrations yet (for example, you created it against a previous Django version), you'll -need to convert it to use migrations; this is a simple process:: +need to convert it to use migrations by running:: $ python manage.py makemigrations your_app_label @@ -390,8 +388,8 @@ classes will need to be kept around for as long as there is a migration referencing them. Any :doc:`custom model fields </howto/custom-model-fields>` will also need to be kept, since these are imported directly by migrations. -In addition, the base classes of the model are just stored as pointers, so you -must always keep base classes around for as long as there is a migration that +In addition, the base classes of the model are stored as pointers, so you must +always keep base classes around for as long as there is a migration that contains a reference to them. On the plus side, methods and managers from these base classes inherit normally, so if you absolutely need access to these you can opt to move them into a superclass. @@ -492,10 +490,10 @@ second is a :doc:`SchemaEditor </ref/schema-editor>`, which you can use to manually effect database schema changes (but beware, doing this can confuse the migration autodetector!) -Let's write a simple migration that populates our new ``name`` field with the -combined values of ``first_name`` and ``last_name`` (we've come to our senses -and realized that not everyone has first and last names). All we -need to do is use the historical model and iterate over the rows:: +Let's write a migration that populates our new ``name`` field with the combined +values of ``first_name`` and ``last_name`` (we've come to our senses and +realized that not everyone has first and last names). All we need to do is use +the historical model and iterate over the rows:: from django.db import migrations @@ -517,8 +515,8 @@ need to do is use the historical model and iterate over the rows:: migrations.RunPython(combine_names), ] -Once that's done, we can just run ``python manage.py migrate`` as normal and -the data migration will run in place alongside other migrations. +Once that's done, we can run ``python manage.py migrate`` as normal and the +data migration will run in place alongside other migrations. You can pass a second callable to :class:`~django.db.migrations.operations.RunPython` to run whatever logic you @@ -593,18 +591,17 @@ so they can coexist with the old migration files, and Django will intelligently switch between them depending where you are in the history. If you're still part-way through the set of migrations that you squashed, it will keep using them until it hits the end and then switch to the squashed history, while new -installs will just use the new squashed migration and skip all the old ones. +installs will use the new squashed migration and skip all the old ones. This enables you to squash and not mess up systems currently in production that aren't fully up-to-date yet. The recommended process is to squash, keeping the old files, commit and release, wait until all systems are upgraded with -the new release (or if you're a third-party project, just ensure your users -upgrade releases in order without skipping any), and then remove the old files, -commit and do a second release. +the new release (or if you're a third-party project, ensure your users upgrade +releases in order without skipping any), and then remove the old files, commit +and do a second release. -The command that backs all this is :djadmin:`squashmigrations` - just pass -it the app label and migration name you want to squash up to, and it'll get to -work:: +The command that backs all this is :djadmin:`squashmigrations` - pass it the +app label and migration name you want to squash up to, and it'll get to work:: $ ./manage.py squashmigrations myapp 0004 Will squash the following migrations: @@ -660,7 +657,7 @@ You must then transition the squashed migration to a normal migration by: Serializing values ================== -Migrations are just Python files containing the old definitions of your models +Migrations are Python files containing the old definitions of your models - thus, to write them, Django must take the current state of your models and serialize them out into a file. diff --git a/docs/topics/performance.txt b/docs/topics/performance.txt index 4ccf158241..70fcff6e48 100644 --- a/docs/topics/performance.txt +++ b/docs/topics/performance.txt @@ -86,7 +86,7 @@ Get things right from the start ------------------------------- Some work in optimization involves tackling performance shortcomings, but some -of the work can simply be built in to what you'd do anyway, as part of the good +of the work can be built in to what you'd do anyway, as part of the good practices you should adopt even before you start thinking about improving performance. @@ -353,7 +353,7 @@ Newer is often - but not always - better It's fairly rare for a new release of well-maintained software to be less efficient, but the maintainers can't anticipate every possible use-case - so while being aware that newer versions are likely to perform better, don't -simply assume that they always will. +assume that they always will. This is true of Django itself. Successive releases have offered a number of improvements across the system, but you should still check the real-world diff --git a/docs/topics/security.txt b/docs/topics/security.txt index 549b473988..862b2de258 100644 --- a/docs/topics/security.txt +++ b/docs/topics/security.txt @@ -66,10 +66,10 @@ this if you know what you are doing. There are other :ref:`limitations control. :ref:`CSRF protection works <how-csrf-works>` by checking for a secret in each -POST request. This ensures that a malicious user cannot simply "replay" a form -POST to your website and have another logged in user unwittingly submit that -form. The malicious user would have to know the secret, which is user specific -(using a cookie). +POST request. This ensures that a malicious user cannot "replay" a form POST to +your website and have another logged in user unwittingly submit that form. The +malicious user would have to know the secret, which is user specific (using a +cookie). When deployed with :ref:`HTTPS <security-recommendation-ssl>`, ``CsrfViewMiddleware`` will check that the HTTP referer header is set to a diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index 11d07bf301..a9bab470a2 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -15,7 +15,7 @@ serializer to handle any format (text-based or not). Serializing data ================ -At the highest level, serializing data is a very simple operation:: +At the highest level, you can serialize data like this:: from django.core import serializers data = serializers.serialize("xml", SomeModel.objects.all()) @@ -74,7 +74,7 @@ Inherited models If you have a model that is defined using an :ref:`abstract base class <abstract-base-classes>`, you don't have to do anything special to serialize -that model. Just call the serializer on the object (or objects) that you want to +that model. Call the serializer on the object (or objects) that you want to serialize, and the output will be a complete representation of the serialized object. @@ -105,7 +105,7 @@ serialize the ``Place`` models as well:: Deserializing data ================== -Deserializing data is also a fairly simple operation:: +Deserializing data is very similar to serializing it:: for obj in serializers.deserialize("xml", data): do_something_with(obj) @@ -114,7 +114,7 @@ As you can see, the ``deserialize`` function takes the same format argument as ``serialize``, a string or stream of data, and returns an iterator. However, here it gets slightly complicated. The objects returned by the -``deserialize`` iterator *aren't* simple Django objects. Instead, they are +``deserialize`` iterator *aren't* regular Django objects. Instead, they are special ``DeserializedObject`` instances that wrap a created -- but unsaved -- object and any associated relationship data. @@ -136,7 +136,7 @@ something like:: In other words, the usual use is to examine the deserialized objects to make sure that they are "appropriate" for saving before doing so. Of course, if you -trust your data source you could just save the object and move on. +trust your data source you can instead save the object directly and move on. The Django object itself can be inspected as ``deserialized_object.object``. If fields in the serialized data do not exist on a model, a @@ -170,7 +170,7 @@ Identifier Information XML --- -The basic XML serialization format is quite simple:: +The basic XML serialization format looks like this:: <?xml version="1.0" encoding="utf-8"?> <django-objects version="1.0"> @@ -247,7 +247,7 @@ with three properties: "pk", "model" and "fields". "fields" is again an object containing each field's name and value as property and property-value respectively. -Foreign keys just have the PK of the linked object as property value. +Foreign keys have the PK of the linked object as property value. ManyToMany-relations are serialized for the model that defines them and are represented as a list of PKs. @@ -313,7 +313,7 @@ again a mapping with the key being name of the field and the value the value:: model: sessions.session pk: 4b678b301dfd8a4e0dad910de3ae245b -Referential fields are again just represented by the PK or sequence of PKs. +Referential fields are again represented by the PK or sequence of PKs. .. _topics-serialization-natural-keys: diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index def574546f..7a420b6777 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -104,9 +104,8 @@ that's redundant. Seeing which settings you've changed ------------------------------------ -There's an easy way to view which of your settings deviate from the default -settings. The command ``python manage.py diffsettings`` displays differences -between the current settings file and Django's default settings. +The command ``python manage.py diffsettings`` displays differences between the +current settings file and Django's default settings. For more, see the :djadmin:`diffsettings` documentation. @@ -161,7 +160,7 @@ Creating your own settings ========================== There's nothing stopping you from creating your own settings, for your own -Django apps. Just follow these guidelines: +Django apps, but follow these guidelines: * Setting names must be all uppercase. * Don't reinvent an already-existing setting. @@ -248,7 +247,7 @@ is accessed. If you set ``DJANGO_SETTINGS_MODULE``, access settings values somehow, *then* call ``configure()``, Django will raise a ``RuntimeError`` indicating -that settings have already been configured. There is a property just for this +that settings have already been configured. There is a property for this purpose: .. attribute: django.conf.settings.configured diff --git a/docs/topics/signals.txt b/docs/topics/signals.txt index 80a92d7a9c..817867a4ae 100644 --- a/docs/topics/signals.txt +++ b/docs/topics/signals.txt @@ -138,7 +138,7 @@ Now, our ``my_callback`` function will be called each time a request finishes. submodule of the application they relate to. Signal receivers are connected in the :meth:`~django.apps.AppConfig.ready` method of your application configuration class. If you're using the :func:`receiver` - decorator, simply import the ``signals`` submodule inside + decorator, import the ``signals`` submodule inside :meth:`~django.apps.AppConfig.ready`. .. note:: diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index 41c7f58745..8382be82b4 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -225,7 +225,7 @@ subdirectories as needed. Do this for your own sanity. Storing all templates in the root level of a single directory gets messy. -To load a template that's within a subdirectory, just use a slash, like so:: +To load a template that's within a subdirectory, use a slash, like so:: get_template('news/story_detail.html') @@ -439,7 +439,7 @@ adds defaults that differ from Jinja2's for a few options: * Using the result multiple times in each template. Unless all of these conditions are met, passing a function to the template is - simpler and more in line with the design of Jinja2. + more in line with the design of Jinja2. The default configuration is purposefully kept to a minimum. If a template is rendered with a request (e.g. when using :py:func:`~django.shortcuts.render`), @@ -478,10 +478,10 @@ Then you could use the following constructs in Jinja2 templates: The concepts of tags and filters exist both in the Django template language and in Jinja2 but they're used differently. Since Jinja2 supports passing arguments to callables in templates, many features that require a template tag -or filter in Django templates can be achieved simply by calling a function in -Jinja2 templates, as shown in the example above. Jinja2's global namespace -removes the need for template context processors. The Django template language -doesn't have an equivalent of Jinja2 tests. +or filter in Django templates can be achieved by calling a function in Jinja2 +templates, as shown in the example above. Jinja2's global namespace removes the +need for template context processors. The Django template language doesn't have +an equivalent of Jinja2 tests. Custom backends --------------- @@ -667,9 +667,9 @@ Syntax This is an overview of the Django template language's syntax. For details see the :doc:`language syntax reference </ref/templates/language>`. -A Django template is simply a text document or a Python string marked-up using -the Django template language. Some constructs are recognized and interpreted -by the template engine. The main ones are variables and tags. +A Django template is a text document or a Python string marked-up using the +Django template language. Some constructs are recognized and interpreted by the +template engine. The main ones are variables and tags. A template is rendered with a context. Rendering replaces variables with their values, which are looked up in the context, and executes tags. Everything else @@ -822,8 +822,8 @@ data to be added to the rendering context. Their main use is to add common data shared by all templates to the context without repeating code in every view. -Django provides many :ref:`built-in context processors <context-processors>`. -Implementing a custom context processor is as simple as defining a function. +Django provides many :ref:`built-in context processors <context-processors>`, +and you can implement your own additional context processors, too. .. _Jinja2: http://jinja.pocoo.org/ .. _DEP 182: https://github.com/django/deps/blob/master/final/0182-multiple-template-engines.rst diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt index 2e4171d376..48006d7b73 100644 --- a/docs/topics/testing/advanced.txt +++ b/docs/topics/testing/advanced.txt @@ -35,7 +35,7 @@ restricted subset of the test client API: Example ------- -The following is a simple unit test using the request factory:: +The following is a unit test using the request factory:: from django.contrib.auth.models import AnonymousUser, User from django.test import RequestFactory, TestCase @@ -79,9 +79,8 @@ Projects that support multitenancy or otherwise alter business logic based on the request's host and use custom host names in tests must include those hosts in :setting:`ALLOWED_HOSTS`. -The first and simplest option to do so is to add the hosts to your settings -file. For example, the test suite for docs.djangoproject.com includes the -following:: +The first option to do so is to add the hosts to your settings file. For +example, the test suite for docs.djangoproject.com includes the following:: from django.test import TestCase diff --git a/docs/topics/testing/index.txt b/docs/topics/testing/index.txt index e8cab96277..65f970b0ae 100644 --- a/docs/topics/testing/index.txt +++ b/docs/topics/testing/index.txt @@ -20,8 +20,6 @@ framework and assorted utilities, you can simulate requests, insert test data, inspect your application's output and generally verify your code is doing what it should be doing. -The best part is, it's really easy. - The preferred way to write tests in Django is using the :mod:`unittest` module built in to the Python standard library. This is covered in detail in the :doc:`overview` document. diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index 31c62383e0..e74e3fb21b 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -661,7 +661,7 @@ More details are in :ref:`explicitly-setting-the-active-language`. Example ------- -The following is a simple unit test using the test client:: +The following is a unit test using the test client:: import unittest from django.test import Client @@ -702,11 +702,11 @@ Normal Python unit test classes extend a base class of Hierarchy of Django unit testing classes -Converting a normal :class:`unittest.TestCase` to any of the subclasses is -easy: change the base class of your test from ``unittest.TestCase`` to the -subclass. All of the standard Python unit test functionality will be available, -and it will be augmented with some useful additions as described in each -section below. +You can convert a normal :class:`unittest.TestCase` to any of the subclasses: +change the base class of your test from ``unittest.TestCase`` to the subclass. +All of the standard Python unit test functionality will be available, and it +will be augmented with some useful additions as described in each section +below. ``SimpleTestCase`` ------------------ @@ -914,9 +914,9 @@ The live server listens on ``localhost`` and binds to port 0 which uses a free port assigned by the operating system. The server's URL can be accessed with ``self.live_server_url`` during the tests. -To demonstrate how to use ``LiveServerTestCase``, let's write a simple Selenium -test. First of all, you need to install the `selenium package`_ into your -Python path: +To demonstrate how to use ``LiveServerTestCase``, let's write a Selenium test. +First of all, you need to install the `selenium package`_ into your Python +path: .. console:: @@ -1002,10 +1002,10 @@ out the `full reference`_ for more details. The tricky thing here is that there's really no such thing as a "page load," especially in modern Web apps that generate HTML dynamically after the - server generates the initial document. So, simply checking for the presence - of ``<body>`` in the response might not necessarily be appropriate for all - use cases. Please refer to the `Selenium FAQ`_ and - `Selenium documentation`_ for more information. + server generates the initial document. So, checking for the presence of + ``<body>`` in the response might not necessarily be appropriate for all use + cases. Please refer to the `Selenium FAQ`_ and `Selenium documentation`_ + for more information. .. _Selenium FAQ: https://web.archive.org/web/20160129132110/http://code.google.com/p/selenium/wiki/FrequentlyAskedQuestions#Q:_WebDriver_fails_to_find_elements_/_Does_not_block_on_page_loa .. _Selenium documentation: https://www.seleniumhq.org/docs/04_webdriver_advanced.html#explicit-waits @@ -1039,7 +1039,7 @@ This means, instead of instantiating a ``Client`` in each test:: response = client.get('/customer/index/') self.assertEqual(response.status_code, 200) -...you can just refer to ``self.client``, like so:: +...you can refer to ``self.client``, like so:: from django.test import TestCase @@ -1268,9 +1268,9 @@ in the ``with`` block and reset its value to the previous state afterwards. .. method:: SimpleTestCase.modify_settings() It can prove unwieldy to redefine settings that contain a list of values. In -practice, adding or removing values is often sufficient. The -:meth:`~django.test.SimpleTestCase.modify_settings` context manager makes it -easy:: +practice, adding or removing values is often sufficient. Django provides the +:meth:`~django.test.SimpleTestCase.modify_settings` context manager for easier +settings changes:: from django.test import TestCase @@ -1806,12 +1806,12 @@ Django, such as your machine's mail server, if you're running one.) .. data:: django.core.mail.outbox During test running, each outgoing email is saved in -``django.core.mail.outbox``. This is a simple list of all -:class:`~django.core.mail.EmailMessage` instances that have been sent. -The ``outbox`` attribute is a special attribute that is created *only* when -the ``locmem`` email backend is used. It doesn't normally exist as part of the -:mod:`django.core.mail` module and you can't import it directly. The code -below shows how to access this attribute correctly. +``django.core.mail.outbox``. This is a list of all +:class:`~django.core.mail.EmailMessage` instances that have been sent. The +``outbox`` attribute is a special attribute that is created *only* when the +``locmem`` email backend is used. It doesn't normally exist as part of the +:mod:`django.core.mail` module and you can't import it directly. The code below +shows how to access this attribute correctly. Here's an example test that examines ``django.core.mail.outbox`` for length and contents:: |