diff options
| author | Natalia <124304+nessita@users.noreply.github.com> | 2025-08-22 12:36:48 -0300 |
|---|---|---|
| committer | nessita <124304+nessita@users.noreply.github.com> | 2025-08-25 10:51:10 -0300 |
| commit | 4286a23df64f6ce3b9b6ed097f4d1aac7d9e0de4 (patch) | |
| tree | e7225d1586c174b5945f595b3759b7c6dddbdae1 | |
| parent | 01a460f23e470555a733b8980401402b7947bb9f (diff) | |
Refs #36485 -- Removed double spaces after periods in sentences.
80 files changed, 310 insertions, 306 deletions
diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt index 254a141b45..c5f53c5e07 100644 --- a/docs/howto/auth-remote-user.txt +++ b/docs/howto/auth-remote-user.txt @@ -4,7 +4,7 @@ How to authenticate using ``REMOTE_USER`` This document describes how to make use of external authentication sources (where the web server sets the ``REMOTE_USER`` environment variable) in your -Django applications. This type of authentication solution is typically seen on +Django applications. This type of authentication solution is typically seen on intranet sites, with single sign-on solutions such as IIS and Integrated Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `WebAuth`_, `mod_auth_sspi`_, etc. @@ -15,9 +15,9 @@ Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `WebAuth`_, .. _mod_auth_sspi: https://sourceforge.net/projects/mod-auth-sspi When the web server takes care of authentication it typically sets the -``REMOTE_USER`` environment variable for use in the underlying application. In +``REMOTE_USER`` environment variable for use in the underlying application. In Django, ``REMOTE_USER`` is made available in the :attr:`request.META -<django.http.HttpRequest.META>` attribute. Django can be configured to make +<django.http.HttpRequest.META>` attribute. Django can be configured to make use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` or ``PersistentRemoteUserMiddleware``, and :class:`~django.contrib.auth.backends.RemoteUserBackend` classes found in @@ -76,7 +76,7 @@ regardless of ``AUTHENTICATION_BACKENDS``. If your authentication mechanism uses a custom HTTP header and not ``REMOTE_USER``, you can subclass ``RemoteUserMiddleware`` and set the -``header`` attribute to the desired ``request.META`` key. For example: +``header`` attribute to the desired ``request.META`` key. For example: .. code-block:: python :caption: ``mysite/middleware.py`` diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 915c4e9c37..908c937151 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -33,7 +33,7 @@ easier to follow, we'll use a consistent example throughout this document: wrapping a Python object representing the deal of cards in a hand of Bridge_. Don't worry, you don't have to know how to play Bridge to follow this example. You only need to know that 52 cards are dealt out equally to four players, who -are traditionally called *north*, *east*, *south* and *west*. Our class looks +are traditionally called *north*, *east*, *south* and *west*. Our class looks something like this:: class Hand: diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 4038bb5184..1154e45515 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -264,7 +264,7 @@ Template filter code falls into one of two situations: reviewing your code. Marking a filter ``is_safe`` will coerce the filter's return value to - a string. If your filter should return a boolean or other non-string + a string. If your filter should return a boolean or other non-string value, marking it ``is_safe`` will probably have unintended consequences (such as converting a boolean False to the string 'False'). @@ -841,7 +841,7 @@ 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 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 +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 @@ -1159,7 +1159,7 @@ Now your tag should begin to look like this:: return FormatTimeNode(date_to_be_formatted, format_string[1:-1]) 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 +``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, instantiate it with the name of the variable to diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt index b4cfd03df7..930e933f0e 100644 --- a/docs/howto/static-files/index.txt +++ b/docs/howto/static-files/index.txt @@ -3,7 +3,7 @@ How to manage static files (e.g. images, JavaScript, CSS) ========================================================= Websites generally need to serve additional files such as images, JavaScript, -or CSS. In Django, we refer to these files as "static files". Django provides +or CSS. In Django, we refer to these files as "static files". Django provides :mod:`django.contrib.staticfiles` to help you manage them. This page describes how you can serve these static files. diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 0a80ea5f28..d117b2e165 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -5,7 +5,7 @@ Reporting bugs and requesting features .. Important:: Please report security issues **only** to - security@djangoproject.com. This is a private list only open to + security@djangoproject.com. This is a private list only open to long-time, highly trusted Django developers, and its archives are not public. For further details, please see :doc:`our security policies </internals/security>`. diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 031074c3fa..b5dc17fd6a 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -1295,7 +1295,7 @@ details on these changes. </topics/class-based-views/index>`. * The ``django.core.servers.basehttp.AdminMediaHandler`` will be - removed. In its place use + removed. In its place use ``django.contrib.staticfiles.handlers.StaticFilesHandler``. * The template tags library ``adminmedia`` and the template tag ``{% @@ -1358,7 +1358,7 @@ details on these changes. See the :ref:`Django 1.2 release notes<deprecated-features-1.2>` for more details on these changes. -* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` will be removed. Use +* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` will be removed. Use the ``{% csrf_token %}`` template tag inside forms to enable CSRF protection. ``CsrfViewMiddleware`` remains and is enabled by default. @@ -1386,7 +1386,7 @@ details on these changes. * The ``Message`` model (in ``django.contrib.auth``), its related manager in the ``User`` model (``user.message_set``), and the associated methods (``user.message_set.create()`` and - ``user.get_and_delete_messages()``), will be removed. The + ``user.get_and_delete_messages()``), will be removed. The :doc:`messages framework </ref/contrib/messages>` should be used instead. The related ``messages`` variable returned by the auth context processor will also be removed. Note that this @@ -1398,7 +1398,7 @@ details on these changes. will no longer be checked and can be removed from custom backends. * Authentication backends will need to support the ``AnonymousUser`` class - being passed to all methods dealing with permissions. The + being passed to all methods dealing with permissions. The ``supports_anonymous_user`` variable will no longer be checked and can be removed from custom backends. @@ -1425,7 +1425,7 @@ details on these changes. ``django.contrib.syndication`` will be removed. The class-based view ``views.Feed`` should be used instead. -* ``django.core.context_processors.auth``. This release will +* ``django.core.context_processors.auth``. This release will remove the old method in favor of the new method in ``django.contrib.auth.context_processors.auth``. @@ -1456,7 +1456,7 @@ details on these changes. See the :ref:`Django 1.1 release notes<deprecated-features-1.1>` for more details on these changes. -* ``AdminSite.root()``. This method of hooking up the admin URLs will be +* ``AdminSite.root()``. This method of hooking up the admin URLs will be removed in favor of including ``admin.site.urls``. * Authentication backends need to define the boolean attributes diff --git a/docs/internals/mailing-lists.txt b/docs/internals/mailing-lists.txt index a88a1d3edf..c8e074c2df 100644 --- a/docs/internals/mailing-lists.txt +++ b/docs/internals/mailing-lists.txt @@ -5,7 +5,7 @@ Mailing lists and Forum .. Important:: Please report security issues **only** to - security@djangoproject.com. This is a private list only open to + security@djangoproject.com. This is a private list only open to long-time, highly trusted Django developers, and its archives are not public. For further details, please see :doc:`our security policies </internals/security>`. diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 504480acb1..fc968ebf8f 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -91,7 +91,7 @@ These files are: read :ref:`more about packages <tut-packages>` in the official Python docs. * :file:`mysite/settings.py`: Settings/configuration for this Django - project. :doc:`/topics/settings` will tell you all about how settings + project. :doc:`/topics/settings` will tell you all about how settings work. * :file:`mysite/urls.py`: The URL declarations for this Django project; a diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt index 599f81f85c..80804ac9b2 100644 --- a/docs/intro/tutorial05.txt +++ b/docs/intro/tutorial05.txt @@ -352,7 +352,7 @@ The Django test client ---------------------- Django provides a test :class:`~django.test.Client` to simulate a user -interacting with the code at the view level. We can use it in ``tests.py`` +interacting with the code at the view level. We can use it in ``tests.py`` or even in the :djadmin:`shell`. We will start again with the :djadmin:`shell`, where we need to do a couple of diff --git a/docs/intro/tutorial07.txt b/docs/intro/tutorial07.txt index bf695d551c..14752e3285 100644 --- a/docs/intro/tutorial07.txt +++ b/docs/intro/tutorial07.txt @@ -159,7 +159,7 @@ by ``extra`` -- and each time you come back to the "Change" page for an already-created object, you get another three extra slots. At the end of the three current slots you will find an "Add another Choice" -link. If you click on it, a new slot will be added. If you want to remove the +link. If you click on it, a new slot will be added. If you want to remove the added slot, you can click on the X to the top right of the added slot. This image shows an added slot: diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt index 3643c51d76..af27bf02d7 100644 --- a/docs/misc/design-philosophies.txt +++ b/docs/misc/design-philosophies.txt @@ -310,7 +310,7 @@ The core goals of Django's :doc:`cache framework </topics/cache>` are: Less code --------- -A cache should be as fast as possible. Hence, all framework code surrounding +A cache should be as fast as possible. Hence, all framework code surrounding the cache backend should be kept to the absolute minimum, especially for ``get()`` operations. diff --git a/docs/misc/distributions.txt b/docs/misc/distributions.txt index df7b074d1a..64b4f3d88e 100644 --- a/docs/misc/distributions.txt +++ b/docs/misc/distributions.txt @@ -16,7 +16,7 @@ instructions for :ref:`installing the development version If you're using Linux or a Unix installation, such as OpenSolaris, check with your distributor to see if they already package Django. If you're using a Linux distro and don't know how to find out if a package -is available, then now is a good time to learn. The Django Wiki contains +is available, then now is a good time to learn. The Django Wiki contains a list of `Third Party Distributions`_ to help you out. .. _`Third Party Distributions`: https://code.djangoproject.com/wiki/Distributions diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index f0a23ffc7b..ebc2a11a80 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -37,9 +37,9 @@ Simple mixins .. admonition:: Use ``alters_data`` where appropriate Note that having the view instance in the template context may - expose potentially hazardous methods to template authors. To + expose potentially hazardous methods to template authors. To prevent methods like this from being called in the template, set - ``alters_data=True`` on those methods. For more information, read + ``alters_data=True`` on those methods. For more information, read the documentation on :ref:`rendering a template context <alters-data-description>`. diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index 0c8dc0339d..8e98bac5ee 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -6,7 +6,7 @@ Clickjacking Protection :synopsis: Protects against Clickjacking The clickjacking middleware and decorators provide easy-to-use protection -against `clickjacking`_. This type of attack occurs when a malicious site +against `clickjacking`_. This type of attack occurs when a malicious site tricks a user into clicking on a concealed element of another site which they have loaded in a hidden frame or iframe. diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 34bbb7942d..57183fa483 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1153,7 +1153,7 @@ subclass:: The ``raw_id_fields`` ``Input`` widget should contain a primary key if the field is a ``ForeignKey`` or a comma separated list of values if the field - is a ``ManyToManyField``. The ``raw_id_fields`` widget shows a magnifying + is a ``ManyToManyField``. The ``raw_id_fields`` widget shows a magnifying glass button next to the field which allows users to search for and select a value: @@ -1355,9 +1355,9 @@ subclass:: Custom template options ~~~~~~~~~~~~~~~~~~~~~~~ -The :ref:`admin-overriding-templates` section describes how to override or extend -the default admin templates. Use the following options to override the default -templates used by the :class:`ModelAdmin` views: +The :ref:`admin-overriding-templates` section describes how to override or +extend the default admin templates. Use the following options to override the +default templates used by the :class:`ModelAdmin` views: .. attribute:: ModelAdmin.add_form_template @@ -1660,7 +1660,7 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.get_urls() The ``get_urls`` method on a ``ModelAdmin`` returns the URLs to be used for - that ModelAdmin in the same way as a URLconf. Therefore you can extend + that ModelAdmin in the same way as a URLconf. Therefore you can extend them as documented in :doc:`/topics/http/urls`, using the ``AdminSite.admin_view()`` wrapper on your views:: @@ -1970,7 +1970,7 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False) Sends a message to the user using the :mod:`django.contrib.messages` - backend. See the :ref:`custom ModelAdmin example <custom-admin-action>`. + backend. See the :ref:`custom ModelAdmin example <custom-admin-action>`. Keyword arguments allow you to change the message level, add extra CSS tags, or fail silently if the ``contrib.messages`` framework is not diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 56c33c40b6..6f35b9fa98 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -604,9 +604,9 @@ The following backends are available in :mod:`django.contrib.auth.backends`: .. class:: ModelBackend - This is the default authentication backend used by Django. It + This is the default authentication backend used by Django. It authenticates using credentials consisting of a user identifier and - password. For Django's default user model, the user identifier is the + password. For Django's default user model, the user identifier is the username, for custom user models it is the field specified by USERNAME_FIELD (see :doc:`Customizing Users and authentication </topics/auth/customizing>`). @@ -751,8 +751,8 @@ The following backends are available in :mod:`django.contrib.auth.backends`: .. class:: RemoteUserBackend Use this backend to take advantage of external-to-Django-handled - authentication. It authenticates using usernames passed in - :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See + authentication. It authenticates using usernames passed in + :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>` documentation. diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index eeb6ca0513..fe3cea63f8 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -19,13 +19,13 @@ auto-generated model definition, where appropriate. The ``ogrinspect`` management command will inspect the given OGR-compatible :class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will -output a GeoDjango model with the given model name. There's a detailed example +output a GeoDjango model with the given model name. There's a detailed example of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. .. django-admin-option:: --blank BLANK Use a comma separated list of OGR field names to add the ``blank=True`` - keyword option to the field definition. Set with ``true`` to apply + keyword option to the field definition. Set with ``true`` to apply to all applicable fields. .. django-admin-option:: --decimal DECIMAL @@ -73,10 +73,10 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. .. django-admin-option:: --null NULL Use a comma separated list of OGR field names to add the ``null=True`` - keyword option to the field definition. Set with ``true`` to apply to + keyword option to the field definition. Set with ``true`` to apply to all applicable fields. .. django-admin-option:: --srid SRID - The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts + The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts to automatically determine of the SRID of the data source. diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index be7e5440b4..cf26978169 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -141,7 +141,7 @@ Spatial Lookups =============== GeoDjango's lookup types may be used with any manager method like -``filter()``, ``exclude()``, etc. However, the lookup types unique to +``filter()``, ``exclude()``, etc. However, the lookup types unique to GeoDjango are only available on spatial fields. Filters on 'normal' fields (e.g. :class:`~django.db.models.CharField`) @@ -233,9 +233,9 @@ Introduction ------------ Distance calculations with spatial data is tricky because, unfortunately, -the Earth is not flat. Some distance queries with fields in a geographic +the Earth is not flat. Some distance queries with fields in a geographic coordinate system may have to be expressed differently because of -limitations in PostGIS. Please see the :ref:`selecting-an-srid` section +limitations in PostGIS. Please see the :ref:`selecting-an-srid` section in the :doc:`model-api` documentation for more details. .. _distance-lookups-intro: @@ -273,7 +273,7 @@ to be in the units of the field. In PostGIS, ``ST_Distance_Sphere`` does *not* limit the geometry types geographic distance queries are performed with. [#fndistsphere15]_ However, these queries may take a long time, as great-circle distances must be - calculated on the fly for *every* row in the query. This is because the + calculated on the fly for *every* row in the query. This is because the spatial index on traditional geometry fields cannot be used. For much better performance on WGS84 distance queries, consider using diff --git a/docs/ref/contrib/gis/deployment.txt b/docs/ref/contrib/gis/deployment.txt index 3c8b415a0f..05e7e15baf 100644 --- a/docs/ref/contrib/gis/deployment.txt +++ b/docs/ref/contrib/gis/deployment.txt @@ -9,11 +9,11 @@ the deployment of a normal Django application. Please consult Django's .. warning:: GeoDjango uses the GDAL geospatial library which is - not thread safe at this time. Thus, it is *highly* recommended + not thread safe at this time. Thus, it is *highly* recommended to not use threading when deploying -- in other words, use an appropriate configuration of Apache. For example, when configuring your application with ``mod_wsgi``, set the ``WSGIDaemonProcess`` attribute ``threads`` to ``1``, unless - Apache may crash when running your GeoDjango application. Increase the + Apache may crash when running your GeoDjango application. Increase the number of ``processes`` instead. diff --git a/docs/ref/contrib/gis/feeds.txt b/docs/ref/contrib/gis/feeds.txt index 3f17a68574..ded9b3d76d 100644 --- a/docs/ref/contrib/gis/feeds.txt +++ b/docs/ref/contrib/gis/feeds.txt @@ -7,7 +7,7 @@ Geographic Feeds GeoDjango has its own :class:`Feed` subclass that may embed location information in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or -`W3C Geo`_ standards. Because GeoDjango's syndication API is a superset of +`W3C Geo`_ standards. Because GeoDjango's syndication API is a superset of Django's, please consult :doc:`Django's syndication documentation </ref/contrib/syndication>` for details on general usage. diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index 8c9c1cf82f..d65f52d9d8 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/docs/ref/contrib/gis/functions.txt @@ -349,7 +349,7 @@ scaled coordinates by multiplying them with the ``x``, ``y``, and optionally SpatiaLite Accepts a single geographic field or expression and returns a geometry with all -points snapped to the given grid. How the geometry is snapped to the grid +points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given. @@ -376,7 +376,7 @@ the transformed geometry to the spatial reference system specified by the .. note:: What spatial reference system an integer SRID corresponds to may depend on - the spatial database used. In other words, the SRID numbers used for Oracle + the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS. ``Translate`` diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index b7e617cfec..9d10452305 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/docs/ref/contrib/gis/gdal.txt @@ -6,7 +6,7 @@ GDAL API :synopsis: GeoDjango's high-level interface to the GDAL library. `GDAL`__ stands for **Geospatial Data Abstraction Library**, -and is a veritable "Swiss army knife" of GIS data functionality. A subset +and is a veritable "Swiss army knife" of GIS data functionality. A subset of GDAL is the `OGR`__ Simple Features Library, which specializes in reading and writing vector geographic data in a variety of standard formats. @@ -34,7 +34,7 @@ Sample Data 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 +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 data sets that you can use for testing. You can download them here: @@ -51,9 +51,9 @@ 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 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` +one or more layers of data. Each layer, represented by a :class:`Layer` object, contains some number of geographic features (:class:`Feature`), information about the type of features contained in that layer (e.g. points, polygons, etc.), as well as the names and types of any @@ -285,7 +285,7 @@ __ https://gdal.org/drivers/vector/ .. method:: test_capability(capability) Returns a boolean indicating whether this layer supports the given - capability (a string). Examples of valid capability strings include: + capability (a string). Examples of valid capability strings include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``, ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``, ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and @@ -673,7 +673,7 @@ coordinate transformation: This property controls the spatial reference for this geometry, or ``None`` if no spatial reference system has been assigned to it. If assigned, accessing this property returns a :class:`SpatialReference` - object. It may be set with another :class:`SpatialReference` object, + object. It may be set with another :class:`SpatialReference` object, or any input that :class:`SpatialReference` accepts. Example: .. code-block:: pycon @@ -684,7 +684,7 @@ coordinate transformation: .. attribute:: srid Returns or sets the spatial reference identifier corresponding to - :class:`SpatialReference` of this geometry. Returns ``None`` if + :class:`SpatialReference` of this geometry. Returns ``None`` if there is no spatial reference information associated with this geometry, or if an SRID cannot be determined. @@ -1274,9 +1274,9 @@ 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 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 +one or more layers of data named bands. Each band, represented by a :class:`GDALBand` object, contains georeferenced image data. For example, an RGB image is represented as three bands: one for red, one for green, and one for blue. @@ -2140,7 +2140,7 @@ Settings ``GDAL_LIBRARY_PATH`` --------------------- -A string specifying the location of the GDAL library. Typically, +A string specifying the location of the GDAL library. Typically, this setting is only used if the GDAL library is in a non-standard location (e.g., ``/home/john/lib/libgdal.so``). diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index 1ab0f7c309..d31a057863 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -13,7 +13,7 @@ The spatial lookups in this section are available for :class:`GeometryField` and :class:`RasterField`. For an introduction, see the :ref:`spatial lookups introduction -<spatial-lookups-intro>`. For an overview of what lookups are +<spatial-lookups-intro>`. For an overview of what lookups are compatible with a particular spatial backend, refer to the :ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`. @@ -454,18 +454,18 @@ SpatiaLite ``Overlaps(poly, geom)`` MariaDB, Oracle, SpatiaLite, PGRaster (Conversion) Tests if the geometry field is spatially related to the lookup geometry by -the values given in the given pattern. This lookup requires a tuple parameter, +the values given in the given pattern. This lookup requires a tuple parameter, ``(geom, pattern)``; the form of ``pattern`` will depend on the spatial backend: MariaDB, PostGIS, and SpatiaLite ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On these spatial backends the intersection pattern is a string comprising -nine characters, which define intersections between the interior, boundary, -and exterior of the geometry field and the lookup geometry. -The intersection pattern matrix may only use the following characters: -``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune" -a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_ +On these spatial backends the intersection pattern is a string comprising nine +characters, which define intersections between the interior, boundary, and +exterior of the geometry field and the lookup geometry. The intersection +pattern matrix may only use the following characters: ``1``, ``2``, ``T``, +``F``, or ``*``. This lookup type allows users to "fine tune" a specific +geometric relationship consistent with the DE-9IM model. [#fnde9im]_ Geometry example:: @@ -503,7 +503,7 @@ Oracle Here the relation pattern is comprised of at least one of the nine relation strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, ``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and -``ANYINTERACT``. Multiple strings may be combined with the logical Boolean +``ANYINTERACT``. Multiple strings may be combined with the logical Boolean operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation strings are case-insensitive. @@ -894,7 +894,7 @@ use these aggregate functions, see :doc:`the topic guide on aggregation ===================== ===================================================== Keyword Argument Description ===================== ===================================================== -``tolerance`` This keyword is for Oracle only. It is for the +``tolerance`` This keyword is for Oracle only. It is for the tolerance value used by the ``SDOAGGRTYPE`` procedure; the `Oracle documentation`__ has more details. diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index 58097434e8..a17edb6390 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -12,7 +12,7 @@ What is GEOS? ------------- `GEOS`__ stands for **Geometry Engine - Open Source**, -and is a C++ library, ported from the `Java Topology Suite`__. GEOS +and is a C++ library, ported from the `Java Topology Suite`__. GEOS implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions and spatial operators. GEOS, now an OSGeo project, was initially developed and maintained by `Refractions Research`__ of Victoria, Canada. @@ -30,8 +30,8 @@ features include: * A BSD-licensed interface to the GEOS geometry routines, implemented purely in Python using ``ctypes``. -* Loosely-coupled to GeoDjango. For example, :class:`GEOSGeometry` objects - may be used outside of a Django project/application. In other words, +* Loosely-coupled to GeoDjango. For example, :class:`GEOSGeometry` objects + may be used outside of a Django project/application. In other words, no need to have :envvar:`DJANGO_SETTINGS_MODULE` set or use a database, etc. * Mutability: :class:`GEOSGeometry` objects may be modified. * Cross-platform tested. @@ -47,7 +47,7 @@ This section contains a brief introduction and tutorial to using Creating a Geometry ------------------- -:class:`GEOSGeometry` objects may be created in a few ways. The first is +:class:`GEOSGeometry` objects may be created in a few ways. The first is to simply instantiate the object on some spatial input -- the following are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON: @@ -66,7 +66,7 @@ are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON: ... ) # GeoJSON Another option is to use the constructor for the specific geometry type -that you wish to create. For example, a :class:`Point` object may be +that you wish to create. For example, a :class:`Point` object may be created by passing in the X and Y coordinates into its constructor: .. code-block:: pycon @@ -127,8 +127,8 @@ may be used to get the geometry coordinates as a Python tuple: (5.0, 23.0) You can get/set geometry components using standard Python indexing -techniques. However, what is returned depends on the geometry type -of the object. For example, indexing on a :class:`LineString` +techniques. However, what is returned depends on the geometry type +of the object. For example, indexing on a :class:`LineString` returns a coordinate tuple: .. code-block:: pycon @@ -212,7 +212,7 @@ Geometry Objects :param srid: spatial reference identifier :type srid: int -This is the base class for all GEOS geometry objects. It initializes on the +This is the base class for all GEOS geometry objects. It initializes on the given ``geo_input`` argument, and then assumes the proper geometry subclass (e.g., ``GEOSGeometry('POINT(1 1)')`` will create a :class:`Point` object). @@ -275,7 +275,7 @@ Properties .. attribute:: GEOSGeometry.geom_type - Returns a string corresponding to the type of geometry. For example: + Returns a string corresponding to the type of geometry. For example: .. code-block:: pycon @@ -285,7 +285,7 @@ Properties .. attribute:: GEOSGeometry.geom_typeid - Returns the GEOS geometry type identification number. The following table + Returns the GEOS geometry type identification number. The following table shows the value for each geometry type: =========================== ======== @@ -307,7 +307,7 @@ Properties .. attribute:: GEOSGeometry.num_geom - Returns the number of geometries in this geometry. In other words, will + Returns the number of geometries in this geometry. In other words, will return 1 on anything but geometry collections. .. attribute:: GEOSGeometry.hasz @@ -329,7 +329,7 @@ Properties Returns a boolean indicating whether the geometry is 'simple'. A geometry is simple if and only if it does not intersect itself (except at boundary - points). For example, a :class:`LineString` object is not simple if it + points). For example, a :class:`LineString` object is not simple if it intersects itself. Thus, :class:`LinearRing` and :class:`Polygon` objects are always simple because they cannot intersect themselves, by definition. @@ -344,7 +344,7 @@ Properties .. attribute:: GEOSGeometry.srid Property that may be used to retrieve or set the SRID associated with the - geometry. For example: + geometry. For example: .. code-block:: pycon @@ -359,12 +359,12 @@ Output Properties ~~~~~~~~~~~~~~~~~ The properties in this section export the :class:`GEOSGeometry` object into -a different. This output may be in the form of a string, buffer, or even +a different. This output may be in the form of a string, buffer, or even another object. .. attribute:: GEOSGeometry.ewkt - Returns the "extended" Well-Known Text of the geometry. This representation + Returns the "extended" Well-Known Text of the geometry. This representation is specific to PostGIS and is a superset of the OGC WKT standard. [#fnogc]_ Essentially the SRID is prepended to the WKT representation, for example ``SRID=4326;POINT(5 23)``. @@ -376,14 +376,14 @@ another object. .. attribute:: GEOSGeometry.hex - Returns the WKB of this Geometry in hexadecimal form. Please note + Returns the WKB of this Geometry in hexadecimal form. Please note that the SRID value is not included in this representation because it is not a part of the OGC specification (use the :attr:`GEOSGeometry.hexewkb` property instead). .. attribute:: GEOSGeometry.hexewkb - Returns the EWKB of this Geometry in hexadecimal form. This is an + Returns the EWKB of this Geometry in hexadecimal form. This is an extension of the WKB specification that includes the SRID value that are a part of this geometry. @@ -400,7 +400,7 @@ another object. .. attribute:: GEOSGeometry.kml Returns a `KML`__ (Keyhole Markup Language) representation of the - geometry. This should only be used for geometries with an SRID of + geometry. This should only be used for geometries with an SRID of 4326 (WGS84), but this restriction is not enforced. .. attribute:: GEOSGeometry.ogr @@ -413,7 +413,7 @@ another object. .. attribute:: GEOSGeometry.wkb Returns the WKB (Well-Known Binary) representation of this Geometry - as a Python buffer. SRID value is not included, use the + as a Python buffer. SRID value is not included, use the :attr:`GEOSGeometry.ewkb` property instead. .. _ewkb: @@ -483,7 +483,7 @@ return a boolean. .. method:: GEOSGeometry.equals_exact(other, tolerance=0) Returns true if the two geometries are exactly equal, up to a - specified tolerance. The ``tolerance`` value should be a floating + specified tolerance. The ``tolerance`` value should be a floating point number representing the error tolerance in the comparison, e.g., ``poly1.equals_exact(poly2, 0.001)`` will compare equality to within one thousandth of a unit. @@ -608,7 +608,7 @@ Topological Properties .. attribute:: GEOSGeometry.centroid Returns a :class:`Point` object representing the geometric center of - the geometry. The point is not guaranteed to be on the interior + the geometry. The point is not guaranteed to be on the interior of the geometry. .. attribute:: GEOSGeometry.convex_hull @@ -809,7 +809,7 @@ Other Properties & Methods .. class:: Polygon(*args, **kwargs) ``Polygon`` objects may be instantiated by passing in parameters that - represent the rings of the polygon. The parameters must either be + represent the rings of the polygon. The parameters must either be :class:`LinearRing` instances, or a sequence that may be used to construct a :class:`LinearRing`: @@ -922,12 +922,13 @@ Prepared Geometries =================== 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 -geometry can be orders of magnitude faster -- the more complex the geometry -that is prepared, the larger the speedup in the operation. For more information, -please consult the `GEOS wiki page on prepared geometries <https://trac.osgeo.org/geos/wiki/PreparedGeometry>`_. +: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 geometry can be orders +of magnitude faster -- the more complex the geometry that is prepared, the +larger the speedup in the operation. For more information, please consult the +`GEOS wiki page on prepared geometries +<https://trac.osgeo.org/geos/wiki/PreparedGeometry>`_. For example: @@ -1034,14 +1035,14 @@ Writer Objects -------------- All writer objects have a ``write(geom)`` method that returns either the -WKB or WKT of the given geometry. In addition, :class:`WKBWriter` objects +WKB or WKT of the given geometry. In addition, :class:`WKBWriter` objects also have properties that may be used to change the byte order, and or include the SRID value (in other words, EWKB). .. class:: WKBWriter(dim=2) - ``WKBWriter`` provides the most control over its output. By default it - returns OGC-compliant WKB when its ``write`` method is called. However, + ``WKBWriter`` provides the most control over its output. By default it + returns OGC-compliant WKB when its ``write`` method is called. However, it has properties that allow for the creation of EWKB, a superset of the WKB standard that includes additional information. See the :attr:`WKBWriter.outdim` documentation for more details about the ``dim`` @@ -1062,7 +1063,7 @@ include the SRID value (in other words, EWKB). .. method:: WKBWriter.write_hex(geom) - Returns WKB of the geometry in hexadecimal. Example: + Returns WKB of the geometry in hexadecimal. Example: .. code-block:: pycon @@ -1099,7 +1100,7 @@ include the SRID value (in other words, EWKB). .. attribute:: WKBWriter.outdim This property may be set to change the output dimension of the geometry - representation. In other words, if you have a 3D geometry then set to 3 + representation. In other words, if you have a 3D geometry then set to 3 so that the Z value is included in the WKB. ============ =========================== @@ -1127,7 +1128,7 @@ include the SRID value (in other words, EWKB). .. attribute:: WKBWriter.srid Set this property with a boolean to indicate whether the SRID of the - geometry should be included with the WKB representation. Example: + geometry should be included with the WKB representation. Example: .. code-block:: pycon @@ -1210,7 +1211,7 @@ Settings ``GEOS_LIBRARY_PATH`` --------------------- -A string specifying the location of the GEOS C library. Typically, +A string specifying the location of the GEOS C library. Typically, this setting is only used if the GEOS C library is in a non-standard location (e.g., ``/home/bob/lib/libgeos_c.so``). diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index eedf11f83c..2f3f6024bf 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -80,7 +80,7 @@ Building from source When installing from source on UNIX and GNU/Linux systems, please follow the installation instructions carefully, and install the libraries in the -given order. If using MySQL or Oracle as the spatial database, only GEOS +given order. If using MySQL or Oracle as the spatial database, only GEOS is required. .. note:: @@ -106,7 +106,7 @@ GEOS GEOS is a C++ library for performing geometric operations, and is the default internal geometry representation used by GeoDjango (it's behind the "lazy" -geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) +geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) directly from Python using ctypes. First, download GEOS from the GEOS website and untar the source archive: @@ -158,7 +158,7 @@ If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binut If your GEOS library is in a non-standard location, or you don't want to modify the system's library path then the :setting:`GEOS_LIBRARY_PATH` setting may be added to your Django settings file with the full path to the -GEOS C library. For example: +GEOS C library. For example: .. code-block:: shell @@ -231,7 +231,7 @@ GDAL ---- `GDAL`__ is an excellent open source geospatial library that has support for -reading most vector and raster spatial data formats. Currently, GeoDjango only +reading most vector and raster spatial data formats. Currently, GeoDjango only supports :doc:`GDAL's vector data <../gdal>` capabilities [#]_. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL. @@ -284,7 +284,7 @@ When GeoDjango can't find the GDAL library, configure your :ref:`libsettings` If your GDAL library is in a non-standard location, or you don't want to modify the system's library path then the :setting:`GDAL_LIBRARY_PATH` setting may be added to your Django settings file with the full path to -the GDAL library. For example: +the GDAL library. For example: .. code-block:: shell diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index e7971ca2b4..b1d91119f4 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -21,9 +21,9 @@ then inserting into a GeoDjango model. .. warning :: - GIS data sources, like shapefiles, may be very large. If you find + GIS data sources, like shapefiles, may be very large. If you find that :class:`LayerMapping` is using too much memory, set - :setting:`DEBUG` to ``False`` in your settings. When :setting:`DEBUG` + :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 -- and when SQL statements contain geometries, this may consume more memory than is typical. @@ -83,7 +83,7 @@ Example 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 +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. @@ -101,7 +101,7 @@ Argument Description ``model`` The geographic model, *not* an instance. ``data_source`` The path to the OGR-supported data source file - (e.g., a shapefile). Also accepts + (e.g., a shapefile). Also accepts :class:`django.contrib.gis.gdal.DataSource` instances. ``mapping`` A dictionary: keys are strings corresponding to @@ -120,12 +120,12 @@ Keyword Arguments ``source_srs`` Use this to specify the source SRS manually (for example, some shapefiles don't come with a ``'.prj'`` - file). An integer SRID, WKT or PROJ strings, and + file). An integer SRID, WKT or PROJ strings, and :class:`django.contrib.gis.gdal.SpatialReference` objects are accepted. ``encoding`` Specifies the character set encoding of the strings - in the OGR data source. For example, ``'latin-1'``, + in the OGR data source. For example, ``'latin-1'``, ``'utf-8'``, and ``'cp437'`` are all valid encoding parameters. @@ -133,7 +133,7 @@ Keyword Arguments ``'autocommit'``. ``transform`` Setting this to False will disable coordinate - transformations. In other words, geometries will + transformations. In other words, geometries will be inserted into the database unmodified from their original state in the data source. @@ -141,7 +141,7 @@ Keyword Arguments from the given model will create models unique only to the given name(s). Geometries from each feature will be added into the collection - associated with the unique model. Forces + associated with the unique model. Forces the transaction mode to be ``'autocommit'``. ``using`` Sets the database to use when importing spatial data. @@ -153,7 +153,7 @@ Keyword Arguments .. method:: LayerMapping.save(verbose=False, fid_range=False, step=False, progress=False, silent=False, stream=sys.stdout, strict=False) -The ``save()`` method also accepts keywords. These keywords are +The ``save()`` method also accepts keywords. These keywords are used for controlling output logging, error handling, and for importing specific feature ranges. @@ -162,14 +162,14 @@ Save Keyword Arguments Description =========================== ================================================= ``fid_range`` May be set with a slice or tuple of (begin, end) feature ID's to map from - the data source. In other words, this + the data source. In other words, this keyword enables the user to selectively import a subset range of features in the geographic data source. ``progress`` When this keyword is set, status information will be printed giving the number of features - processed and successfully saved. By default, + processed and successfully saved. By default, progress information will be printed every 1000 features processed, however, this default may be overridden by setting this keyword with an @@ -186,11 +186,11 @@ Save Keyword Arguments Description ``stream`` Status information will be written to this file - handle. Defaults to using ``sys.stdout``, but + handle. Defaults to using ``sys.stdout``, but any object with a ``write`` method is supported. ``strict`` Execution of the model mapping will cease upon - the first error encountered. The default value + the first error encountered. The default value (``False``) behavior is to attempt to continue. @@ -206,7 +206,7 @@ Running out of memory --------------------- As noted in the warning at the top of this section, Django stores all SQL -queries when ``DEBUG=True``. Set ``DEBUG=False`` in your settings, and this +queries when ``DEBUG=True``. Set ``DEBUG=False`` in your settings, and this should stop excessive memory use when running ``LayerMapping`` scripts. MySQL: ``max_allowed_packet`` error @@ -219,7 +219,7 @@ If you encounter the following error when using ``LayerMapping`` and MySQL: OperationalError: (1153, "Got a packet bigger than 'max_allowed_packet' bytes") Then the solution is to increase the value of the ``max_allowed_packet`` -setting in your MySQL configuration. For example, the default value may +setting in your MySQL configuration. For example, the default value may be something low like one megabyte -- the setting may be modified in MySQL's configuration file (``my.cnf``) in the ``[mysqld]`` section: diff --git a/docs/ref/contrib/gis/measure.txt b/docs/ref/contrib/gis/measure.txt index 1d88ba129d..6073b7dc90 100644 --- a/docs/ref/contrib/gis/measure.txt +++ b/docs/ref/contrib/gis/measure.txt @@ -14,9 +14,10 @@ Specifically, it implements two objects, :class:`Distance` and Example ======= -:class:`Distance` objects may be instantiated using a keyword argument indicating the -context of the units. In the example below, two different distance objects are -instantiated in units of kilometers (``km``) and miles (``mi``): +:class:`Distance` objects may be instantiated using a keyword argument +indicating the context of the units. In the example below, two different +distance objects are instantiated in units of kilometers (``km``) and miles +(``mi``): .. code-block:: pycon diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index 981581cbf2..1b6ec1d543 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -5,7 +5,7 @@ GeoDjango Model API .. module:: django.contrib.gis.db.models :synopsis: GeoDjango model and field API. -This document explores the details of the GeoDjango Model API. Throughout this +This document explores the details of the GeoDjango Model API. Throughout this section, we'll be using the following geographic model of a `ZIP code`__ and of a `Digital Elevation Model`__ as our examples:: @@ -120,32 +120,33 @@ Selecting an SRID ~~~~~~~~~~~~~~~~~ Choosing an appropriate SRID for your model is an important decision that the -developer should consider carefully. The SRID is an integer specifier that +developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [#fnsrid]_ Projection systems give the context to the -coordinates that specify a location. Although the details of `geodesy`__ are +coordinates that specify a location. Although the details of `geodesy`__ are beyond the scope of this documentation, the general problem is that the earth is spherical and representations of the earth (e.g., paper maps, web maps) are not. Most people are familiar with using latitude and longitude to reference a -location on the earth's surface. However, latitude and longitude are angles, -not distances. In other words, while the shortest path between two points on -a flat surface is a straight line, the shortest path between two points on a curved -surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_ Thus, -additional computation is required to obtain distances in planar units (e.g., -kilometers and miles). Using a geographic coordinate system may introduce -complications for the developer later on. For example, SpatiaLite does not have -the capability to perform distance calculations between geometries using -geographic coordinate systems, e.g. constructing a query to find all points -within 5 miles of a county boundary stored as WGS84. -[#fndist]_ +location on the earth's surface. However, latitude and longitude are angles, +not distances. In other words, while the shortest path between two points on a +flat surface is a straight line, the shortest path between two points on a +curved surface (such as the earth) is an *arc* of a `great circle`__. +[#fnthematic]_ + +Thus, additional computation is required to obtain distances in planar units +(e.g., kilometers and miles). Using a geographic coordinate system may +introduce complications for the developer later on. For example, SpatiaLite +does not have the capability to perform distance calculations between +geometries using geographic coordinate systems, e.g. constructing a query to +find all points within 5 miles of a county boundary stored as WGS84. [#fndist]_ Portions of the earth's surface may projected onto a two-dimensional, or -Cartesian, plane. Projected coordinate systems are especially convenient -for region-specific applications, e.g., if you know that your database will -only cover geometries in `North Kansas`__, then you may consider using projection -system specific to that region. Moreover, projected coordinate systems are +Cartesian, plane. Projected coordinate systems are especially convenient for +region-specific applications, e.g., if you know that your database will only +cover geometries in `North Kansas`__, then you may consider using projection +system specific to that region. Moreover, projected coordinate systems are defined in Cartesian units (such as meters or feet), easing distance calculations. @@ -161,7 +162,7 @@ Additional Resources: * `spatialreference.org`__: A Django-powered database of spatial reference systems. * `The State Plane Coordinate System`__: A website covering the various - projection systems used in the United States. Much of the U.S. spatial + projection systems used in the United States. Much of the U.S. spatial data encountered will be in one of these coordinate systems rather than in a geographic coordinate system such as WGS84. @@ -176,14 +177,14 @@ __ https://web.archive.org/web/20080302095452/http://welcome.warnercnr.colostate .. attribute:: BaseSpatialField.spatial_index -Defaults to ``True``. Creates a spatial index for the given geometry +Defaults to ``True``. Creates a spatial index for the given geometry field. .. note:: This is different from the ``db_index`` field option because spatial indexes are created in a different manner than regular database - indexes. Specifically, spatial indexes are typically created using + indexes. Specifically, spatial indexes are typically created using a variant of the R-Tree, while regular database indexes typically use B-Trees. @@ -201,8 +202,8 @@ options are optional. .. attribute:: GeometryField.dim This option may be used for customizing the coordinate dimension of the -geometry field. By default, it is set to 2, for representing two-dimensional -geometries. For spatial backends that support it, it may be set to 3 for +geometry field. By default, it is set to 2, for representing two-dimensional +geometries. For spatial backends that support it, it may be set to 3 for three-dimensional support. .. note:: @@ -215,7 +216,7 @@ three-dimensional support. .. attribute:: GeometryField.geography If set to ``True``, this option will create a database column of -type geography, rather than geometry. Please refer to the +type geography, rather than geometry. Please refer to the :ref:`geography type <geography-type>` section below for more details. @@ -231,9 +232,9 @@ Geography Type The geography type provides native support for spatial features represented with geographic coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_ Unlike the plane used by a geometry type, the geography type uses a spherical -representation of its data. Distance and measurement operations +representation of its data. Distance and measurement operations performed on a geography column automatically employ great circle arc -calculations and return linear units. In other words, when ``ST_Distance`` +calculations and return linear units. In other words, when ``ST_Distance`` is called on two geographies, a value in meters is returned (as opposed to degrees if called on a geometry column in WGS84). @@ -267,7 +268,7 @@ determining `when to use geography data type over geometry data type .. rubric:: Footnotes .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <https://www.ogc.org/standard/sfs/>`_. .. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems). -.. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <https://epsg.org/>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table. +.. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <https://epsg.org/>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table. .. [#fnthematic] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3. .. [#fndist] This limitation does not apply to PostGIS. .. [#fngeography] Please refer to the `PostGIS Geography Type <https://postgis.net/docs/using_postgis_dbmanagement.html#PostGIS_Geography>`_ documentation for more details. diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 17635d2e24..e417d2d16d 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -107,7 +107,7 @@ Geographic Data World Borders ------------- -The world borders data is available in this `zip file`__. Create a ``data`` +The world borders data is available in this `zip file`__. Create a ``data`` directory in the ``world`` application, download the world borders data, and unzip. On GNU/Linux platforms, use the following commands: @@ -120,7 +120,7 @@ unzip. On GNU/Linux platforms, use the following commands: $ cd ../.. The world borders ZIP file contains a set of data files collectively known as -an `ESRI Shapefile`__, one of the most popular geospatial data formats. When +an `ESRI Shapefile`__, one of the most popular geospatial data formats. When unzipped, the world borders dataset includes files with the following extensions: @@ -148,7 +148,7 @@ other vector data sources: 1: TM_WORLD_BORDERS-0.3 (Polygon) ``ogrinfo`` tells us that the shapefile has one layer, and that this -layer contains polygon data. To find out more, we'll specify the layer name +layer contains polygon data. To find out more, we'll specify the layer name and use the ``-so`` option to get only the important summary information: .. console:: @@ -195,7 +195,7 @@ This detailed summary information tells us the number of features in the layer (246), the geographic bounds of the data, the spatial reference system ("SRS WKT"), as well as type information for each attribute field. For example, ``FIPS: String (2.0)`` indicates that the ``FIPS`` character field has -a maximum length of 2. Similarly, ``LON: Real (8.3)`` is a floating-point +a maximum length of 2. Similarly, ``LON: Real (8.3)`` is a floating-point field that holds a maximum of 8 digits up to three decimal places. Geographic Models @@ -236,7 +236,7 @@ Note that the ``models`` module is imported from ``django.contrib.gis.db``. The default spatial reference system for geometry fields is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in -longitude, latitude pairs in units of degrees. To use a different +longitude, latitude pairs in units of degrees. To use a different coordinate system, set the SRID of the geometry field with the ``srid`` argument. Use an integer representing the coordinate system's EPSG code. @@ -324,7 +324,7 @@ GDAL Interface -------------- Earlier, you used ``ogrinfo`` to examine the contents of the world borders -shapefile. GeoDjango also includes a Pythonic interface to GDAL's powerful OGR +shapefile. GeoDjango also includes a Pythonic interface to GDAL's powerful OGR library that can work with all the vector data sources that OGR supports. First, invoke the Django shell: @@ -375,15 +375,15 @@ You can see the layer's geometry type and how many features it contains: .. note:: Unfortunately, the shapefile data format does not allow for greater - specificity with regards to geometry types. This shapefile, like + specificity with regards to geometry types. This shapefile, like many others, actually includes ``MultiPolygon`` geometries, not Polygons. It's important to use a more general field type in models: a GeoDjango ``MultiPolygonField`` will accept a ``Polygon`` geometry, but a - ``PolygonField`` will not accept a ``MultiPolygon`` type geometry. This + ``PolygonField`` will not accept a ``MultiPolygon`` type geometry. This is why the ``WorldBorder`` model defined above uses a ``MultiPolygonField``. The :class:`~django.contrib.gis.gdal.Layer` may also have a spatial reference -system associated with it. If it does, the ``srs`` attribute will return a +system associated with it. If it does, the ``srs`` attribute will return a :class:`~django.contrib.gis.gdal.SpatialReference` object: .. code-block:: pycon @@ -410,7 +410,7 @@ system -- in other words, the data uses longitude, latitude pairs in units of degrees. In addition, shapefiles also support attribute fields that may contain -additional data. Here are the fields on the World Borders layer: +additional data. Here are the fields on the World Borders layer: >>> print(lyr.fields) ['FIPS', 'ISO2', 'ISO3', 'UN', 'NAME', 'AREA', 'POP2005', 'REGION', 'SUBREGION', 'LON', 'LAT'] @@ -497,10 +497,10 @@ with the following code:: A few notes about what's going on: * Each key in the ``world_mapping`` dictionary corresponds to a field in the - ``WorldBorder`` model. The value is the name of the shapefile field + ``WorldBorder`` model. The value is the name of the shapefile field that data will be loaded from. * The key ``mpoly`` for the geometry field is ``MULTIPOLYGON``, the - geometry type GeoDjango will import the field as. Even simple polygons in + geometry type GeoDjango will import the field as. Even simple polygons in the shapefile will automatically be converted into collections prior to insertion into the database. * The path to the shapefile is not absolute -- in other words, if you move the @@ -529,7 +529,7 @@ Try ``ogrinspect`` ------------------ Now that you've seen how to define geographic models and import data with the :doc:`layermapping`, it's possible to further automate this process with -use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect` +use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect` command introspects a GDAL-supported vector data source (e.g., a shapefile) and generates a model definition and ``LayerMapping`` dictionary automatically. @@ -540,7 +540,7 @@ The general usage of the command goes as follows: $ python manage.py ogrinspect [options] <data_source> <model_name> [options] ``data_source`` is the path to the GDAL-supported data source and -``model_name`` is the name to use for the model. Command-line options may +``model_name`` is the name to use for the model. Command-line options may be used to further define how the model is generated. For example, the following command nearly reproduces the ``WorldBorder`` model @@ -604,9 +604,9 @@ Spatial Queries Spatial Lookups --------------- -GeoDjango adds spatial lookups to the Django ORM. For example, you +GeoDjango adds spatial lookups to the Django ORM. For example, you can find the country in the ``WorldBorder`` table that contains -a particular point. First, fire up the management shell: +a particular point. First, fire up the management shell: .. console:: @@ -619,7 +619,7 @@ Now, define a point of interest [#]_: >>> pnt_wkt = "POINT(-95.3385 29.7245)" The ``pnt_wkt`` string represents the point at -95.3385 degrees longitude, -29.7245 degrees latitude. The geometry is in a format known as +29.7245 degrees latitude. The geometry is in a format known as Well Known Text (WKT), a standard issued by the Open Geospatial Consortium (OGC). [#]_ Import the ``WorldBorder`` model, and perform a ``contains`` lookup using the ``pnt_wkt`` as the parameter: @@ -653,7 +653,7 @@ available queries -- the :doc:`db-api` documentation has more. Automatic Spatial Transformations --------------------------------- When doing spatial queries, GeoDjango automatically transforms -geometries if they're in a different coordinate system. In the following +geometries if they're in a different coordinate system. In the following example, coordinates will be expressed in `EPSG SRID 32140`__, a coordinate system specific to south Texas **only** and in units of **meters**, not degrees: @@ -710,7 +710,7 @@ __ https://spatialreference.org/ref/epsg/32140/ Lazy Geometries --------------- -GeoDjango loads geometries in a standardized textual representation. When the +GeoDjango loads geometries in a standardized textual representation. When the geometry field is first accessed, GeoDjango creates a :class:`~django.contrib.gis.geos.GEOSGeometry` object, exposing powerful functionality, such as serialization properties for popular geospatial diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index b5479a9f33..d3df35a106 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -299,11 +299,11 @@ Indexes for ``varchar`` and ``text`` columns -------------------------------------------- When specifying ``db_index=True`` on your model fields, Django typically -outputs a single ``CREATE INDEX`` statement. However, if the database type +outputs a single ``CREATE INDEX`` statement. However, if the database type for the field is either ``varchar`` or ``text`` (e.g., used by ``CharField``, ``FileField``, and ``TextField``), then Django will create an additional index that uses an appropriate `PostgreSQL operator class`_ -for the column. The extra index is necessary to correctly perform +for the column. The extra index is necessary to correctly perform lookups that use the ``LIKE`` operator in their SQL, as is done with the ``contains`` and ``startswith`` lookup types. @@ -827,7 +827,7 @@ Substring matching and case sensitivity --------------------------------------- For all SQLite versions, there is some slightly counterintuitive behavior when -attempting to match some types of strings. These are triggered when using the +attempting to match some types of strings. These are triggered when using the :lookup:`iexact` or :lookup:`contains` filters in querysets. The behavior splits into two cases: @@ -1143,7 +1143,7 @@ INSERT ... RETURNING INTO ------------------------- By default, the Oracle backend uses a ``RETURNING INTO`` clause to efficiently -retrieve the value of an ``AutoField`` when inserting new rows. This behavior +retrieve the value of an ``AutoField`` when inserting new rows. This behavior may result in a ``DatabaseError`` in certain unusual setups, such as when inserting into a remote table, or into a view with an ``INSTEAD OF`` trigger. The ``RETURNING INTO`` clause can be disabled by setting the @@ -1182,9 +1182,9 @@ backends; except for Oracle, however, the quotes have no effect. When running ``migrate``, an ``ORA-06552`` error may be encountered if certain Oracle keywords are used as the name of a model field or the -value of a ``db_column`` option. Django quotes all identifiers used +value of a ``db_column`` option. Django quotes all identifiers used in queries to prevent most such problems, but this error can still -occur when an Oracle datatype is used as a column name. In +occur when an Oracle datatype is used as a column name. In particular, take care to avoid using the names ``date``, ``timestamp``, ``number`` or ``float`` as a field name. diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 64819af1ab..73d3754fc2 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -1641,7 +1641,7 @@ This is useful in a number of ways: copy of a database that you'd like to interact with. You can dump your database to a :ref:`fixture <fixtures-explanation>` (using the :djadmin:`dumpdata` command, explained above), then use ``testserver`` to run - your web application with that data. With this arrangement, you have the + your web application with that data. With this arrangement, you have the flexibility of messing up your data in any way, knowing that whatever data changes you're making are only being made to a test database. @@ -1907,7 +1907,7 @@ Example usage: .. django-admin-option:: --no-color -Disables colorized command output. Some commands format their output to be +Disables colorized command output. Some commands format their output to be colorized. For example, errors will be printed to the console in red and SQL statements will be syntax highlighted. diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 399c8f3728..ed2bb4d604 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -842,7 +842,7 @@ By default, the form rendering methods include: It's always a good idea to use ``<label>`` tags. The ``id`` attribute values are generated by prepending ``id_`` to the form -field names. This behavior is configurable, though, if you want to change the +field names. This behavior is configurable, though, if you want to change the ``id`` convention or remove HTML ``id`` attributes and ``<label>`` tags entirely. @@ -1389,7 +1389,7 @@ Methods of ``BoundField`` .. method:: BoundField.as_widget(widget=None, attrs=None, only_initial=False) Renders the field by rendering the passed widget, adding any HTML - attributes passed as ``attrs``. If no widget is specified, then the + attributes passed as ``attrs``. If no widget is specified, then the field's default widget will be used. ``only_initial`` is used by Django internals and should not be set diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index b09a43f47c..f0a8e6c341 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -713,15 +713,15 @@ For each field, we describe the default widget used if you don't specify .. attribute:: allow_files - Optional. Either ``True`` or ``False``. Default is ``True``. Specifies - whether files in the specified location should be included. Either this or - :attr:`allow_folders` must be ``True``. + Optional. Either ``True`` or ``False``. Default is ``True``. Specifies + whether files in the specified location should be included. Either this + or :attr:`allow_folders` must be ``True``. .. attribute:: allow_folders - Optional. Either ``True`` or ``False``. Default is ``False``. Specifies - whether folders in the specified location should be included. Either this or - :attr:`allow_files` must be ``True``. + Optional. Either ``True`` or ``False``. Default is ``False``. Specifies + whether folders in the specified location should be included. Either + this or :attr:`allow_files` must be ``True``. ``FloatField`` @@ -1217,7 +1217,7 @@ Slightly complex built-in ``Field`` classes .. attribute:: fields A tuple of fields whose values are cleaned and subsequently combined - into a single value. Each value of the field is cleaned by the + into a single value. Each value of the field is cleaned by the corresponding field in ``fields`` -- the first value is cleaned by the first field, the second value is cleaned by the second field, etc. Once all fields are cleaned, the list of clean values is combined into @@ -1325,9 +1325,9 @@ Fields which handle relationships Two fields are available for representing relationships between models: :class:`ModelChoiceField` and -:class:`ModelMultipleChoiceField`. Both of these fields require a +:class:`ModelMultipleChoiceField`. Both of these fields require a single ``queryset`` parameter that is used to create the choices for -the field. Upon form validation, these fields will place either one +the field. Upon form validation, these fields will place either one model object (in the case of ``ModelChoiceField``) or multiple model objects (in the case of ``ModelMultipleChoiceField``) into the ``cleaned_data`` dictionary of the form. diff --git a/docs/ref/logging.txt b/docs/ref/logging.txt index a045d4d7d7..d10da840bc 100644 --- a/docs/ref/logging.txt +++ b/docs/ref/logging.txt @@ -251,7 +251,7 @@ The security loggers will receive messages on any occurrence of :exc:`~django.core.exceptions.SuspiciousOperation` and other security-related errors. There is a sub-logger for each subtype of security error, including all ``SuspiciousOperation``\s. The level of the log event depends on where the -exception is handled. Most occurrences are logged as a warning, while +exception is handled. Most occurrences are logged as a warning, while any ``SuspiciousOperation`` that reaches the WSGI handler will be logged as an error. For example, when an HTTP ``Host`` header is included in a request from a client that does not match :setting:`ALLOWED_HOSTS`, Django will return a 400 diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 6879d5e726..0cbcee4c4c 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -416,7 +416,7 @@ the browser when you expected it to be something harmless. To prevent the browser from guessing the content type and force it to always use the type provided in the ``Content-Type`` header, you can pass -the `X-Content-Type-Options: nosniff`__ header. ``SecurityMiddleware`` will +the `X-Content-Type-Options: nosniff`__ header. ``SecurityMiddleware`` will do this for all responses if the :setting:`SECURE_CONTENT_TYPE_NOSNIFF` setting is ``True``. diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 430efcd446..39c7277de1 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -1146,7 +1146,7 @@ If you want to manually associate file data with method is used to persist that file data. Takes two required arguments: ``name`` which is the name of the file, and -``content`` which is an object containing the file's contents. The +``content`` which is an object containing the file's contents. The optional ``save`` argument controls whether or not the model instance is saved after the file associated with this field has been altered. Defaults to ``True``. @@ -1230,14 +1230,14 @@ directory on the filesystem. Has some special arguments, of which the first is .. attribute:: FilePathField.allow_files - Optional. Either ``True`` or ``False``. Default is ``True``. Specifies - whether files in the specified location should be included. Either this or + Optional. Either ``True`` or ``False``. Default is ``True``. Specifies + whether files in the specified location should be included. Either this or :attr:`~FilePathField.allow_folders` must be ``True``. .. attribute:: FilePathField.allow_folders - Optional. Either ``True`` or ``False``. Default is ``False``. Specifies - whether folders in the specified location should be included. Either this + Optional. Either ``True`` or ``False``. Default is ``False``. Specifies + whether folders in the specified location should be included. Either this or :attr:`~FilePathField.allow_files` must be ``True``. The one potential gotcha is that :attr:`~FilePathField.match` applies to the @@ -1528,7 +1528,7 @@ default length of 50. Implies setting :attr:`Field.db_index` to ``True``. It is often useful to automatically prepopulate a SlugField based on the value -of some other value. You can do this automatically in the admin using +of some other value. You can do this automatically in the admin using :attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`. It uses :class:`~django.core.validators.validate_slug` or @@ -1681,7 +1681,7 @@ See :attr:`ForeignKey.on_delete` for details on the second positional argument. A database index is automatically created on the ``ForeignKey``. You can -disable this by setting :attr:`~Field.db_index` to ``False``. You may want to +disable this by setting :attr:`~Field.db_index` to ``False``. You may want to avoid the overhead of an index if you are creating a foreign key for consistency rather than joins, or if you will be creating an alternative index like a partial or multiple column index. diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index fc568422b6..f03f96443e 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -959,7 +959,7 @@ Examples: .. method:: all() -Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass). This +Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass). This can be useful in situations where you might want to pass in either a model manager or a ``QuerySet`` and do further filtering on the result. After calling ``all()`` on either object, you'll definitely have a ``QuerySet`` to work with. @@ -1562,7 +1562,7 @@ of the arguments is required, but you should use at least one of them. * ``select`` The ``select`` argument lets you put extra fields in the ``SELECT`` - clause. It should be a dictionary mapping attribute names to SQL + clause. It should be a dictionary mapping attribute names to SQL clauses to use to calculate that attribute. Example:: @@ -1895,7 +1895,7 @@ are in your ``only()`` call. .. method:: using(alias) This method is for controlling which database the ``QuerySet`` will be -evaluated against if you are using more than one database. The only argument +evaluated against if you are using more than one database. The only argument this method takes is the alias of a database, as defined in :setting:`DATABASES`. diff --git a/docs/ref/paginator.txt b/docs/ref/paginator.txt index 5acd3d87c2..549b9f4cd6 100644 --- a/docs/ref/paginator.txt +++ b/docs/ref/paginator.txt @@ -58,7 +58,7 @@ For examples, see the :doc:`Pagination topic guide </topics/pagination>`. .. attribute:: Paginator.allow_empty_first_page - Optional. Whether or not the first page is allowed to be empty. If + Optional. Whether or not the first page is allowed to be empty. If ``False`` and ``object_list`` is empty, then an ``EmptyPage`` error will be raised. diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 21848494f7..d39cd9fa3e 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -1255,7 +1255,7 @@ using non-dict objects in JSON-encoded response. <https://262.ecma-international.org/5.1/#sec-11.1.4>`_ it was possible to poison the JavaScript ``Array`` constructor. For this reason, Django does not allow passing non-dict objects to the - :class:`~django.http.JsonResponse` constructor by default. However, most + :class:`~django.http.JsonResponse` constructor by default. However, most modern browsers implement ECMAScript 5 which removes this attack vector. Therefore it is possible to disable this security precaution. diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 7bb836f42d..c1909ff40f 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -311,9 +311,9 @@ keep the cookies in-memory instead of on persistent storage. Default: ``None`` -The domain to be used when setting the CSRF cookie. This can be useful for +The domain to be used when setting the CSRF cookie. This can be useful for easily allowing cross-subdomain requests to be excluded from the normal cross -site request forgery protection. It should be set to a string such as +site request forgery protection. It should be set to a string such as ``".example.com"`` to allow a POST request from a form on one subdomain to be accepted by a view served from another subdomain. diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index bdeca55938..60d7cd083d 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -40,8 +40,9 @@ model system. methods for these signals to be sent. Note also that Django stores signal handlers as weak references by default, - so if your handler is a local function, it may be garbage collected. To - prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`. + so if your handler is a local function, it may be garbage collected. To + prevent this, pass ``weak=False`` when you call the signal's + :meth:`~django.dispatch.Signal.connect`. .. note:: @@ -687,7 +688,7 @@ initiated. :module: Sent when the database wrapper makes the initial connection to the -database. This is particularly useful if you'd like to send any post +database. This is particularly useful if you'd like to send any post connection commands to the SQL backend. Arguments sent with this signal: diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index f1fb70c9b8..cc6d807ce1 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -368,7 +368,7 @@ straight lookups. Here are some things to keep in mind: To prevent this, set an ``alters_data`` attribute on the callable variable. The template system won't call a variable if it has ``alters_data=True`` set, and will instead replace the variable with - ``string_if_invalid``, unconditionally. The + ``string_if_invalid``, unconditionally. The dynamically-generated :meth:`~django.db.models.Model.delete` and :meth:`~django.db.models.Model.save` methods on Django model objects get ``alters_data=True`` automatically. Example:: @@ -381,8 +381,8 @@ straight lookups. Here are some things to keep in mind: * Occasionally you may want to turn off this feature for other reasons, and tell the template system to leave a variable uncalled no matter - what. To do so, set a ``do_not_call_in_templates`` attribute on the - callable with the value ``True``. The template system then will act as + what. To do so, set a ``do_not_call_in_templates`` attribute on the + callable with the value ``True``. The template system then will act as if your variable is not callable (allowing you to access attributes of the callable, for example). @@ -666,7 +666,7 @@ processors:: ] In addition to these, :class:`RequestContext` always enables -``'django.template.context_processors.csrf'``. This is a security related +``'django.template.context_processors.csrf'``. This is a security related context processor required by the admin and other contrib apps, and, in case of accidental misconfiguration, it is deliberately hardcoded in and cannot be turned off in the ``context_processors`` option. @@ -1100,7 +1100,7 @@ Loader methods source. For example, the filesystem loader may receive ``'index.html'`` as a - ``template_name`` argument. This method would yield origins for the + ``template_name`` argument. This method would yield origins for the full path of ``index.html`` as it appears in each template directory the loader looks at. diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 464c4d83ac..9e76319c43 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -137,7 +137,7 @@ this: </tr> {% endfor %} -Variables included in the cycle will be escaped. You can disable auto-escaping +Variables included in the cycle will be escaped. You can disable auto-escaping with: .. code-block:: html+django @@ -1754,32 +1754,32 @@ Format character Description Example output leading zeros. ``j`` Day of the month without leading ``'1'`` to ``'31'`` zeros. -``D`` Day of the week, textual, 3 letters. ``'Fri'`` -``l`` Day of the week, textual, long. ``'Friday'`` +``D`` Day of the week, textual, 3 letters. ``'Fri'`` +``l`` Day of the week, textual, long. ``'Friday'`` ``S`` English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` month, 2 characters. ``w`` Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) leading zeros. -``z`` Day of the year. ``1`` to ``366`` +``z`` Day of the year. ``1`` to ``366`` **Week** ``W`` ISO-8601 week number of year, with ``1``, ``53`` weeks starting on Monday. **Month** -``m`` Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` -``n`` Month without leading zeros. ``'1'`` to ``'12'`` -``M`` Month, textual, 3 letters. ``'Jan'`` -``b`` Month, textual, 3 letters, lowercase. ``'jan'`` +``m`` Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` +``n`` Month without leading zeros. ``'1'`` to ``'12'`` +``M`` Month, textual, 3 letters. ``'Jan'`` +``b`` Month, textual, 3 letters, lowercase. ``'jan'`` ``E`` Month, locale specific alternative representation usually used for long - date representation. ``'listopada'`` (for Polish locale, as opposed to ``'Listopad'``) -``F`` Month, textual, long. ``'January'`` + date representation. ``'listopada'`` (for Polish locale, as opposed to ``'Listopad'``) +``F`` Month, textual, long. ``'January'`` ``N`` Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` style. Proprietary extension. -``t`` Number of days in the given month. ``28`` to ``31`` +``t`` Number of days in the given month. ``28`` to ``31`` **Year** -``y`` Year, 2 digits with leading zeros. ``'00'`` to ``'99'`` -``Y`` Year, 4 digits with leading zeros. ``'0001'``, ..., ``'1999'``, ..., ``'9999'`` -``L`` Boolean for whether it's a leap year. ``True`` or ``False`` +``y`` Year, 2 digits with leading zeros. ``'00'`` to ``'99'`` +``Y`` Year, 4 digits with leading zeros. ``'0001'``, ..., ``'1999'``, ..., ``'9999'`` +``L`` Boolean for whether it's a leap year. ``True`` or ``False`` ``o`` ISO-8601 week-numbering year, ``'1999'`` corresponding to the ISO-8601 week number (W) which uses leap weeks. See Y @@ -1789,16 +1789,16 @@ Format character Description Example output zeros. ``G`` Hour, 24-hour format without leading ``'0'`` to ``'23'`` zeros. -``h`` Hour, 12-hour format. ``'01'`` to ``'12'`` -``H`` Hour, 24-hour format. ``'00'`` to ``'23'`` -``i`` Minutes. ``'00'`` to ``'59'`` -``s`` Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` -``u`` Microseconds. ``000000`` to ``999999`` +``h`` Hour, 12-hour format. ``'01'`` to ``'12'`` +``H`` Hour, 24-hour format. ``'00'`` to ``'23'`` +``i`` Minutes. ``'00'`` to ``'59'`` +``s`` Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` +``u`` Microseconds. ``000000`` to ``999999`` ``a`` ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` this is slightly different than PHP's output, because this includes periods to match Associated Press style.) -``A`` ``'AM'`` or ``'PM'``. ``'AM'`` +``A`` ``'AM'`` or ``'PM'``. ``'AM'`` ``f`` Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` with minutes left off if they're zero. Proprietary extension. @@ -1813,8 +1813,8 @@ Format character Description Example output depending on the datetime. ``I`` Daylight saving time, whether it's in ``'1'`` or ``'0'`` effect or not. -``O`` Difference to Greenwich time in hours. ``'+0200'`` -``T`` Time zone of this machine. ``'EST'``, ``'MDT'`` +``O`` Difference to Greenwich time in hours. ``'+0200'`` +``T`` Time zone of this machine. ``'EST'``, ``'MDT'`` ``Z`` Time zone offset in seconds. The ``-43200`` to ``43200`` offset for timezones west of UTC is always negative, and for those east of diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt index e8812666fa..b24f291e4c 100644 --- a/docs/ref/templates/language.txt +++ b/docs/ref/templates/language.txt @@ -208,7 +208,7 @@ you a taste of what's available, here are some of the more commonly used tags: :ttag:`for` - Loop over each item in an array. For example, to display a list of athletes + Loop over each item in an array. For example, to display a list of athletes provided in ``athlete_list``: .. code-block:: html+django diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 18c5681515..6542f26476 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -282,7 +282,7 @@ The functions defined in this module share the following properties: :class:`~pathlib.Path`. This method will encode certain characters that would normally be - recognized as special characters for URIs. Note that this method does not + recognized as special characters for URIs. Note that this method does not encode the ' character, as it is a valid character within URIs. See ``encodeURIComponent()`` JavaScript function for more details. diff --git a/docs/releases/0.96.txt b/docs/releases/0.96.txt index 032eb1009a..5a9492e389 100644 --- a/docs/releases/0.96.txt +++ b/docs/releases/0.96.txt @@ -133,7 +133,7 @@ New forms library ``django.newforms`` is Django's new form-handling library. It's a replacement for ``django.forms``, the old form/manipulator/validation -framework. Both APIs are available in 0.96, but over the next two +framework. Both APIs are available in 0.96, but over the next two releases we plan to switch completely to the new forms system, and deprecate and remove the old system. @@ -142,7 +142,7 @@ There are three elements to this transition: * We've copied the current ``django.forms`` to ``django.oldforms``. This allows you to upgrade your code *now* rather than waiting for the backwards-incompatible change and - rushing to fix your code after the fact. Just change your + rushing to fix your code after the fact. Just change your import statements like this:: from django import forms # 0.95-style diff --git a/docs/releases/1.1.2.txt b/docs/releases/1.1.2.txt index 22819a895b..8fdaa09be9 100644 --- a/docs/releases/1.1.2.txt +++ b/docs/releases/1.1.2.txt @@ -23,9 +23,9 @@ Test runner exit status code The exit status code of the test runners (``tests/runtests.py`` and ``python manage.py test``) no longer represents the number of failed tests, since a -failure of 256 or more tests resulted in a wrong exit status code. The exit +failure of 256 or more tests resulted in a wrong exit status code. The exit status code for the test runner is now 0 for success (no failing tests) and 1 -for any number of test failures. If needed, the number of test failures can be +for any number of test failures. If needed, the number of test failures can be found at the end of the test runner's output. Cookie encoding @@ -34,7 +34,7 @@ Cookie encoding To fix bugs with cookies in Internet Explorer, Safari, and possibly other browsers, our encoding of cookie values was changed so that the characters comma and semi-colon are treated as non-safe characters, and are therefore -encoded as ``\054`` and ``\073`` respectively. This could produce backwards +encoded as ``\054`` and ``\073`` respectively. This could produce backwards incompatibilities, especially if you are storing comma or semi-colon in cookies and have JavaScript code that parses and manipulates cookie values client-side. diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index a2bc457a8d..7d22efbcf9 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -581,7 +581,7 @@ to generate and apply a database migration for your user model. We considered an increase to 254 characters to more easily allow the use of email addresses (which are limited to 254 characters) as usernames but rejected -it due to a MySQL limitation. When using the ``utf8mb4`` encoding (recommended +it due to a MySQL limitation. When using the ``utf8mb4`` encoding (recommended for proper Unicode support), MySQL can only create unique indexes with 191 characters by default. Therefore, if you need a longer length, please use a custom user model. @@ -850,7 +850,7 @@ Miscellaneous * The ``base_field`` attribute of :class:`~django.contrib.postgres.fields.RangeField` is now a type of field, - not an instance of a field. If you have created a custom subclass of + not an instance of a field. If you have created a custom subclass of :class:`~django.contrib.postgres.fields.RangeField`, you should change the ``base_field`` attribute. diff --git a/docs/releases/1.2.6.txt b/docs/releases/1.2.6.txt index cfd1d9c0d4..9a92b3da05 100644 --- a/docs/releases/1.2.6.txt +++ b/docs/releases/1.2.6.txt @@ -7,7 +7,7 @@ Django 1.2.6 release notes Welcome to Django 1.2.6! This is the sixth bugfix/security release in the Django 1.2 series, fixing -several security issues present in Django 1.2.5. Django 1.2.6 is a +several security issues present in Django 1.2.5. Django 1.2.6 is a recommended upgrade for all users of any Django release in the 1.2.X series. For a full list of issues addressed in this release, see the `security diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt index 6666596872..cff793047e 100644 --- a/docs/releases/1.2.txt +++ b/docs/releases/1.2.txt @@ -173,7 +173,7 @@ Permissions for anonymous users If you provide a custom auth backend with ``supports_anonymous_user`` set to ``True``, AnonymousUser will check the backend for permissions, just like -User already did. This is useful for centralizing permission handling - apps +User already did. This is useful for centralizing permission handling - apps can always delegate the question of whether something is allowed or not to the authorization/authentication backend. See the :doc:`authentication docs </topics/auth/index>` for more details. @@ -276,7 +276,7 @@ untouched up to and including the Django 1.3 release. If you have developed your own custom template loaders we suggest to consider porting them to a class-based implementation because the code for backwards compatibility with function-based loaders starts its deprecation process in -Django 1.2 and will be removed in Django 1.4. There is a description of the +Django 1.2 and will be removed in Django 1.4. There is a description of the API these loader classes must implement in the template API reference and you can also examine the source code of the loaders shipped with Django. @@ -342,7 +342,7 @@ GeoDjango --------- The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>` -in 1.2 is support for multiple spatial databases. As a result, +in 1.2 is support for multiple spatial databases. As a result, the following :ref:`spatial database backends <spatial-backends>` are now included: @@ -680,7 +680,7 @@ Cookie encoding To fix bugs with cookies in Internet Explorer, Safari, and possibly other browsers, our encoding of cookie values was changed so that the comma and semicolon are treated as non-safe characters, and are -therefore encoded as ``\054`` and ``\073`` respectively. This could +therefore encoded as ``\054`` and ``\073`` respectively. This could produce backwards incompatibilities, especially if you are storing comma or semi-colon in cookies and have JavaScript code that parses and manipulates cookie values client-side. @@ -702,7 +702,7 @@ In previous versions of Django, a model's ``BooleanField`` under MySQL would return its value as either ``1`` or ``0``, instead of ``True`` or ``False``; for most people this wasn't a problem because ``bool`` is a subclass of ``int`` in Python. In Django 1.2, however, -``BooleanField`` on MySQL correctly returns a real ``bool``. The only +``BooleanField`` on MySQL correctly returns a real ``bool``. The only time this should ever be an issue is if you were expecting the ``repr`` of a ``BooleanField`` to print ``1`` or ``0``. @@ -1094,10 +1094,10 @@ GeoDjango --------- To allow support for multiple databases, the GeoDjango database internals were -changed substantially. The largest backwards-incompatible change is that +changed substantially. The largest backwards-incompatible change is that the module ``django.contrib.gis.db.backend`` was renamed to :mod:`django.contrib.gis.db.backends`, where the full-fledged -:ref:`spatial database backends <spatial-backends>` now exist. The +:ref:`spatial database backends <spatial-backends>` now exist. The following sections provide information on the most-popular APIs that were affected by these changes. @@ -1107,7 +1107,7 @@ were affected by these changes. Prior to the creation of the separate spatial backends, the ``django.contrib.gis.db.backend.SpatialBackend`` object was provided as an abstraction to introspect on the capabilities of -the spatial database. All of the attributes and routines provided by +the spatial database. All of the attributes and routines provided by ``SpatialBackend`` are now a part of the ``ops`` attribute of the database backend. @@ -1147,7 +1147,7 @@ is using a supported spatial database backend. Because the table structure of the OGC spatial metadata tables differs across spatial databases, the ``SpatialRefSys`` and ``GeometryColumns`` models can no longer be associated with - the ``gis`` application name. Thus, no models will be returned + the ``gis`` application name. Thus, no models will be returned when using the ``get_models`` method in the following example: .. code-block:: pycon diff --git a/docs/releases/1.3.1.txt b/docs/releases/1.3.1.txt index 4c289161e1..0612e40e12 100644 --- a/docs/releases/1.3.1.txt +++ b/docs/releases/1.3.1.txt @@ -7,7 +7,7 @@ Django 1.3.1 release notes Welcome to Django 1.3.1! This is the first security release in the Django 1.3 series, fixing several -security issues in Django 1.3. Django 1.3.1 is a recommended upgrade for +security issues in Django 1.3. Django 1.3.1 is a recommended upgrade for all users of Django 1.3. For a full list of issues addressed in this release, see the `security diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 52780d548b..310a66f198 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -78,7 +78,7 @@ Logging ------- Django 1.3 adds framework-level support for Python's ``logging`` -module. This means you can now easily configure and control logging +module. This means you can now easily configure and control logging as part of your Django project. A number of logging handlers and logging calls have been added to Django's own code as well -- most notably, the error emails sent on an HTTP 500 server error are now @@ -236,7 +236,7 @@ Permissions for inactive users If you provide a custom auth backend with ``supports_inactive_user`` set to ``True``, an inactive ``User`` instance will check the backend -for permissions. This is useful for further centralizing the +for permissions. This is useful for further centralizing the permission handling. See the :doc:`authentication docs </topics/auth/index>` for more details. @@ -808,9 +808,9 @@ GeoDjango * Previously, calling :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` would - silently do nothing when GDAL wasn't available. Now, a + silently do nothing when GDAL wasn't available. Now, a :class:`~django.contrib.gis.geos.GEOSException` is properly raised - to indicate possible faulty application code. A warning is now + to indicate possible faulty application code. A warning is now raised if :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` is called when the SRID of the geometry is less than 0 or ``None``. diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index d756ddc868..9fd9a7cec5 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -389,7 +389,7 @@ Context in year archive class-based views For consistency with the other date-based generic views, :class:`~django.views.generic.dates.YearArchiveView` now passes ``year`` in -the context as a :class:`datetime.date` rather than a string. If you are +the context as a :class:`datetime.date` rather than a string. If you are using ``{{ year }}`` in your templates, you must replace it with ``{{ year|date:"Y" }}``. diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 5f6f378d20..794dddad8f 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -248,8 +248,8 @@ Minor features * The ``validate_max`` parameter was added to ``BaseFormSet`` and :func:`~django.forms.formsets.formset_factory`, and ``ModelForm`` and inline - versions of the same. The behavior of validation for formsets with - ``max_num`` was clarified. The previously undocumented behavior that + versions of the same. The behavior of validation for formsets with + ``max_num`` was clarified. The previously undocumented behavior that hardened formsets against memory exhaustion attacks was documented, and the undocumented limit of the higher of 1000 or ``max_num`` forms was changed so it is always 1000 more than ``max_num``. diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index e9dabbbdb7..14f928486f 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -1668,7 +1668,7 @@ Model ``Field.related`` ----------------------- Private attribute ``django.db.models.Field.related`` is deprecated in favor -of ``Field.rel``. The latter is an instance of +of ``Field.rel``. The latter is an instance of ``django.db.models.fields.related.ForeignObjectRel`` which replaces ``django.db.models.related.RelatedObject``. The ``django.db.models.related`` module has been removed and the ``Field.related`` attribute will be removed in diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt index b37d256d90..b16fc61a64 100644 --- a/docs/releases/1.9.txt +++ b/docs/releases/1.9.txt @@ -357,7 +357,7 @@ Forms * :class:`~django.forms.CharField` now accepts a :attr:`~django.forms.CharField.strip` argument to strip input data of leading - and trailing whitespace. As this defaults to ``True`` this is different + and trailing whitespace. As this defaults to ``True`` this is different behavior from previous releases. * Form fields now support the :attr:`~django.forms.Field.disabled` argument, diff --git a/docs/releases/2.1.txt b/docs/releases/2.1.txt index 2ed9152e21..4c05e5ae3b 100644 --- a/docs/releases/2.1.txt +++ b/docs/releases/2.1.txt @@ -20,7 +20,7 @@ Python compatibility ==================== Django 2.1 supports Python 3.5, 3.6, and 3.7. Django 2.0 is the last version to -support Python 3.4. We **highly recommend** and only officially support the +support Python 3.4. We **highly recommend** and only officially support the latest release of each series. .. _whats-new-2.1: diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index 1a713003a3..5ef1ea5bbd 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -616,7 +616,7 @@ password resets. You must then provide some key implementation details: .. attribute:: is_active A boolean attribute that indicates whether the user is considered - "active". This attribute is provided as an attribute on + "active". This attribute is provided as an attribute on ``AbstractBaseUser`` defaulting to ``True``. How you choose to implement it will depend on the details of your chosen auth backends. See the documentation of the :attr:`is_active attribute on the built-in @@ -708,7 +708,7 @@ The following attributes and methods are available on any subclass of .. method:: models.AbstractBaseUser.set_unusable_password() - Marks the user as having no password set. This isn't the same as + Marks the user as having no password set. This isn't the same as having a blank string for a password. :meth:`~django.contrib.auth.models.AbstractBaseUser.check_password` for this user will never return ``True``. Doesn't save the diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index af09c43eb2..28bc63b739 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -873,7 +873,7 @@ the login page or shown an HTTP 403 Forbidden response, depending on the .. attribute:: login_url - Default return value for :meth:`get_login_url`. Defaults to ``None`` + Default return value for :meth:`get_login_url`. Defaults to ``None`` in which case :meth:`get_login_url` falls back to :setting:`settings.LOGIN_URL <LOGIN_URL>`. @@ -891,7 +891,7 @@ the login page or shown an HTTP 403 Forbidden response, depending on the If this attribute is set to ``True``, a :class:`~django.core.exceptions.PermissionDenied` exception is raised - when the conditions are not met. When ``False`` (the default), + when the conditions are not met. When ``False`` (the default), anonymous users are redirected to the login page. .. method:: get_login_url() diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index 8efd2bdebf..ca25f9ddb6 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -33,7 +33,7 @@ The :attr:`~django.contrib.auth.models.User.password` attribute of a Those are the components used for storing a User's password, separated by the dollar-sign character and consist of: the hashing algorithm, the number of algorithm iterations (work factor), the random salt, and the resulting password -hash. The algorithm is one of a number of one-way hashing or password storage +hash. The algorithm is one of a number of one-way hashing or password storage algorithms Django can use; see below. Iterations describe the number of times the algorithm is run over the hash. Salt is the random seed used and the hash is the result of the one-way function. @@ -46,7 +46,7 @@ amounts of computing time to break. However, depending on your requirements, you may choose a different algorithm, or even use a custom algorithm to match your specific security situation. Again, most users shouldn't need to do this -- if -you're not sure, you probably don't. If you do, please read on: +you're not sure, you probably don't. If you do, please read on: Django chooses the algorithm to use by consulting the :setting:`PASSWORD_HASHERS` setting. This is a list of hashing algorithm diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index 9cb1ddda23..a0aba96863 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -710,7 +710,7 @@ want:: You can also override the cache prefix on a per-view basis. ``cache_page`` takes an optional keyword argument, ``key_prefix``, which works in the same way as the :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -setting for the middleware. It can be used like this:: +setting for the middleware. It can be used like this:: @cache_page(60 * 15, key_prefix="site1") def my_view(request): ... @@ -860,7 +860,7 @@ 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 low-level cache API. You can use this API -to store objects in the cache with any level of granularity you like. You can +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 @@ -1052,7 +1052,7 @@ of keys to be cleared: .. method:: cache.clear() Finally, if you want to delete all the keys in the cache, use -``cache.clear()``. Be careful with this; ``clear()`` will remove *everything* +``cache.clear()``. Be careful with this; ``clear()`` will remove *everything* from the cache, not just the keys set by your application: .. code-block:: pycon @@ -1312,7 +1312,7 @@ expose incorrect or sensitive data to subsequent visitors to those pages. 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 +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 diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt index 81c800e213..e72fe5cfe6 100644 --- a/docs/topics/class-based-views/generic-display.txt +++ b/docs/topics/class-based-views/generic-display.txt @@ -306,8 +306,8 @@ We'll deal with this problem in the next section. .. note:: If you get a 404 when requesting ``/books/acme/``, check to ensure you - actually have a Publisher with the name 'ACME Publishing'. Generic - views have an ``allow_empty`` parameter for this case. See the + actually have a Publisher with the name 'ACME Publishing'. Generic + views have an ``allow_empty`` parameter for this case. See the :doc:`class-based-views reference</ref/class-based-views/index>` for more details. diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt index 173f862891..45c36409ce 100644 --- a/docs/topics/class-based-views/generic-editing.txt +++ b/docs/topics/class-based-views/generic-editing.txt @@ -65,7 +65,7 @@ Notes: Model forms =========== -Generic views really shine when working with models. These generic +Generic views really shine when working with models. These generic views will automatically create a :class:`~django.forms.ModelForm`, so long as they can work out which model class to use: @@ -78,7 +78,7 @@ they can work out which model class to use: Model form views provide a :meth:`~django.views.generic.edit.ModelFormMixin.form_valid` implementation -that saves the model automatically. You can override this if you have any +that saves the model automatically. You can override this if you have any special requirements; see below for examples. You don't even need to provide a ``success_url`` for diff --git a/docs/topics/class-based-views/index.txt b/docs/topics/class-based-views/index.txt index ec126099f6..f69f70cf5a 100644 --- a/docs/topics/class-based-views/index.txt +++ b/docs/topics/class-based-views/index.txt @@ -132,7 +132,7 @@ And the view:: 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 +header indicates when the most recent book was published. Based on this information, the client may or may not download the full object list. .. _async-class-based-views: diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt index dfd36a64ae..2929acd9c6 100644 --- a/docs/topics/conditional-view-processing.txt +++ b/docs/topics/conditional-view-processing.txt @@ -22,7 +22,7 @@ last modification time it was sent, or either :rfc:`If-Match containing the last ``ETag`` it was sent. If the current version of the page matches the ``ETag`` sent by the client, or if the resource has not been modified, a 304 status code can be sent back, instead of a full response, -telling the client that nothing has changed. Depending on the header, if the +telling the client that nothing has changed. Depending on the header, if the page has been modified or does not match the ``ETag`` sent by the client, a 412 status code (Precondition Failed) may be returned. diff --git a/docs/topics/db/instrumentation.txt b/docs/topics/db/instrumentation.txt index 65960fa9a1..8a08bd9a4f 100644 --- a/docs/topics/db/instrumentation.txt +++ b/docs/topics/db/instrumentation.txt @@ -106,7 +106,7 @@ Returns a context manager which, when entered, installs a wrapper around database query executions, and when exited, removes the wrapper. The wrapper is installed on the thread-local connection object. -``wrapper`` is a callable taking five arguments. It is called for every query +``wrapper`` is a callable taking five arguments. It is called for every query execution in the scope of the context manager, with arguments ``execute``, ``sql``, ``params``, ``many``, and ``context`` as described above. It's expected to call ``execute(sql, params, many, context)`` and return the return diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 9360c42109..bafc10f44c 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -1300,7 +1300,7 @@ the parent, it's possible to move from the parent down to the child, as in the above example. However, this uses up the name that is the default :attr:`~django.db.models.ForeignKey.related_name` value for :class:`~django.db.models.ForeignKey` and -:class:`~django.db.models.ManyToManyField` relations. If you +:class:`~django.db.models.ManyToManyField` relations. If you are putting those types of relations on a subclass of the parent model, you **must** specify the :attr:`~django.db.models.ForeignKey.related_name` attribute on each such field. If you forget, Django will raise a validation diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 68bd237340..519d152589 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -900,7 +900,7 @@ reuse it: When ``QuerySet``\s are not cached ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Querysets do not always cache their results. When evaluating only *part* of +Querysets do not always cache their results. When evaluating only *part* of the queryset, the cache is checked, but if it is not populated then the items returned by the subsequent query are not cached. Specifically, this means that :ref:`limiting the queryset <limiting-querysets>` using an array slice or an diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index 63a6bc2d66..2f6fbde168 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -540,7 +540,7 @@ rather than the functions described below, but they're still part of the public API, and there's no plan to deprecate them. Each of these functions takes a ``using`` argument which should be the name of -a database for which the behavior applies. If no ``using`` argument is +a database for which the behavior applies. If no ``using`` argument is provided then the ``"default"`` database is used. Savepoints are controlled by three functions in :mod:`django.db.transaction`: diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index a452c7640d..585a42469f 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -139,9 +139,9 @@ A ``max_num`` value of ``None`` (the default) puts a high limit on the number of forms displayed (1000). In practice this is equivalent to no limit. By default, ``max_num`` only affects how many forms are displayed and does not -affect validation. If ``validate_max=True`` is passed to the +affect validation. If ``validate_max=True`` is passed to the :func:`~django.forms.formsets.formset_factory`, then ``max_num`` will affect -validation. See :ref:`validate_max`. +validation. See :ref:`validate_max`. .. _formsets-absolute-max: @@ -695,7 +695,7 @@ model instances for deleted forms will be deleted when you call ``formset.save()``. If you call ``formset.save(commit=False)``, objects will not be deleted -automatically. You'll need to call ``delete()`` on each of the +automatically. You'll need to call ``delete()`` on each of the :attr:`formset.deleted_objects <django.forms.models.BaseModelFormSet.deleted_objects>` to actually delete them: diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt index 17bd385ed0..96408fb4e7 100644 --- a/docs/topics/forms/media.txt +++ b/docs/topics/forms/media.txt @@ -211,7 +211,7 @@ complete control over which files are inherited, and which are not. If you need to perform some more sophisticated manipulation of asset requirements, you can define the ``media`` property directly. This is done by defining a widget property that returns an instance of -``forms.Media``. The constructor for ``forms.Media`` accepts ``css`` +``forms.Media``. The constructor for ``forms.Media`` accepts ``css`` and ``js`` keyword arguments in the same format as that used in a static media definition. diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index c02d4d7809..a5deeb324a 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -410,7 +410,7 @@ you've manually saved the instance produced by the form, you can invoke Calling ``save_m2m()`` is only required if you use ``save(commit=False)``. 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: +is saved without the need for any additional method calls. For example: .. code-block:: pycon @@ -490,7 +490,7 @@ include that field. Django will prevent any attempt to save an incomplete model, so if the model does not allow the missing fields to be empty, and does not provide a default value for the missing fields, any attempt to - ``save()`` a ``ModelForm`` with missing fields will fail. To + ``save()`` a ``ModelForm`` with missing fields will fail. To avoid this failure, you must instantiate your model with initial values for the missing, but required fields:: @@ -1107,7 +1107,7 @@ Overriding ``clean()`` on a ``ModelFormSet`` Just like with a ``ModelForm``, by default the ``clean()`` method of a ``ModelFormSet`` will validate that none of the items in the formset violate the unique constraints on your model (either ``unique``, ``unique_together`` or -``unique_for_date|month|year``). If you want to override the ``clean()`` method +``unique_for_date|month|year``). If you want to override the ``clean()`` method on a ``ModelFormSet`` and maintain this validation, you must call the parent class's ``clean`` method:: diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt index b9a9bbf416..9896a6032b 100644 --- a/docs/topics/http/file-uploads.txt +++ b/docs/topics/http/file-uploads.txt @@ -313,9 +313,9 @@ list:: :class:`~django.middleware.csrf.CsrfViewMiddleware` which is enabled by default. This means you will need to use :func:`~django.views.decorators.csrf.csrf_exempt` on your view to allow you - to change the upload handlers. You will then need to use + to change the upload handlers. You will then need to use :func:`~django.views.decorators.csrf.csrf_protect` on the function that - actually processes the request. Note that this means that the handlers may + actually processes the request. Note that this means that the handlers may start receiving the file upload before the CSRF checks have been done. Example code:: diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index 183ee6d184..752522818b 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -699,7 +699,7 @@ 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 -:ref:`deploy more than one instance of the admin <multiple-admin-sites>`. In a +: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). diff --git a/docs/topics/i18n/formatting.txt b/docs/topics/i18n/formatting.txt index e1b6213ca2..15dde5f82d 100644 --- a/docs/topics/i18n/formatting.txt +++ b/docs/topics/i18n/formatting.txt @@ -150,7 +150,7 @@ want to create your own, because a format file 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, set your :setting:`FORMAT_MODULE_PATH` setting to the +first. To do that, set your :setting:`FORMAT_MODULE_PATH` setting to the package where format files will exist, for instance:: FORMAT_MODULE_PATH = [ diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 3d6503dfc5..e3d60d33b5 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -560,7 +560,7 @@ languages: The ``name``, ``name_local``, and ``name_translated`` attributes of the dictionary contain the name of the language in English, in the language -itself, and in your current active language respectively. The ``bidi`` +itself, and in your current active language respectively. The ``bidi`` attribute is True only for bi-directional languages. The source of the language information is the ``django.conf.locale`` module. @@ -1704,7 +1704,7 @@ otherwise, they'll be tacked together without whitespace! Due to the way the ``gettext`` tools work internally and because we want to allow non-ASCII source strings in Django's core and your applications, you **must** use UTF-8 as the encoding for your ``.po`` files (the default when - ``.po`` files are created). This means that everybody will be using the + ``.po`` files are created). This means that everybody will be using the same encoding, which is important when Django processes the ``.po`` files. .. admonition:: Fuzzy entries @@ -2082,7 +2082,7 @@ For example, your :setting:`MIDDLEWARE` might look like this:: ``LocaleMiddleware`` tries to determine the user's language preference by following this algorithm: -* First, it looks for the language prefix in the requested URL. This is +* First, it looks for the language prefix in the requested URL. This is only performed when you are using the ``i18n_patterns`` function in your root URLconf. See :ref:`url-internationalization` for more information about the language prefix and how to internationalize URL patterns. @@ -2178,7 +2178,7 @@ translations for the same literal: precedence, with the ones appearing first having higher precedence than the ones appearing later. #. Then, it looks for and uses if it exists a ``locale`` directory in each - of the installed apps listed in :setting:`INSTALLED_APPS`. The ones + of the installed apps listed in :setting:`INSTALLED_APPS`. The ones appearing first have higher precedence than the ones appearing later. #. Finally, the Django-provided base translation in :source:`django/conf/locale` is used as a fallback. diff --git a/docs/topics/signing.txt b/docs/topics/signing.txt index c0394da2e5..4e7da9eb14 100644 --- a/docs/topics/signing.txt +++ b/docs/topics/signing.txt @@ -148,7 +148,7 @@ your :setting:`SECRET_KEY`: {'message': 'Hello!'} Using salt in this way puts the different signatures into different -namespaces. A signature that comes from one namespace (a particular salt +namespaces. A signature that comes from one namespace (a particular salt value) cannot be used to validate the same plaintext string in a different namespace that is using a different salt setting. The result is to prevent an attacker from using a signed string generated in one place in the code as input diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt index b6146253c1..fcc9c782c7 100644 --- a/docs/topics/testing/advanced.txt +++ b/docs/topics/testing/advanced.txt @@ -560,7 +560,7 @@ and tear down the test suite. ``debug_mode`` specifies what the :setting:`DEBUG` setting should be set to prior to running tests. - ``parallel`` specifies the number of processes. If ``parallel`` is greater + ``parallel`` specifies the number of processes. If ``parallel`` is greater than ``1``, the test suite will run in ``parallel`` processes. If there are fewer test case classes than configured processes, Django will reduce the number of processes accordingly. Each process gets its own database. This diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index ac4110943a..80e6663f6b 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -84,7 +84,7 @@ your project's ``manage.py`` utility: $ ./manage.py test Test discovery is based on the unittest module's :py:ref:`built-in test -discovery <unittest-test-discovery>`. By default, this will discover tests in +discovery <unittest-test-discovery>`. By default, this will discover tests in any file named ``test*.py`` under the current working directory. You can specify particular tests to run by supplying any number of "test diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index 7574695b21..7943b3dcac 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -2057,7 +2057,7 @@ Django, such as your machine's mail server, if you're running one.) During test running, each outgoing email is saved in ``django.core.mail.outbox``. This is a list of all -:class:`~django.core.mail.EmailMessage` instances that have been sent. The +: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 |