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 /docs/ref | |
| parent | 01a460f23e470555a733b8980401402b7947bb9f (diff) | |
Refs #36485 -- Removed double spaces after periods in sentences.
Diffstat (limited to 'docs/ref')
33 files changed, 221 insertions, 217 deletions
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. |