From 4286a23df64f6ce3b9b6ed097f4d1aac7d9e0de4 Mon Sep 17 00:00:00 2001 From: Natalia <124304+nessita@users.noreply.github.com> Date: Fri, 22 Aug 2025 12:36:48 -0300 Subject: [PATCH] Refs #36485 -- Removed double spaces after periods in sentences. --- docs/howto/auth-remote-user.txt | 8 +-- docs/howto/custom-model-fields.txt | 2 +- docs/howto/custom-template-tags.txt | 6 +- docs/howto/static-files/index.txt | 2 +- .../contributing/bugs-and-features.txt | 2 +- docs/internals/deprecation.txt | 12 ++-- docs/internals/mailing-lists.txt | 2 +- docs/intro/tutorial01.txt | 2 +- docs/intro/tutorial05.txt | 2 +- docs/intro/tutorial07.txt | 2 +- docs/misc/design-philosophies.txt | 2 +- docs/misc/distributions.txt | 2 +- docs/ref/class-based-views/mixins-simple.txt | 4 +- docs/ref/clickjacking.txt | 2 +- docs/ref/contrib/admin/index.txt | 12 ++-- docs/ref/contrib/auth.txt | 8 +-- docs/ref/contrib/gis/commands.txt | 8 +-- docs/ref/contrib/gis/db-api.txt | 8 +-- docs/ref/contrib/gis/deployment.txt | 4 +- docs/ref/contrib/gis/feeds.txt | 2 +- docs/ref/contrib/gis/functions.txt | 4 +- docs/ref/contrib/gis/gdal.txt | 20 +++--- docs/ref/contrib/gis/geoquerysets.txt | 20 +++--- docs/ref/contrib/gis/geos.txt | 71 ++++++++++--------- docs/ref/contrib/gis/install/geolibs.txt | 10 +-- docs/ref/contrib/gis/layermapping.txt | 30 ++++---- docs/ref/contrib/gis/measure.txt | 7 +- docs/ref/contrib/gis/model-api.txt | 55 +++++++------- docs/ref/contrib/gis/tutorial.txt | 38 +++++----- docs/ref/databases.txt | 12 ++-- docs/ref/django-admin.txt | 4 +- docs/ref/forms/api.txt | 4 +- docs/ref/forms/fields.txt | 18 ++--- docs/ref/logging.txt | 2 +- docs/ref/middleware.txt | 2 +- docs/ref/models/fields.txt | 14 ++-- docs/ref/models/querysets.txt | 6 +- docs/ref/paginator.txt | 2 +- docs/ref/request-response.txt | 2 +- docs/ref/settings.txt | 4 +- docs/ref/signals.txt | 7 +- docs/ref/templates/api.txt | 10 +-- docs/ref/templates/builtins.txt | 44 ++++++------ docs/ref/templates/language.txt | 2 +- docs/ref/utils.txt | 2 +- docs/releases/0.96.txt | 4 +- docs/releases/1.1.2.txt | 6 +- docs/releases/1.10.txt | 4 +- docs/releases/1.2.6.txt | 2 +- docs/releases/1.2.txt | 18 ++--- docs/releases/1.3.1.txt | 2 +- docs/releases/1.3.txt | 8 +-- docs/releases/1.5.txt | 2 +- docs/releases/1.6.txt | 4 +- docs/releases/1.8.txt | 2 +- docs/releases/1.9.txt | 2 +- docs/releases/2.1.txt | 2 +- docs/topics/auth/customizing.txt | 4 +- docs/topics/auth/default.txt | 4 +- docs/topics/auth/passwords.txt | 4 +- docs/topics/cache.txt | 8 +-- .../class-based-views/generic-display.txt | 4 +- .../class-based-views/generic-editing.txt | 4 +- docs/topics/class-based-views/index.txt | 2 +- docs/topics/conditional-view-processing.txt | 2 +- docs/topics/db/instrumentation.txt | 2 +- docs/topics/db/models.txt | 2 +- docs/topics/db/queries.txt | 2 +- docs/topics/db/transactions.txt | 2 +- docs/topics/forms/formsets.txt | 6 +- docs/topics/forms/media.txt | 2 +- docs/topics/forms/modelforms.txt | 6 +- docs/topics/http/file-uploads.txt | 4 +- docs/topics/http/urls.txt | 2 +- docs/topics/i18n/formatting.txt | 2 +- docs/topics/i18n/translation.txt | 8 +-- docs/topics/signing.txt | 2 +- docs/topics/testing/advanced.txt | 2 +- docs/topics/testing/overview.txt | 2 +- docs/topics/testing/tools.txt | 2 +- 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 -` attribute. Django can be configured to make +` 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 `. 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. `. * 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` 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 ` 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` 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 `. 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 ` 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 ` 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 `. 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 `. + backend. See the :ref:`custom ModelAdmin example `. 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 `). @@ -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'] `. See + authentication. It authenticates using usernames passed in + :attr:`request.META['REMOTE_USER'] `. See the :doc:`Authenticating against 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 `. .. 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 `. .. 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 ` 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 -`. For an overview of what lookups are +`. For an overview of what lookups are compatible with a particular spatial backend, refer to the :ref:`spatial lookup compatibility table `. @@ -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 `_. +: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 +`_. 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 ` *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 ` 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 `_. .. [#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 `_) 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 `_) 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 `_ 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] [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 ` (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 ``