From b784768eef75afb32f6d2ce7166551a528bce0ec Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Thu, 9 Feb 2023 16:48:46 +0100 Subject: [4.2.x] Refs #34140 -- Applied rst code-block to non-Python examples. Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for reviews. Backport of 534ac4829764f317cf2fbc4a18354fcc998c1425 from main. --- docs/ref/applications.txt | 4 +- .../class-based-views/mixins-multiple-object.txt | 10 +- docs/ref/contrib/admin/index.txt | 8 +- docs/ref/contrib/contenttypes.txt | 52 +- docs/ref/contrib/gis/db-api.txt | 48 +- docs/ref/contrib/gis/functions.txt | 28 +- docs/ref/contrib/gis/gdal.txt | 254 ++++++--- docs/ref/contrib/gis/geoip2.txt | 4 +- docs/ref/contrib/gis/geoquerysets.txt | 20 +- docs/ref/contrib/gis/geos.txt | 154 +++-- docs/ref/contrib/gis/install/geolibs.txt | 56 +- docs/ref/contrib/gis/install/index.txt | 46 +- docs/ref/contrib/gis/install/postgis.txt | 8 +- docs/ref/contrib/gis/install/spatialite.txt | 24 +- docs/ref/contrib/gis/layermapping.txt | 16 +- docs/ref/contrib/gis/measure.txt | 44 +- docs/ref/contrib/gis/testing.txt | 24 +- docs/ref/contrib/gis/tutorial.txt | 76 ++- docs/ref/contrib/messages.txt | 8 +- docs/ref/contrib/postgres/aggregates.txt | 23 +- docs/ref/contrib/postgres/expressions.txt | 4 +- docs/ref/contrib/postgres/fields.txt | 72 ++- docs/ref/contrib/postgres/forms.txt | 8 +- docs/ref/contrib/postgres/functions.txt | 8 +- docs/ref/contrib/postgres/lookups.txt | 12 +- docs/ref/contrib/postgres/search.txt | 64 ++- docs/ref/contrib/redirects.txt | 4 +- docs/ref/contrib/sitemaps.txt | 4 +- docs/ref/contrib/sites.txt | 4 +- docs/ref/contrib/syndication.txt | 4 +- docs/ref/databases.txt | 22 +- docs/ref/django-admin.txt | 200 +++++-- docs/ref/files/file.txt | 6 +- docs/ref/forms/api.txt | 208 +++++-- docs/ref/forms/fields.txt | 68 ++- docs/ref/forms/widgets.txt | 20 +- docs/ref/models/conditional-expressions.txt | 32 +- docs/ref/models/database-functions.txt | 290 +++++++--- docs/ref/models/expressions.txt | 76 ++- docs/ref/models/fields.txt | 16 +- docs/ref/models/instances.txt | 22 +- docs/ref/models/options.txt | 12 +- docs/ref/models/querysets.txt | 208 +++++-- docs/ref/models/relations.txt | 24 +- docs/ref/request-response.txt | 100 +++- docs/ref/settings.txt | 4 +- docs/ref/signals.txt | 8 +- docs/ref/template-response.txt | 4 +- docs/ref/templates/api.txt | 38 +- docs/ref/templates/builtins.txt | 626 +++++++++++++++------ docs/ref/templates/language.txt | 126 +++-- docs/ref/unicode.txt | 12 +- docs/ref/urlresolvers.txt | 8 +- docs/ref/utils.txt | 22 +- 54 files changed, 2427 insertions(+), 816 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index af387ac884..7649f86132 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -9,7 +9,9 @@ and provides introspection. It also maintains a list of available :doc:`models `. This registry is called :attr:`~django.apps.apps` and it's available in -:mod:`django.apps`:: +:mod:`django.apps`: + +.. code-block:: pycon >>> from django.apps import apps >>> apps.get_app_config('admin').verbose_name diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt index 52d5d976db..5049314d7c 100644 --- a/docs/ref/class-based-views/mixins-multiple-object.txt +++ b/docs/ref/class-based-views/mixins-multiple-object.txt @@ -18,9 +18,11 @@ Multiple object mixins path('objects/page/', PaginatedView.as_view()), * Pass the page number via the ``page`` query-string parameter. For - example, a URL would look like this:: + example, a URL would look like this: - /objects/?page=3 + .. code-block:: text + + /objects/?page=3 These values and lists are 1-based, not 0-based, so the first page would be represented as page ``1``. @@ -29,7 +31,9 @@ Multiple object mixins `. As a special case, you are also permitted to use ``last`` as a value for - ``page``:: + ``page``: + + .. code-block:: text /objects/?page=last diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index ec1450fa83..718f25411b 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -3236,7 +3236,9 @@ with an instance namespace corresponding to the name of the Site instance. So - if you wanted to get a reference to the Change view for a particular ``Choice`` object (from the polls application) in the default admin, you would -call:: +call: + +.. code-block:: pycon >>> from django.urls import reverse >>> c = Choice.objects.get(...) @@ -3249,7 +3251,9 @@ This will find the first registered instance of the admin application If you want to find a URL in a specific admin instance, provide the name of that instance as a ``current_app`` hint to the reverse call. For example, if you specifically wanted the admin view from the admin instance named -``custom``, you would need to call:: +``custom``, you would need to call: + +.. code-block:: pycon >>> change_url = reverse('admin:polls_choice_change', args=(c.id,), current_app='custom') diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index d115d434ac..dcea4e2d2f 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -121,7 +121,9 @@ model it represents, or to retrieve objects from that model: For example, we could look up the :class:`~django.contrib.contenttypes.models.ContentType` for the -:class:`~django.contrib.auth.models.User` model:: +:class:`~django.contrib.auth.models.User` model: + +.. code-block:: pycon >>> from django.contrib.contenttypes.models import ContentType >>> user_type = ContentType.objects.get(app_label='auth', model='user') @@ -130,7 +132,9 @@ For example, we could look up the And then use it to query for a particular :class:`~django.contrib.auth.models.User`, or to get access -to the ``User`` model class:: +to the ``User`` model class: + +.. code-block:: pycon >>> user_type.model_class() @@ -219,7 +223,9 @@ The :meth:`~ContentTypeManager.get_for_model()` method is especially useful when you know you need to work with a :class:`ContentType ` but don't want to go to the trouble of obtaining the model's metadata to perform a manual -lookup:: +lookup: + +.. code-block:: pycon >>> from django.contrib.auth.models import User >>> ContentType.objects.get_for_model(User) @@ -340,7 +346,9 @@ This will enable an API similar to the one used for a normal :class:`~django.db.models.ForeignKey`; each ``TaggedItem`` will have a ``content_object`` field that returns the object it's related to, and you can also assign to that field or use it when -creating a ``TaggedItem``:: +creating a ``TaggedItem``: + +.. code-block:: pycon >>> from django.contrib.auth.models import User >>> guido = User.objects.get(username='Guido') @@ -351,7 +359,9 @@ creating a ``TaggedItem``:: If the related object is deleted, the ``content_type`` and ``object_id`` fields remain set to their original values and the ``GenericForeignKey`` returns -``None``:: +``None``: + +.. code-block:: pycon >>> guido.delete() >>> t.content_object # returns None @@ -360,7 +370,9 @@ Due to the way :class:`~django.contrib.contenttypes.fields.GenericForeignKey` is implemented, you cannot use such fields directly with filters (``filter()`` and ``exclude()``, for example) via the database API. Because a :class:`~django.contrib.contenttypes.fields.GenericForeignKey` isn't a -normal field object, these examples will *not* work:: +normal field object, these examples will *not* work: + +.. code-block:: pycon # This will fail >>> TaggedItem.objects.filter(content_object=guido) @@ -393,7 +405,9 @@ a "reverse" generic relationship to enable an additional API. For example:: tags = GenericRelation(TaggedItem) ``Bookmark`` instances will each have a ``tags`` attribute, which can -be used to retrieve their associated ``TaggedItems``:: +be used to retrieve their associated ``TaggedItems``: + +.. code-block:: pycon >>> b = Bookmark(url='https://www.djangoproject.com/') >>> b.save() @@ -405,7 +419,9 @@ be used to retrieve their associated ``TaggedItems``:: , ]> You can also use ``add()``, ``create()``, or ``set()`` to create -relationships:: +relationships: + +.. code-block:: pycon >>> t3 = TaggedItem(tag='Web development') >>> b.tags.add(t3, bulk=False) @@ -417,7 +433,9 @@ relationships:: >>> b.tags.all() , ]> -The ``remove()`` call will bulk delete the specified model objects:: +The ``remove()`` call will bulk delete the specified model objects: + +.. code-block:: pycon >>> b.tags.remove(t3) >>> b.tags.all() @@ -426,7 +444,9 @@ The ``remove()`` call will bulk delete the specified model objects:: ]> The ``clear()`` method can be used to bulk delete all related objects for an -instance:: +instance: + +.. code-block:: pycon >>> b.tags.clear() >>> b.tags.all() @@ -440,14 +460,18 @@ Defining :class:`~django.contrib.contenttypes.fields.GenericRelation` with tags = GenericRelation(TaggedItem, related_query_name='bookmark') This enables filtering, ordering, and other query operations on ``Bookmark`` -from ``TaggedItem``:: +from ``TaggedItem``: + +.. code-block:: pycon >>> # Get all tags belonging to bookmarks containing `django` in the url >>> TaggedItem.objects.filter(bookmark__url__contains='django') , ]> If you don't add the ``related_query_name``, you can do the same types of -lookups manually:: +lookups manually: + +.. code-block:: pycon >>> bookmarks = Bookmark.objects.filter(url__contains='django') >>> bookmark_type = ContentType.objects.get_for_model(Bookmark) @@ -491,7 +515,9 @@ Generic relations and aggregation :doc:`Django's database aggregation API ` works with a :class:`~django.contrib.contenttypes.fields.GenericRelation`. For example, you -can find out how many tags all the bookmarks have:: +can find out how many tags all the bookmarks have: + +.. code-block:: pycon >>> Bookmark.objects.aggregate(Count('tags')) {'tags__count': 3} diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index d215eb1ecb..e23bc5afb3 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -37,13 +37,17 @@ Creating and Saving Models with Geometry Fields =============================================== Here is an example of how to create a geometry object (assuming the ``Zipcode`` -model):: +model): + +.. code-block:: pycon >>> from zipcode.models import Zipcode >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))') >>> z.save() -:class:`~django.contrib.gis.geos.GEOSGeometry` objects may also be used to save geometric models:: +:class:`~django.contrib.gis.geos.GEOSGeometry` objects may also be used to save geometric models: + +.. code-block:: pycon >>> from django.contrib.gis.geos import GEOSGeometry >>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))') @@ -53,7 +57,9 @@ model):: Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a different SRID value) than that of the field, then it will be implicitly transformed into the SRID of the model's field, using the spatial database's -transform procedure:: +transform procedure: + +.. code-block:: pycon >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal' >>> z = Zipcode(code=78212, poly=poly_3084) @@ -82,14 +88,18 @@ The raster field will therefore accept any input that is accepted by the :class:`~django.contrib.gis.gdal.GDALRaster` constructor. Here is an example of how to create a raster object from a raster file -``volcano.tif`` (assuming the ``Elevation`` model):: +``volcano.tif`` (assuming the ``Elevation`` model): + +.. code-block:: pycon >>> from elevation.models import Elevation >>> dem = Elevation(name='Volcano', rast='/path/to/raster/volcano.tif') >>> dem.save() :class:`~django.contrib.gis.gdal.GDALRaster` objects may also be used to save -raster models:: +raster models: + +.. code-block:: pycon >>> from django.contrib.gis.gdal import GDALRaster >>> rast = GDALRaster({'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326, @@ -97,7 +107,9 @@ raster models:: >>> dem = Elevation(name='Canyon', rast=rast) >>> dem.save() -Note that this equivalent to:: +Note that this equivalent to: + +.. code-block:: pycon >>> dem = Elevation.objects.create( ... name='Canyon', @@ -125,12 +137,16 @@ Geometry Lookups ---------------- Geographic queries with geometries take the following general form (assuming -the ``Zipcode`` model used in the :doc:`model-api`):: +the ``Zipcode`` model used in the :doc:`model-api`): + +.. code-block:: pycon >>> qs = Zipcode.objects.filter(__=) >>> qs = Zipcode.objects.exclude(...) -For example:: +For example: + +.. code-block:: pycon >>> qs = Zipcode.objects.filter(poly__contains=pnt) >>> qs = Elevation.objects.filter(poly__contains=rst) @@ -157,13 +173,17 @@ used to pass a band index. On the right hand side, a tuple of the raster and band index can be specified. This results in the following general form for lookups involving rasters -(assuming the ``Elevation`` model used in the :doc:`model-api`):: +(assuming the ``Elevation`` model used in the :doc:`model-api`): + +.. code-block:: pycon >>> qs = Elevation.objects.filter(__=) >>> qs = Elevation.objects.filter(____=) >>> qs = Elevation.objects.filter(__=() -For example:: +For example: + +.. code-block:: pycon >>> qs = Elevation.objects.filter(rast__contains=geom) >>> qs = Elevation.objects.filter(rast__contains=rst) @@ -256,7 +276,9 @@ For example, let's say we have a ``SouthTexasCity`` model (from the # is used, units are in meters. point = models.PointField(srid=32140) -Then distance queries may be performed as follows:: +Then distance queries may be performed as follows: + +.. code-block:: pycon >>> from django.contrib.gis.geos import GEOSGeometry >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance`` @@ -273,7 +295,9 @@ Then distance queries may be performed as follows:: Raster queries work the same way by replacing the geometry field ``point`` with a raster field, or the ``pnt`` object with a raster object, or both. To specify the band index of a raster input on the right hand side, a 3-tuple can be -passed to the lookup as follows:: +passed to the lookup as follows: + +.. code-block:: pycon >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(rst, 2, D(km=7))) diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index a07feebfb7..a1846b86b6 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/docs/ref/contrib/gis/functions.txt @@ -8,7 +8,9 @@ Geographic Database Functions The functions documented on this page allow users to access geographic database functions to be used in annotations, aggregations, or filters in Django. -Example:: +Example: + +.. code-block:: pycon >>> from django.contrib.gis.db.models.functions import Length >>> Track.objects.annotate(length=Length('line')).filter(length__gt=100) @@ -61,7 +63,9 @@ Accepts a single geographic field or expression and returns a `GeoJSON is not a complete GeoJSON structure but only the ``geometry`` key content of a GeoJSON structure. See also :doc:`/ref/contrib/gis/serializers`. -Example:: +Example: + +.. code-block:: pycon >>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json {"type":"Point","coordinates":[-87.65018,41.85039]} @@ -94,7 +98,9 @@ SpatiaLite Accepts a single geographic field or expression and returns a `Geographic Markup Language (GML)`__ representation of the geometry. -Example:: +Example: + +.. code-block:: pycon >>> qs = Zipcode.objects.annotate(gml=AsGML('poly')) >>> print(qs[0].gml) @@ -123,7 +129,9 @@ __ https://en.wikipedia.org/wiki/Geography_Markup_Language Accepts a single geographic field or expression and returns a `Keyhole Markup Language (KML)`__ representation of the geometry. -Example:: +Example: + +.. code-block:: pycon >>> qs = Zipcode.objects.annotate(kml=AsKML('poly')) >>> print(qs[0].kml) @@ -176,7 +184,9 @@ Oracle, `PostGIS `__, SpatiaLite Accepts a single geographic field or expression and returns a `Well-known binary (WKB)`_ representation of the geometry. -Example:: +Example: + +.. code-block:: pycon >>> bytes(City.objects.annotate(wkb=AsWKB('point')).get(name='Chelyabinsk').wkb) b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@' @@ -193,7 +203,9 @@ Oracle, `PostGIS `__, SpatiaLite Accepts a single geographic field or expression and returns a `Well-known text (WKT)`_ representation of the geometry. -Example:: +Example: + +.. code-block:: pycon >>> City.objects.annotate(wkt=AsWKT('point')).get(name='Chelyabinsk').wkt 'POINT (55.137555 61.451728)' @@ -276,7 +288,9 @@ resource-intensive). In the following example, the distance from the city of Hobart to every other :class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity`` -queryset is calculated:: +queryset is calculated: + +.. code-block:: pycon >>> from django.contrib.gis.db.models.functions import Distance >>> pnt = AustraliaCity.objects.get(name='Hobart').point diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index 75915e6751..6100bc2698 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/docs/ref/contrib/gis/gdal.txt @@ -36,7 +36,9 @@ The GDAL/OGR tools described here are designed to help you read in your geospatial data, in order for most of them to be useful you have to have some data to work with. If you're starting out and don't yet have any data of your own to use, GeoDjango tests contain a number of -data sets that you can use for testing. You can download them here:: +data sets that you can use for testing. You can download them here: + +.. code-block:: shell $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf} $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/rasters/raster.tif @@ -75,7 +77,9 @@ each feature in that layer. Once you've created your ``DataSource``, you can find out how many layers of data it contains by accessing the :attr:`layer_count` property, or (equivalently) by using the ``len()`` function. For information on - accessing the layers of data themselves, see the next section:: + accessing the layers of data themselves, see the next section: + + .. code-block:: pycon >>> from django.contrib.gis.gdal import DataSource >>> ds = DataSource('/path/to/your/cities.shp') @@ -110,7 +114,9 @@ __ https://gdal.org/drivers/vector/ Typically, all the features in a given layer have the same geometry type. The :attr:`geom_type` property of a layer is an :class:`OGRGeomType` that identifies the feature type. We can use it to print out some basic - information about each layer in a :class:`DataSource`:: + information about each layer in a :class:`DataSource`: + + .. code-block:: pycon >>> for layer in ds: ... print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)) @@ -120,7 +126,9 @@ __ https://gdal.org/drivers/vector/ The example output is from the cities data source, loaded above, which evidently contains one layer, called ``"cities"``, which contains three point features. For simplicity, the examples below assume that you've - stored that layer in the variable ``layer``:: + stored that layer in the variable ``layer``: + + .. code-block:: pycon >>> layer = ds[0] @@ -128,19 +136,25 @@ __ https://gdal.org/drivers/vector/ Returns the name of this layer in the data source. + .. code-block:: pycon + >>> layer.name 'cities' .. attribute:: num_feat - Returns the number of features in the layer. Same as ``len(layer)``:: + Returns the number of features in the layer. Same as ``len(layer)``: + + .. code-block:: pycon >>> layer.num_feat 3 .. attribute:: geom_type - Returns the geometry type of the layer, as an :class:`OGRGeomType` object:: + Returns the geometry type of the layer, as an :class:`OGRGeomType` object: + + .. code-block:: pycon >>> layer.geom_type.name 'Point' @@ -148,14 +162,18 @@ __ https://gdal.org/drivers/vector/ .. attribute:: num_fields Returns the number of fields in the layer, i.e the number of fields of - data associated with each feature in the layer:: + data associated with each feature in the layer: + + .. code-block:: pycon >>> layer.num_fields 4 .. attribute:: fields - Returns a list of the names of each of the fields in this layer:: + Returns a list of the names of each of the fields in this layer: + + .. code-block:: pycon >>> layer.fields ['Name', 'Population', 'Density', 'Created'] @@ -163,7 +181,9 @@ __ https://gdal.org/drivers/vector/ .. attribute field_types Returns a list of the data types of each of the fields in this layer. These - are subclasses of ``Field``, discussed below:: + are subclasses of ``Field``, discussed below: + + .. code-block:: pycon >>> [ft.__name__ for ft in layer.field_types] ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] @@ -171,7 +191,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: field_widths Returns a list of the maximum field widths for each of the fields in this - layer:: + layer: + + .. code-block:: pycon >>> layer.field_widths [80, 11, 24, 10] @@ -179,14 +201,18 @@ __ https://gdal.org/drivers/vector/ .. attribute:: field_precisions Returns a list of the numeric precisions for each of the fields in this - layer. This is meaningless (and set to zero) for non-numeric fields:: + layer. This is meaningless (and set to zero) for non-numeric fields: + + .. code-block:: pycon >>> layer.field_precisions [0, 0, 15, 0] .. attribute:: extent - Returns the spatial extent of this layer, as an :class:`Envelope` object:: + Returns the spatial extent of this layer, as an :class:`Envelope` object: + + .. code-block:: pycon >>> layer.extent.tuple (-104.609252, 29.763374, -95.23506, 38.971823) @@ -194,7 +220,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: srs Property that returns the :class:`SpatialReference` associated with this - layer:: + layer: + + .. code-block:: pycon >>> print(layer.srs) GEOGCS["GCS_WGS_1984", @@ -212,7 +240,9 @@ __ https://gdal.org/drivers/vector/ layer. A spatial filter can only be set with an :class:`OGRGeometry` instance, a 4-tuple extent, or ``None``. When set with something other than ``None``, only features that intersect the filter will be returned when - iterating over the layer:: + iterating over the layer: + + .. code-block:: pycon >>> print(layer.spatial_filter) None @@ -233,7 +263,9 @@ __ https://gdal.org/drivers/vector/ .. method:: get_fields() A method that returns a list of the values of a given field for each - feature in the layer:: + feature in the layer: + + .. code-block:: pycon >>> layer.get_fields('Name') ['Pueblo', 'Lawrence', 'Houston'] @@ -243,7 +275,9 @@ __ https://gdal.org/drivers/vector/ A method that returns a list containing the geometry of each feature in the layer. If the optional argument ``geos`` is set to ``True`` then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry` - objects. Otherwise, they are returned as :class:`OGRGeometry` objects:: + objects. Otherwise, they are returned as :class:`OGRGeometry` objects: + + .. code-block:: pycon >>> [pt.tuple for pt in layer.get_geoms()] [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)] @@ -273,7 +307,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: geom - Returns the geometry for this feature, as an ``OGRGeometry`` object:: + Returns the geometry for this feature, as an ``OGRGeometry`` object: + + .. code-block:: pycon >>> city.geom.tuple (-104.609252, 38.255001) @@ -281,7 +317,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: get A method that returns the value of the given field (specified by name) - for this feature, **not** a ``Field`` wrapper object:: + for this feature, **not** a ``Field`` wrapper object: + + .. code-block:: pycon >>> city.get('Population') 102121 @@ -309,7 +347,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: fid - Returns the feature identifier within the layer:: + Returns the feature identifier within the layer: + + .. code-block:: pycon >>> city.fid 0 @@ -317,7 +357,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: layer_name Returns the name of the :class:`Layer` that the feature came from. This - will be the same for all features in a given layer:: + will be the same for all features in a given layer: + + .. code-block:: pycon >>> city.layer_name 'cities' @@ -325,7 +367,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: index A method that returns the index of the given field name. This will be the - same for all features in a given layer:: + same for all features in a given layer: + + .. code-block:: pycon >>> city.index('Population') 1 @@ -337,7 +381,9 @@ __ https://gdal.org/drivers/vector/ .. attribute:: name - Returns the name of this field:: + Returns the name of this field: + + .. code-block:: pycon >>> city['Name'].name 'Name' @@ -345,14 +391,18 @@ __ https://gdal.org/drivers/vector/ .. attribute:: type Returns the OGR type of this field, as an integer. The ``FIELD_CLASSES`` - dictionary maps these values onto subclasses of ``Field``:: + dictionary maps these values onto subclasses of ``Field``: + + .. code-block:: pycon >>> city['Density'].type 2 .. attribute:: type_name - Returns a string with the name of the data type of this field:: + Returns a string with the name of the data type of this field: + + .. code-block:: pycon >>> city['Name'].type_name 'String' @@ -361,14 +411,18 @@ __ https://gdal.org/drivers/vector/ Returns the value of this field. The ``Field`` class itself returns the value as a string, but each subclass returns the value in the most - appropriate form:: + appropriate form: + + .. code-block:: pycon >>> city['Population'].value 102121 .. attribute:: width - Returns the width of this field:: + Returns the width of this field: + + .. code-block:: pycon >>> city['Name'].width 80 @@ -376,35 +430,45 @@ __ https://gdal.org/drivers/vector/ .. attribute:: precision Returns the numeric precision of this field. This is meaningless (and set - to zero) for non-numeric fields:: + to zero) for non-numeric fields: + + .. code-block:: pycon >>> city['Density'].precision 15 .. method:: as_double() - Returns the value of the field as a double (float):: + Returns the value of the field as a double (float): + + .. code-block:: pycon >>> city['Density'].as_double() 874.7 .. method:: as_int() - Returns the value of the field as an integer:: + Returns the value of the field as an integer: + + .. code-block:: pycon >>> city['Population'].as_int() 102121 .. method:: as_string() - Returns the value of the field as a string:: + Returns the value of the field as a string: + + .. code-block:: pycon >>> city['Name'].as_string() 'Pueblo' .. method:: as_datetime() - Returns the value of the field as a tuple of date and time components:: + Returns the value of the field as a tuple of date and time components: + + .. code-block:: pycon >>> city['Created'].as_datetime() (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0)) @@ -432,7 +496,9 @@ OGR Geometries around OGR's internal geometry representation. Thus, they allow for more efficient access to data when using :class:`DataSource`. Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference systems and -coordinate transformation:: +coordinate transformation: + +.. code-block:: pycon >>> from django.contrib.gis.gdal import OGRGeometry >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))') @@ -478,7 +544,9 @@ coordinate transformation:: .. attribute:: dimension Returns the number of coordinated dimensions of the geometry, i.e. 0 - for points, 1 for lines, and so forth:: + for points, 1 for lines, and so forth: + + .. code-block:: pycon >> polygon.dimension 2 @@ -490,14 +558,18 @@ coordinate transformation:: .. attribute:: geom_count - Returns the number of elements in this geometry:: + Returns the number of elements in this geometry: + + .. code-block:: pycon >>> polygon.geom_count 1 .. attribute:: point_count - Returns the number of points used to describe this geometry:: + Returns the number of points used to describe this geometry: + + .. code-block:: pycon >>> polygon.point_count 4 @@ -516,7 +588,9 @@ coordinate transformation:: .. attribute:: geom_name - Returns the name of the type of this geometry:: + Returns the name of the type of this geometry: + + .. code-block:: pycon >>> polygon.geom_name 'POLYGON' @@ -524,7 +598,9 @@ coordinate transformation:: .. attribute:: area Returns the area of this geometry, or 0 for geometries that do not contain - an area:: + an area: + + .. code-block:: pycon >>> polygon.area 25.0 @@ -536,7 +612,9 @@ coordinate transformation:: .. attribute:: extent Returns the envelope of this geometry as a 4-tuple, instead of as an - :class:`Envelope` object:: + :class:`Envelope` object: + + .. code-block:: pycon >>> point.extent (0.0, 0.0, 5.0, 5.0) @@ -547,7 +625,9 @@ coordinate transformation:: ``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, - or any input that :class:`SpatialReference` accepts. Example:: + or any input that :class:`SpatialReference` accepts. Example: + + .. code-block:: pycon >>> city.geom.srs.name 'GCS_WGS_1984' @@ -566,21 +646,27 @@ coordinate transformation:: .. attribute:: gml - Returns a string representation of this geometry in GML format:: + Returns a string representation of this geometry in GML format: + + .. code-block:: pycon >>> OGRGeometry('POINT(1 2)').gml '1,2' .. attribute:: hex - Returns a string representation of this geometry in HEX WKB format:: + Returns a string representation of this geometry in HEX WKB format: + + .. code-block:: pycon >>> OGRGeometry('POINT(1 2)').hex '0101000000000000000000F03F0000000000000040' .. attribute:: json - Returns a string representation of this geometry in JSON format:: + Returns a string representation of this geometry in JSON format: + + .. code-block:: pycon >>> OGRGeometry('POINT(1 2)').json '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }' @@ -592,7 +678,9 @@ coordinate transformation:: .. attribute:: wkb_size Returns the size of the WKB buffer needed to hold a WKB representation - of this geometry:: + of this geometry: + + .. code-block:: pycon >>> OGRGeometry('POINT(1 2)').wkb_size 21 @@ -616,7 +704,9 @@ coordinate transformation:: .. method:: close_rings() If there are any rings within this geometry that have not been closed, - this routine will do so by adding the starting point to the end:: + this routine will do so by adding the starting point to the end: + + .. code-block:: pycon >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)') >>> triangle.close_rings() @@ -706,7 +796,9 @@ coordinate transformation:: .. attribute:: tuple Returns the coordinates of a point geometry as a tuple, the - coordinates of a line geometry as a tuple of tuples, and so forth:: + coordinates of a line geometry as a tuple of tuples, and so forth: + + .. code-block:: pycon >>> OGRGeometry('POINT (1 2)').tuple (1.0, 2.0) @@ -721,14 +813,18 @@ coordinate transformation:: .. attribute:: x - Returns the X coordinate of this point:: + Returns the X coordinate of this point: + + .. code-block:: pycon >>> OGRGeometry('POINT (1 2)').x 1.0 .. attribute:: y - Returns the Y coordinate of this point:: + Returns the Y coordinate of this point: + + .. code-block:: pycon >>> OGRGeometry('POINT (1 2)').y 2.0 @@ -736,7 +832,9 @@ coordinate transformation:: .. attribute:: z Returns the Z coordinate of this point, or ``None`` if the point does not - have a Z coordinate:: + have a Z coordinate: + + .. code-block:: pycon >>> OGRGeometry('POINT (1 2 3)').z 3.0 @@ -745,14 +843,18 @@ coordinate transformation:: .. attribute:: x - Returns a list of X coordinates in this line:: + Returns a list of X coordinates in this line: + + .. code-block:: pycon >>> OGRGeometry('LINESTRING (1 2,3 4)').x [1.0, 3.0] .. attribute:: y - Returns a list of Y coordinates in this line:: + Returns a list of Y coordinates in this line: + + .. code-block:: pycon >>> OGRGeometry('LINESTRING (1 2,3 4)').y [2.0, 4.0] @@ -760,7 +862,9 @@ coordinate transformation:: .. attribute:: z Returns a list of Z coordinates in this line, or ``None`` if the line does - not have Z coordinates:: + not have Z coordinates: + + .. code-block:: pycon >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z [3.0, 6.0] @@ -794,7 +898,9 @@ coordinate transformation:: .. class:: OGRGeomType(type_input) This class allows for the representation of an OGR geometry type - in any of several ways:: + in any of several ways: + + .. code-block:: pycon >>> from django.contrib.gis.gdal import OGRGeomType >>> gt1 = OGRGeomType(3) # Using an integer for the type @@ -805,14 +911,18 @@ coordinate transformation:: .. attribute:: name - Returns a short-hand string form of the OGR Geometry type:: + Returns a short-hand string form of the OGR Geometry type: + + .. code-block:: pycon >>> gt1.name 'Polygon' .. attribute:: num - Returns the number corresponding to the OGR geometry type:: + Returns the number corresponding to the OGR geometry type: + + .. code-block:: pycon >>> gt1.num 3 @@ -820,7 +930,9 @@ coordinate transformation:: .. attribute:: django Returns the Django field type (a subclass of GeometryField) to use for - storing this OGR type, or ``None`` if there is no appropriate Django type:: + storing this OGR type, or ``None`` if there is no appropriate Django type: + + .. code-block:: pycon >>> gt1.django 'PolygonField' @@ -885,7 +997,9 @@ Coordinate System Objects * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, ``'NAD27'``, ``'NAD83'``) - Example:: + Example: + + .. code-block:: pycon >>> wgs84 = SpatialReference('WGS84') # shorthand string >>> wgs84 = SpatialReference(4326) # EPSG code @@ -907,7 +1021,9 @@ Coordinate System Objects Returns the value of the given string attribute node, ``None`` if the node doesn't exist. Can also take a tuple as a parameter, (target, child), where - child is the index of the attribute in the WKT. For example:: + child is the index of the attribute in the WKT. For example: + + .. code-block:: pycon >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]') >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326 @@ -1068,7 +1184,9 @@ Coordinate System Objects Represents a coordinate system transform. It is initialized with two :class:`SpatialReference`, representing the source and target coordinate systems, respectively. These objects should be used when performing the same -coordinate transformation repeatedly on different geometries:: +coordinate transformation repeatedly on different geometries: + +.. code-block:: pycon >>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83')) >>> for feat in layer: @@ -1721,7 +1839,9 @@ Key Default Usage The following example uses some of the options available for the `GTiff driver`__. The result is a compressed signed byte raster with an - internal tiling scheme. The internal tiles have a block size of 23 by 23:: + internal tiling scheme. The internal tiles have a block size of 23 by 23: + + .. code-block:: pycon >>> GDALRaster({ ... 'driver': 'GTiff', @@ -1787,7 +1907,9 @@ from a remote storage or returned from a view without being written to disk. ``/vsimem/``. Input provided as ``bytes`` has to be a full binary representation of a file. -For instance:: +For instance: + +.. code-block:: pycon # Read a raster as a file object from a remote source. >>> from urllib.request import urlopen @@ -1807,7 +1929,9 @@ dictionary representation and provide a ``name`` argument that starts with of the raster. Here's how to create a raster and return it as a file in an -:class:`~django.http.HttpResponse`:: +:class:`~django.http.HttpResponse`: + +.. code-block:: pycon >>> from django.http import HttpResponse >>> rst = GDALRaster({ @@ -1838,7 +1962,9 @@ Compressed rasters Instead decompressing the file and instantiating the resulting raster, GDAL can directly access compressed files using the ``/vsizip/``, ``/vsigzip/``, or -``/vsitar/`` virtual filesystems:: +``/vsitar/`` virtual filesystems: + +.. code-block:: pycon >>> from django.contrib.gis.gdal import GDALRaster >>> rst = GDALRaster('/vsizip/path/to/your/file.zip/path/to/raster.tif') @@ -1852,7 +1978,9 @@ GDAL can support online resources and storage providers transparently. As long as it's built with such capabilities. To access a public raster file with no authentication, you can use -``/vsicurl/``:: +``/vsicurl/``: + +.. code-block:: pycon >>> from django.contrib.gis.gdal import GDALRaster >>> rst = GDALRaster('/vsicurl/https://example.com/raster.tif') diff --git a/docs/ref/contrib/gis/geoip2.txt b/docs/ref/contrib/gis/geoip2.txt index c106acdf0f..e3d27555ec 100644 --- a/docs/ref/contrib/gis/geoip2.txt +++ b/docs/ref/contrib/gis/geoip2.txt @@ -31,7 +31,9 @@ __ https://github.com/maxmind/libmaxminddb/ Example ======= -Here is an example of its usage:: +Here is an example of its usage: + +.. code-block:: pycon >>> from django.contrib.gis.geoip2 import GeoIP2 >>> g = GeoIP2() diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index 53a8b6c3b9..42f0e82d83 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -856,7 +856,9 @@ Keyword Argument Description __ https://docs.oracle.com/en/database/oracle/oracle-database/21/spatl/ spatial-concepts.html#GUID-CE10AB14-D5EA-43BA-A647-DAC9EEF41EE6 -Example:: +Example: + +.. code-block:: pycon >>> from django.contrib.gis.db.models import Extent, Union >>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly')) @@ -886,7 +888,9 @@ Oracle, SpatiaLite Returns the extent of all ``geo_field`` in the ``QuerySet`` as a four-tuple, comprising the lower left coordinate and the upper right coordinate. -Example:: +Example: + +.. code-block:: pycon >>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly')) >>> print(qs['poly__extent']) @@ -903,7 +907,9 @@ Returns the 3D extent of all ``geo_field`` in the ``QuerySet`` as a six-tuple, comprising the lower left coordinate and upper right coordinate (each with x, y, and z coordinates). -Example:: +Example: + +.. code-block:: pycon >>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly')) >>> print(qs['poly__extent3d']) @@ -920,7 +926,9 @@ SpatiaLite Returns a ``LineString`` constructed from the point field geometries in the ``QuerySet``. Currently, ordering the queryset has no effect. -Example:: +Example: + +.. code-block:: pycon >>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(MakeLine('poly')) >>> print(qs['poly__makeline']) @@ -944,7 +952,9 @@ large querysets. If the computation time for using this method is too expensive, consider using :class:`Collect` instead. -Example:: +Example: + +.. code-block:: pycon >>> u = Zipcode.objects.aggregate(Union(poly)) # This may take a long time. >>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly)) # A more sensible approach. diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index 8f32883cc1..8c2628c750 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -50,7 +50,9 @@ Creating a Geometry :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:: +are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON: + +.. code-block:: pycon >>> from django.contrib.gis.geos import GEOSGeometry >>> pnt = GEOSGeometry('POINT(5 23)') # WKT @@ -60,12 +62,16 @@ are examples of creating the same geometry from WKT, HEX, WKB, and 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 -created by passing in the X and Y coordinates into its constructor:: +created by passing in the X and Y coordinates into its constructor: + +.. code-block:: pycon >>> from django.contrib.gis.geos import Point >>> pnt = Point(5, 23) -All these constructors take the keyword argument ``srid``. For example:: +All these constructors take the keyword argument ``srid``. For example: + +.. code-block:: pycon >>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point >>> print(GEOSGeometry('POINT (0 0)', srid=4326)) @@ -76,7 +82,9 @@ All these constructors take the keyword argument ``srid``. For example:: SRID=32140;POINT (0 0) Finally, there is the :func:`fromfile` factory method which returns a -:class:`GEOSGeometry` object from a file:: +:class:`GEOSGeometry` object from a file: + +.. code-block:: pycon >>> from django.contrib.gis.geos import fromfile >>> pnt = fromfile('/path/to/pnt.wkt') @@ -97,14 +105,18 @@ Geometries are Pythonic ----------------------- :class:`GEOSGeometry` objects are 'Pythonic', in other words components may be accessed, modified, and iterated over using standard Python conventions. -For example, you can iterate over the coordinates in a :class:`Point`:: +For example, you can iterate over the coordinates in a :class:`Point`: + +.. code-block:: pycon >>> pnt = Point(5, 23) >>> [coord for coord in pnt] [5.0, 23.0] With any geometry object, the :attr:`GEOSGeometry.coords` property -may be used to get the geometry coordinates as a Python tuple:: +may be used to get the geometry coordinates as a Python tuple: + +.. code-block:: pycon >>> pnt.coords (5.0, 23.0) @@ -112,7 +124,9 @@ may be used to get the geometry coordinates as a Python tuple:: 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` -returns a coordinate tuple:: +returns a coordinate tuple: + +.. code-block:: pycon >>> from django.contrib.gis.geos import LineString >>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0)) @@ -122,7 +136,9 @@ returns a coordinate tuple:: (50.0, 0.0) Whereas indexing on a :class:`Polygon` will return the ring -(a :class:`LinearRing` object) corresponding to the index:: +(a :class:`LinearRing` object) corresponding to the index: + +.. code-block:: pycon >>> from django.contrib.gis.geos import Polygon >>> poly = Polygon( ((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)) ) @@ -132,7 +148,9 @@ Whereas indexing on a :class:`Polygon` will return the ring (50.0, 0.0) In addition, coordinates/components of the geometry may added or modified, -just like a Python list:: +just like a Python list: + +.. code-block:: pycon >>> line[0] = (1.0, 1.0) >>> line.pop() @@ -141,7 +159,9 @@ just like a Python list:: >>> line.coords ((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0)) -Geometries support set-like operators:: +Geometries support set-like operators: + +.. code-block:: pycon >>> from django.contrib.gis.geos import LineString >>> ls1 = LineString((0, 0), (2, 2)) @@ -160,7 +180,9 @@ Geometries support set-like operators:: The :class:`~GEOSGeometry` equality operator uses :meth:`~GEOSGeometry.equals_exact`, not :meth:`~GEOSGeometry.equals`, i.e. it requires the compared geometries to have the same coordinates in the - same positions with the same SRIDs:: + same positions with the same SRIDs: + + .. code-block:: pycon >>> from django.contrib.gis.geos import LineString >>> ls1 = LineString((0, 0), (1, 1)) @@ -191,7 +213,9 @@ given ``geo_input`` argument, and then assumes the proper geometry subclass The ``srid`` parameter, if given, is set as the SRID of the created geometry if ``geo_input`` doesn't have an SRID. If different SRIDs are provided through the -``geo_input`` and ``srid`` parameters, ``ValueError`` is raised:: +``geo_input`` and ``srid`` parameters, ``ValueError`` is raised: + +.. code-block:: pycon >>> from django.contrib.gis.geos import GEOSGeometry >>> GEOSGeometry('POINT EMPTY', srid=4326).ewkt @@ -246,7 +270,9 @@ 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 >>> pnt = GEOSGeometry('POINT(5 23)') >>> pnt.geom_type @@ -307,7 +333,9 @@ 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 >>> pnt = Point(5, 23) >>> print(pnt.srid) @@ -671,7 +699,9 @@ Other Properties & Methods Converts this geometry to canonical form. If the ``clone`` keyword is set, then the geometry is not modified and a normalized clone of the geometry is - returned instead:: + returned instead: + + .. code-block:: pycon >>> g = MultiPoint(Point(0, 0), Point(2, 2), Point(1, 1)) >>> print(g) @@ -691,13 +721,17 @@ Other Properties & Methods ``Point`` objects are instantiated using arguments that represent the component coordinates of the point or with a single sequence coordinates. - For example, the following are equivalent:: + For example, the following are equivalent: + + .. code-block:: pycon >>> pnt = Point(5, 23) >>> pnt = Point([5, 23]) Empty ``Point`` objects may be instantiated by passing no arguments or an - empty sequence. The following are equivalent:: + empty sequence. The following are equivalent: + + .. code-block:: pycon >>> pnt = Point() >>> pnt = Point([]) @@ -709,19 +743,25 @@ Other Properties & Methods ``LineString`` objects are instantiated using arguments that are either a sequence of coordinates or :class:`Point` objects. For example, the - following are equivalent:: + following are equivalent: + + .. code-block:: pycon >>> ls = LineString((0, 0), (1, 1)) >>> ls = LineString(Point(0, 0), Point(1, 1)) In addition, ``LineString`` objects may also be created by passing in a - single sequence of coordinate or :class:`Point` objects:: + single sequence of coordinate or :class:`Point` objects: + + .. code-block:: pycon >>> ls = LineString( ((0, 0), (1, 1)) ) >>> ls = LineString( [Point(0, 0), Point(1, 1)] ) Empty ``LineString`` objects may be instantiated by passing no arguments - or an empty sequence. The following are equivalent:: + or an empty sequence. The following are equivalent: + + .. code-block:: pycon >>> ls = LineString() >>> ls = LineString([]) @@ -738,7 +778,9 @@ Other Properties & Methods ``LinearRing`` objects are constructed in the exact same way as :class:`LineString` objects, however the coordinates must be *closed*, in other words, the first coordinates must be the same as the last - coordinates. For example:: + coordinates. For example: + + .. code-block:: pycon >>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0)) @@ -757,7 +799,9 @@ Other Properties & Methods ``Polygon`` objects may be instantiated by passing in parameters that 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`:: + :class:`LinearRing`: + + .. code-block:: pycon >>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) @@ -779,7 +823,9 @@ Other Properties & Methods or ``>``, but as the comparison is made through Polygon's :class:`LineString`, it does not mean much (but is consistent and quick). You can always force the comparison with the :attr:`~GEOSGeometry.area` - property:: + property: + + .. code-block:: pycon >>> if poly_1.area > poly_2.area: >>> pass @@ -795,7 +841,9 @@ Geometry Collections .. class:: MultiPoint(*args, **kwargs) ``MultiPoint`` objects may be instantiated by passing in :class:`Point` - objects as arguments, or a single sequence of :class:`Point` objects:: + objects as arguments, or a single sequence of :class:`Point` objects: + + .. code-block:: pycon >>> mp = MultiPoint(Point(0, 0), Point(1, 1)) >>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) ) @@ -807,7 +855,9 @@ Geometry Collections ``MultiLineString`` objects may be instantiated by passing in :class:`LineString` objects as arguments, or a single sequence of - :class:`LineString` objects:: + :class:`LineString` objects: + + .. code-block:: pycon >>> ls1 = LineString((0, 0), (1, 1)) >>> ls2 = LineString((2, 2), (3, 3)) @@ -829,7 +879,9 @@ Geometry Collections .. class:: MultiPolygon(*args, **kwargs) ``MultiPolygon`` objects may be instantiated by passing :class:`Polygon` - objects as arguments, or a single sequence of :class:`Polygon` objects:: + objects as arguments, or a single sequence of :class:`Polygon` objects: + + .. code-block:: pycon >>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) ) @@ -843,7 +895,9 @@ Geometry Collections ``GeometryCollection`` objects may be instantiated by passing in other :class:`GEOSGeometry` as arguments, or a single sequence of - :class:`GEOSGeometry` objects:: + :class:`GEOSGeometry` objects: + + .. code-block:: pycon >>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) @@ -862,7 +916,9 @@ 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:: +For example: + +.. code-block:: pycon >>> from django.contrib.gis.geos import Point, Polygon >>> poly = Polygon.from_bbox((0, 0, 5, 5)) @@ -905,7 +961,9 @@ Geometry Factories :type file_h: a Python ``file`` object or a string path to the file :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import fromfile >>> g = fromfile('/home/bob/geom.wkt') @@ -921,7 +979,9 @@ Geometry Factories ``fromstr(string, srid)`` is equivalent to :class:`GEOSGeometry(string, srid) `. - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import fromstr >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326) @@ -937,7 +997,9 @@ and/or WKT input given to their ``read(geom)`` method. .. class:: WKBReader - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import WKBReader >>> wkb_r = WKBReader() @@ -946,7 +1008,9 @@ and/or WKT input given to their ``read(geom)`` method. .. class:: WKTReader - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import WKTReader >>> wkt_r = WKTReader() @@ -973,7 +1037,9 @@ include the SRID value (in other words, EWKB). .. method:: WKBWriter.write(geom) Returns the WKB of the given geometry as a Python ``buffer`` object. - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import Point, WKBWriter >>> pnt = Point(1, 1) @@ -983,7 +1049,9 @@ 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 >>> from django.contrib.gis.geos import Point, WKBWriter >>> pnt = Point(1, 1) @@ -1003,7 +1071,9 @@ include the SRID value (in other words, EWKB). 1 Little Endian (e.g., compatible with x86 systems) =============== ================================================= - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import Point, WKBWriter >>> wkb_w = WKBWriter() @@ -1026,7 +1096,9 @@ include the SRID value (in other words, EWKB). 3 Output 3D WKB. ============ =========================== - Example:: + Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import Point, WKBWriter >>> wkb_w = WKBWriter() @@ -1042,7 +1114,9 @@ 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 >>> from django.contrib.gis.geos import Point, WKBWriter >>> wkb_w = WKBWriter() @@ -1061,7 +1135,9 @@ include the SRID value (in other words, EWKB). .. method:: WKTWriter.write(geom) - Returns the WKT of the given geometry. Example:: + Returns the WKT of the given geometry. Example: + + .. code-block:: pycon >>> from django.contrib.gis.geos import Point, WKTWriter >>> pnt = Point(1, 1) @@ -1078,6 +1154,8 @@ include the SRID value (in other words, EWKB). This property is used to enable or disable trimming of unnecessary decimals. + .. code-block:: pycon + >>> from django.contrib.gis.geos import Point, WKTWriter >>> pnt = Point(1, 1) >>> wkt_w = WKTWriter() diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index ad8aff846e..059820df8e 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -85,7 +85,9 @@ is required. .. note:: On Linux platforms, it may be necessary to run the ``ldconfig`` command - after installing each library. For example:: + after installing each library. For example: + + .. code-block:: shell $ sudo make install $ sudo ldconfig @@ -106,19 +108,25 @@ internal geometry representation used by GeoDjango (it's behind the "lazy" 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:: +First, download GEOS from the GEOS website and untar the source archive: + +.. code-block:: shell $ wget https://download.osgeo.org/geos/geos-X.Y.Z.tar.bz2 $ tar xjf geos-X.Y.Z.tar.bz2 Then step into the GEOS directory, create a ``build`` folder, and step into -it:: +it: + +.. code-block:: shell $ cd geos-X.Y.Z $ mkdir build $ cd build -Then build and install the package:: +Then build and install the package: + +.. code-block:: shell $ cmake -DCMAKE_BUILD_TYPE=Release .. $ cmake --build . @@ -149,7 +157,9 @@ 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 GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so' @@ -168,18 +178,24 @@ PROJ `PROJ`_ is a library for converting geospatial data to different coordinate reference systems. -First, download the PROJ source code:: +First, download the PROJ source code: + +.. code-block:: shell $ wget https://download.osgeo.org/proj/proj-X.Y.Z.tar.gz ... and datum shifting files (download ``proj-datumgrid-X.Y.tar.gz`` for -PROJ < 7.x) [#]_:: +PROJ < 7.x) [#]_: + +.. code-block:: shell $ wget https://download.osgeo.org/proj/proj-data-X.Y.tar.gz Next, untar the source code archive, and extract the datum shifting files in the ``data`` subdirectory (use ``nad`` subdirectory for PROJ < 6.x). This must be -done *prior* to configuration:: +done *prior* to configuration: + +.. code-block:: shell $ tar xzf proj-X.Y.Z.tar.gz $ cd proj-X.Y.Z/data @@ -190,13 +206,17 @@ For PROJ 9.x and greater, releases only support builds using ``CMake`` (see `PROJ RFC-7`_). To build with ``CMake`` ensure your system meets the `build requirements`_. -Then create a ``build`` folder in the PROJ directory, and step into it:: +Then create a ``build`` folder in the PROJ directory, and step into it: + +.. code-block:: shell $ cd proj-X.Y.Z $ mkdir build $ cd build -Finally, configure, make and install PROJ:: +Finally, configure, make and install PROJ: + +.. code-block:: shell $ cmake .. $ cmake --build . @@ -215,20 +235,26 @@ 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. -First download the latest GDAL release version and untar the archive:: +First download the latest GDAL release version and untar the archive: + +.. code-block:: shell $ wget https://download.osgeo.org/gdal/X.Y.Z/gdal-X.Y.Z.tar.gz $ tar xzf gdal-X.Y.Z.tar.gz For GDAL 3.6.x and greater, releases only support builds using ``CMake``. To build with ``CMake`` create a ``build`` folder in the GDAL directory, and step -into it:: +into it: + +.. code-block:: shell $ cd gdal-X.Y.Z $ mkdir build $ cd build -Finally, configure, make and install GDAL:: +Finally, configure, make and install GDAL: + +.. code-block:: shell $ cmake .. $ cmake --build . @@ -258,7 +284,9 @@ 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 GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so' diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index 026c64ccd1..a70712cdcc 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -2,8 +2,6 @@ GeoDjango Installation ====================== -.. highlight:: console - Overview ======== In general, GeoDjango installation requires: @@ -141,7 +139,9 @@ A user may set this environment variable to customize the library paths they want to use. The typical library directory for software built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user -could place the following in their bash profile:: +could place the following in their bash profile: + +.. code-block:: shell export LD_LIBRARY_PATH=/usr/local/lib @@ -151,7 +151,9 @@ Setting system library path On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. As the root user, add the custom library path (like ``/usr/local/lib``) on a -new line in ``ld.so.conf``. This is *one* example of how to do so:: +new line in ``ld.so.conf``. This is *one* example of how to do so: + +.. code-block:: shell $ sudo echo /usr/local/lib >> /etc/ld.so.conf $ sudo ldconfig @@ -159,7 +161,9 @@ new line in ``ld.so.conf``. This is *one* example of how to do so:: For OpenSolaris users, the system library path may be modified using the ``crle`` utility. Run ``crle`` with no options to see the current configuration and use ``crle -l`` to set with the new library path. Be *very* careful when -modifying the system library path:: +modifying the system library path: + +.. code-block:: shell # crle -l $OLD_PATH:/usr/local/lib @@ -176,11 +180,15 @@ Linux system then Python's ctypes may not be able to find your library even if your library path is set correctly and geospatial libraries were built perfectly. The ``binutils`` package may be installed on Debian and Ubuntu systems using the -following command:: +following command: + +.. code-block:: shell $ sudo apt-get install binutils -Similarly, on Red Hat and CentOS systems:: +Similarly, on Red Hat and CentOS systems: + +.. code-block:: shell $ sudo yum install binutils @@ -221,7 +229,9 @@ __ https://www.python.org/ftp/python/ You will need to modify the ``PATH`` environment variable in your ``.profile`` file so that the new version of Python is used when - ``python`` is entered at the command-line:: + ``python`` is entered at the command-line: + + .. code-block:: shell export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH @@ -255,7 +265,9 @@ It provides recipes for the GeoDjango prerequisites on Macintosh computers running macOS. Because Homebrew still builds the software from source, `Xcode`_ is required. -Summary:: +Summary: + +.. code-block:: shell $ brew install postgresql $ brew install postgis @@ -287,7 +299,9 @@ MacPorts running macOS. Because MacPorts still builds the software from source, `Xcode`_ is required. -Summary:: +Summary: + +.. code-block:: shell $ sudo port install postgresql13-server $ sudo port install geos @@ -299,12 +313,16 @@ Summary:: .. note:: You will also have to modify the ``PATH`` in your ``.profile`` so - that the MacPorts programs are accessible from the command-line:: + that the MacPorts programs are accessible from the command-line: + + .. code-block:: shell export PATH=/opt/local/bin:/opt/local/lib/postgresql13/bin In addition, add the ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that - the libraries can be found by Python:: + the libraries can be found by Python: + + .. code-block:: shell export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql13 @@ -434,7 +452,9 @@ psycopg The ``psycopg`` Python module provides the interface between Python and the PostgreSQL database. ``psycopg`` can be installed via pip within your Python -virtual environment:: +virtual environment: + +.. code-block:: doscon ...\> py -m pip install psycopg diff --git a/docs/ref/contrib/gis/install/postgis.txt b/docs/ref/contrib/gis/install/postgis.txt index 6859dce7de..5603c5e1c8 100644 --- a/docs/ref/contrib/gis/install/postgis.txt +++ b/docs/ref/contrib/gis/install/postgis.txt @@ -35,7 +35,9 @@ Creating a spatial database --------------------------- PostGIS 2 includes an extension for PostgreSQL that's used to enable spatial -functionality:: +functionality: + +.. code-block:: shell $ createdb $ psql @@ -74,7 +76,9 @@ To administer the database, you can either use the pgAdmin III program (:menuselection:`Start --> PostgreSQL X --> pgAdmin III`) or the SQL Shell (:menuselection:`Start --> PostgreSQL X --> SQL Shell`). For example, to create a ``geodjango`` spatial database and user, the following may be executed from -the SQL Shell as the ``postgres`` user:: +the SQL Shell as the ``postgres`` user: + +.. code-block:: psql postgres# CREATE USER geodjango PASSWORD 'my_passwd'; postgres# CREATE DATABASE geodjango OWNER geodjango; diff --git a/docs/ref/contrib/gis/install/spatialite.txt b/docs/ref/contrib/gis/install/spatialite.txt index c6326d1e0d..b4d6d25371 100644 --- a/docs/ref/contrib/gis/install/spatialite.txt +++ b/docs/ref/contrib/gis/install/spatialite.txt @@ -33,7 +33,9 @@ SQLite ------ Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3 -command line interface and enter the following query:: +command line interface and enter the following query: + +.. code-block:: sqlite3 sqlite> CREATE VIRTUAL TABLE testrtree USING rtree(id,minX,maxX,minY,maxY); @@ -41,14 +43,18 @@ If you obtain an error, you will have to recompile SQLite from source. Otherwise skip this section. To install from sources, download the latest amalgamation source archive from -the `SQLite download page`__, and extract:: +the `SQLite download page`__, and extract: + +.. code-block:: shell $ wget https://www.sqlite.org/YYYY/sqlite-amalgamation-XXX0000.zip $ unzip sqlite-amalgamation-XXX0000.zip $ cd sqlite-amalgamation-XXX0000 Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable -needs to be customized so that SQLite knows to build the R*Tree module:: +needs to be customized so that SQLite knows to build the R*Tree module: + +.. code-block:: shell $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure $ make @@ -64,7 +70,9 @@ SpatiaLite library (``libspatialite``) -------------------------------------- Get the latest SpatiaLite library source bundle from the -`download page`__:: +`download page`__: + +.. code-block:: shell $ wget https://www.gaia-gis.it/gaia-sins/libspatialite-sources/libspatialite-X.Y.Z.tar.gz $ tar xaf libspatialite-X.Y.Z.tar.gz @@ -76,7 +84,9 @@ Get the latest SpatiaLite library source bundle from the .. note:: For macOS users building from source, the SpatiaLite library *and* tools - need to have their ``target`` configured:: + need to have their ``target`` configured: + + .. code-block:: shell $ ./configure --target=macosx @@ -93,7 +103,9 @@ Homebrew -------- `Homebrew`_ handles all the SpatiaLite related packages on your behalf, -including SQLite, SpatiaLite, PROJ, and GEOS. Install them like this:: +including SQLite, SpatiaLite, PROJ, and GEOS. Install them like this: + +.. code-block:: shell $ brew update $ brew install spatialite-tools diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index cbce2aff59..c0548159fe 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -32,7 +32,9 @@ Example ======= #. You need a GDAL-supported data source, like a shapefile (here we're using - a simple polygon shapefile, ``test_poly.shp``, with three features):: + a simple polygon shapefile, ``test_poly.shp``, with three features): + +.. code-block:: pycon >>> from django.contrib.gis.gdal import DataSource >>> ds = DataSource('test_poly.shp') @@ -62,7 +64,9 @@ Example return 'Name: %s' % self.name #. Use :class:`LayerMapping` to extract all the features and place them in the - database:: + database: + +.. code-block:: pycon >>> from django.contrib.gis.utils import LayerMapping >>> from geoapp.models import TestGeo @@ -206,13 +210,17 @@ should stop excessive memory use when running ``LayerMapping`` scripts. MySQL: ``max_allowed_packet`` error ----------------------------------- -If you encounter the following error when using ``LayerMapping`` and MySQL:: +If you encounter the following error when using ``LayerMapping`` and MySQL: + +.. code-block:: pytb 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 be something low like one megabyte -- the setting may be modified in MySQL's -configuration file (``my.cnf``) in the ``[mysqld]`` section:: +configuration file (``my.cnf``) in the ``[mysqld]`` section: + +.. code-block:: ini max_allowed_packet = 10M diff --git a/docs/ref/contrib/gis/measure.txt b/docs/ref/contrib/gis/measure.txt index f7b13c1b81..8d87320d3b 100644 --- a/docs/ref/contrib/gis/measure.txt +++ b/docs/ref/contrib/gis/measure.txt @@ -16,7 +16,9 @@ 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``):: +instantiated in units of kilometers (``km``) and miles (``mi``): + +.. code-block:: pycon >>> from django.contrib.gis.measure import D, Distance >>> d1 = Distance(km=5) @@ -27,7 +29,9 @@ instantiated in units of kilometers (``km``) and miles (``mi``):: 5.0 mi For conversions, access the preferred unit attribute to get a converted -distance quantity:: +distance quantity: + +.. code-block:: pycon >>> print(d1.mi) # Converting 5 kilometers to miles 3.10685596119 @@ -35,7 +39,9 @@ distance quantity:: 8.04672 Moreover, arithmetic operations may be performed between the distance -objects:: +objects: + +.. code-block:: pycon >>> print(d1 + d2) # Adding 5 miles to 5 kilometers 13.04672 km @@ -43,14 +49,18 @@ objects:: 1.89314403881 mi Two :class:`Distance` objects multiplied together will yield an :class:`Area` -object, which uses squared units of measure:: +object, which uses squared units of measure: + +.. code-block:: pycon >>> a = d1 * d2 # Returns an Area object. >>> print(a) 40.2336 sq_km To determine what the attribute abbreviation of a unit is, the ``unit_attname`` -class method may be used:: +class method may be used: + +.. code-block:: pycon >>> print(Distance.unit_attname('US Survey Foot')) survey_ft @@ -117,14 +127,18 @@ Measurement API To initialize a distance object, pass in a keyword corresponding to the desired :ref:`unit attribute name ` set with desired value. For example, the following creates a distance object representing 5 - miles:: + miles: + + .. code-block:: pycon >>> dist = Distance(mi=5) .. method:: __getattr__(unit_att) Returns the distance value in units corresponding to the given unit - attribute. For example:: + attribute. For example: + + .. code-block:: pycon >>> print(dist.km) 8.04672 @@ -132,7 +146,9 @@ Measurement API .. classmethod:: unit_attname(unit_name) Returns the distance unit attribute name for the given full unit name. For - example:: + example: + + .. code-block:: pycon >>> Distance.unit_attname('Mile') 'mi' @@ -149,14 +165,18 @@ Measurement API To initialize an area object, pass in a keyword corresponding to the desired :ref:`unit attribute name ` set with desired value. For example, the following creates an area object representing 5 - square miles:: + square miles: + + .. code-block:: pycon >>> a = Area(sq_mi=5) .. method:: __getattr__(unit_att) Returns the area value in units corresponding to the given unit attribute. - For example:: + For example: + + .. code-block:: pycon >>> print(a.sq_km) 12.949940551680001 @@ -164,7 +184,9 @@ Measurement API .. classmethod:: unit_attname(unit_name) Returns the area unit attribute name for the given full unit name. For - example:: + example: + + .. code-block:: pycon >>> Area.unit_attname('Kilometer') 'sq_km' diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index d77971bb5a..79d4779d18 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -46,7 +46,9 @@ Create database user ~~~~~~~~~~~~~~~~~~~~ To make a database user with the ability to create databases, use the -following command:: +following command: + +.. code-block:: shell $ createuser --createdb -R -S @@ -54,19 +56,25 @@ The ``-R -S`` flags indicate that we do not want the user to have the ability to create additional users (roles) or to be a superuser, respectively. Alternatively, you may alter an existing user's role from the SQL shell -(assuming this is done from an existing superuser account):: +(assuming this is done from an existing superuser account): + +.. code-block:: psql postgres# ALTER ROLE CREATEDB NOSUPERUSER NOCREATEROLE; Create database superuser ~~~~~~~~~~~~~~~~~~~~~~~~~ -This may be done at the time the user is created, for example:: +This may be done at the time the user is created, for example: + +.. code-block:: shell $ createuser --superuser Or you may alter the user's role from the SQL shell (assuming this -is done from an existing superuser account):: +is done from an existing superuser account): + +.. code-block:: psql postgres# ALTER ROLE SUPERUSER; @@ -114,10 +122,14 @@ in :mod:`django.contrib.gis`:: Assuming the settings above were in a ``postgis.py`` file in the same directory as ``runtests.py``, then all Django and GeoDjango tests would -be performed when executing the command:: +be performed when executing the command: + +.. code-block:: shell $ ./runtests.py --settings=postgis -To run only the GeoDjango test suite, specify ``gis_tests``:: +To run only the GeoDjango test suite, specify ``gis_tests``: + +.. code-block:: shell $ ./runtests.py --settings=postgis gis_tests diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 2a4e082869..4e8f5f4bb0 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -321,14 +321,18 @@ First, invoke the Django shell: $ python manage.py shell If you downloaded the :ref:`worldborders` data earlier in the tutorial, then -you can determine its path using Python's :class:`pathlib.Path`:: +you can determine its path using Python's :class:`pathlib.Path`: + +.. code-block:: pycon >>> from pathlib import Path >>> import world >>> world_shp = Path(world.__file__).resolve().parent / 'data' / 'TM_WORLD_BORDERS-0.3.shp' Now, open the world borders shapefile using GeoDjango's -:class:`~django.contrib.gis.gdal.DataSource` interface:: +:class:`~django.contrib.gis.gdal.DataSource` interface: + +.. code-block:: pycon >>> from django.contrib.gis.gdal import DataSource >>> ds = DataSource(world_shp) @@ -336,7 +340,9 @@ Now, open the world borders shapefile using GeoDjango's / ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile) Data source objects can have different layers of geospatial features; however, -shapefiles are only allowed to have one layer:: +shapefiles are only allowed to have one layer: + +.. code-block:: pycon >>> print(len(ds)) 1 @@ -344,7 +350,9 @@ shapefiles are only allowed to have one layer:: >>> print(lyr) TM_WORLD_BORDERS-0.3 -You can see the layer's geometry type and how many features it contains:: +You can see the layer's geometry type and how many features it contains: + +.. code-block:: pycon >>> print(lyr.geom_type) Polygon @@ -363,7 +371,9 @@ You can see the layer's geometry type and how many features it contains:: 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 -:class:`~django.contrib.gis.gdal.SpatialReference` object:: +:class:`~django.contrib.gis.gdal.SpatialReference` object: + +.. code-block:: pycon >>> srs = lyr.srs >>> print(srs) @@ -401,7 +411,9 @@ string) associated with each of the fields: You can iterate over each feature in the layer and extract information from both the feature's geometry (accessed via the ``geom`` attribute) as well as the feature's attribute fields (whose **values** are accessed via ``get()`` -method):: +method): + +.. code-block:: pycon >>> for feat in lyr: ... print(feat.get('NAME'), feat.geom.num_points) @@ -411,18 +423,24 @@ method):: South Georgia South Sandwich Islands 338 Taiwan 363 -:class:`~django.contrib.gis.gdal.Layer` objects may be sliced:: +:class:`~django.contrib.gis.gdal.Layer` objects may be sliced: + +.. code-block:: pycon >>> lyr[0:2] [, ] -And individual features may be retrieved by their feature ID:: +And individual features may be retrieved by their feature ID: + +.. code-block:: pycon >>> feat = lyr[234] >>> print(feat.get('NAME')) San Marino -Boundary geometries may be exported as WKT and GeoJSON:: +Boundary geometries may be exported as WKT and GeoJSON: + +.. code-block:: pycon >>> geom = feat.geom >>> print(geom.wkt) @@ -484,7 +502,9 @@ Afterward, invoke the Django shell from the ``geodjango`` project directory: $ python manage.py shell Next, import the ``load`` module, call the ``run`` routine, and watch -``LayerMapping`` do the work:: +``LayerMapping`` do the work: + +.. code-block:: pycon >>> from world import load >>> load.run() @@ -576,7 +596,9 @@ a particular point. First, fire up the management shell: $ python manage.py shell -Now, define a point of interest [#]_:: +Now, define a point of interest [#]_: + +.. code-block:: pycon >>> pnt_wkt = 'POINT(-95.3385 29.7245)' @@ -584,7 +606,9 @@ The ``pnt_wkt`` string represents the point at -95.3385 degrees longitude, 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:: +a ``contains`` lookup using the ``pnt_wkt`` as the parameter: + +.. code-block:: pycon >>> from world.models import WorldBorder >>> WorldBorder.objects.filter(mpoly__contains=pnt_wkt) @@ -596,7 +620,9 @@ United States (exactly what you would expect). Similarly, you may also use a :doc:`GEOS geometry object `. Here, you can combine the ``intersects`` spatial lookup with the ``get`` method to retrieve only the ``WorldBorder`` instance for San Marino instead -of a queryset:: +of a queryset: + +.. code-block:: pycon >>> from django.contrib.gis.geos import Point >>> pnt = Point(12.4604, 43.9420) @@ -614,19 +640,25 @@ When doing spatial queries, GeoDjango automatically transforms 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:: +**meters**, not degrees: + +.. code-block:: pycon >>> from django.contrib.gis.geos import GEOSGeometry, Point >>> pnt = Point(954158.1, 4215137.1, srid=32140) Note that ``pnt`` may also be constructed with EWKT, an "extended" form of -WKT that includes the SRID:: +WKT that includes the SRID: + +.. code-block:: pycon >>> pnt = GEOSGeometry('SRID=32140;POINT(954158.1 4215137.1)') GeoDjango's ORM will automatically wrap geometry values in transformation SQL, allowing the developer to work at a higher level -of abstraction:: +of abstraction: + +.. code-block:: pycon >>> qs = WorldBorder.objects.filter(mpoly__intersects=pnt) >>> print(qs.query) # Generating the SQL @@ -646,7 +678,9 @@ __ https://spatialreference.org/ref/epsg/32140/ .. admonition:: Raw queries When using :doc:`raw queries `, you must wrap your geometry - fields so that the field value can be recognized by GEOS:: + fields so that the field value can be recognized by GEOS: + + .. code-block:: pycon from django.db import connection # or if you're querying a non-default database: @@ -663,7 +697,9 @@ 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 -formats:: +formats: + +.. code-block:: pycon >>> sm = WorldBorder.objects.get(name='San Marino') >>> sm.mpoly @@ -676,7 +712,9 @@ formats:: '{ "type": "MultiPolygon", "coordinates": [ [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ... This includes access to all of the advanced geometric operations provided by -the GEOS library:: +the GEOS library: + +.. code-block:: pycon >>> pnt = Point(12.4604, 43.9420) >>> sm.mpoly.contains(pnt) diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 6c96c383a2..403ad5649f 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -180,7 +180,9 @@ Displaying messages ------------------- .. function:: get_messages(request) -**In your template**, use something like:: +**In your template**, use something like: + +.. code-block:: html+django {% if messages %}
    @@ -199,7 +201,9 @@ Even if you know there is only one message, you should still iterate over the cleared for the next request. The context processor also provides a ``DEFAULT_MESSAGE_LEVELS`` variable which -is a mapping of the message level names to their numeric value:: +is a mapping of the message level names to their numeric value: + +.. code-block:: html+django {% if messages %}
      diff --git a/docs/ref/contrib/postgres/aggregates.txt b/docs/ref/contrib/postgres/aggregates.txt index 55ec952fa2..5c241dc4cf 100644 --- a/docs/ref/contrib/postgres/aggregates.txt +++ b/docs/ref/contrib/postgres/aggregates.txt @@ -12,7 +12,9 @@ module. They are described in more detail in the `PostgreSQL docs .. note:: All functions come without default aliases, so you must explicitly provide - one. For example:: + one. For example: + + .. code-block:: pycon >>> SomeModel.objects.aggregate(arr=ArrayAgg('somefield')) {'arr': [0, 1, 2]} @@ -100,6 +102,8 @@ General-purpose aggregation functions published = models.BooleanField() rank = models.IntegerField() + .. code-block:: pycon + >>> from django.db.models import Q >>> from django.contrib.postgres.aggregates import BoolAnd >>> Comment.objects.aggregate(booland=BoolAnd('published')) @@ -122,6 +126,8 @@ General-purpose aggregation functions published = models.BooleanField() rank = models.IntegerField() + .. code-block:: pycon + >>> from django.db.models import Q >>> from django.contrib.postgres.aggregates import BoolOr >>> Comment.objects.aggregate(boolor=BoolOr('published')) @@ -163,6 +169,8 @@ General-purpose aggregation functions end = models.DateTimeField() requirements = models.JSONField(blank=True, null=True) + .. code-block:: pycon + >>> from django.contrib.postgres.aggregates import JSONBAgg >>> Room.objects.annotate( ... requirements=JSONBAgg( @@ -217,6 +225,8 @@ General-purpose aggregation functions headline = models.CharField(max_length=100) publications = models.ManyToManyField(Publication) + .. code-block:: pycon + >>> article = Article.objects.create(headline="NASA uses Python") >>> article.publications.create(title="The Python Journal") @@ -354,7 +364,9 @@ field or an expression returning a numeric data. Both are required. Usage examples ============== -We will use this example table:: +We will use this example table: + +.. code-block:: text | FIELD1 | FIELD2 | FIELD3 | |--------|--------|--------| @@ -362,8 +374,9 @@ We will use this example table:: | bar | 2 | (null) | | test | 3 | 13 | +Here's some examples of some of the general-purpose aggregation functions: -Here's some examples of some of the general-purpose aggregation functions:: +.. code-block:: pycon >>> TestModel.objects.aggregate(result=StringAgg('field1', delimiter=';')) {'result': 'foo;bar;test'} @@ -374,7 +387,9 @@ Here's some examples of some of the general-purpose aggregation functions:: The next example shows the usage of statistical aggregate functions. The underlying math will be not described (you can read about this, for example, at -`wikipedia `_):: +`wikipedia `_): + +.. code-block:: pycon >>> TestModel.objects.aggregate(count=RegrCount(y='field3', x='field2')) {'count': 2} diff --git a/docs/ref/contrib/postgres/expressions.txt b/docs/ref/contrib/postgres/expressions.txt index 05d5096fee..9ce2b9f7c6 100644 --- a/docs/ref/contrib/postgres/expressions.txt +++ b/docs/ref/contrib/postgres/expressions.txt @@ -22,7 +22,9 @@ in the way that it does not act as an aggregate function and does not require an SQL ``GROUP BY`` clause to build the list of values. For example, if you want to annotate all related books to an author as JSON -objects:: +objects: + +.. code-block:: pycon >>> from django.db.models import OuterRef >>> from django.db.models.functions import JSONObject diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index 34ad06a09a..87f79aa80c 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -127,7 +127,9 @@ We will use the following example model:: The :lookup:`contains` lookup is overridden on :class:`ArrayField`. The returned objects will be those where the values passed are a subset of the -data. It uses the SQL operator ``@>``. For example:: +data. It uses the SQL operator ``@>``. For example: + +.. code-block:: pycon >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) @@ -149,7 +151,9 @@ data. It uses the SQL operator ``@>``. For example:: This is the inverse of the :lookup:`contains ` lookup - the objects returned will be those where the data is a subset of the values -passed. It uses the SQL operator ``<@``. For example:: +passed. It uses the SQL operator ``<@``. For example: + +.. code-block:: pycon >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) @@ -167,7 +171,9 @@ passed. It uses the SQL operator ``<@``. For example:: ~~~~~~~~~~~ Returns objects where the data shares any results with the values passed. Uses -the SQL operator ``&&``. For example:: +the SQL operator ``&&``. For example: + +.. code-block:: pycon >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts', 'tutorial']) @@ -193,7 +199,9 @@ the SQL operator ``&&``. For example:: ~~~~~~~ Returns the length of the array. The lookups available afterward are those -available for :class:`~django.db.models.IntegerField`. For example:: +available for :class:`~django.db.models.IntegerField`. For example: + +.. code-block:: pycon >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) @@ -209,7 +217,9 @@ Index transforms Index transforms index into the array. Any non-negative integer can be used. There are no errors if it exceeds the :attr:`size ` of the array. The lookups available after the transform are those from the -:attr:`base_field `. For example:: +:attr:`base_field `. For example: + +.. code-block:: pycon >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) @@ -236,7 +246,9 @@ Slice transforms Slice transforms take a slice of the array. Any two non-negative integers can be used, separated by a single underscore. The lookups available after the -transform do not change. For example:: +transform do not change. For example: + +.. code-block:: pycon >>> Post.objects.create(name='First post', tags=['thoughts', 'django']) >>> Post.objects.create(name='Second post', tags=['thoughts']) @@ -374,7 +386,9 @@ We will use the following example model:: Key lookups ~~~~~~~~~~~ -To query based on a given key, you can use that key as the lookup name:: +To query based on a given key, you can use that key as the lookup name: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie'}) @@ -382,12 +396,16 @@ To query based on a given key, you can use that key as the lookup name:: >>> Dog.objects.filter(data__breed='collie') ]> -You can chain other lookups after key lookups:: +You can chain other lookups after key lookups: + +.. code-block:: pycon >>> Dog.objects.filter(data__breed__contains='l') , ]> -or use ``F()`` expressions to annotate a key value. For example:: +or use ``F()`` expressions to annotate a key value. For example: + +.. code-block:: pycon >>> from django.db.models import F >>> rufus = Dog.objects.annotate(breed=F("data__breed"))[0] @@ -419,7 +437,9 @@ need to use the :lookup:`hstorefield.contains` lookup instead. The :lookup:`contains` lookup is overridden on :class:`~django.contrib.postgres.fields.HStoreField`. The returned objects are those where the given ``dict`` of key-value pairs are all contained in the -field. It uses the SQL operator ``@>``. For example:: +field. It uses the SQL operator ``@>``. For example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador', 'owner': 'Bob'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) @@ -439,7 +459,9 @@ field. It uses the SQL operator ``@>``. For example:: This is the inverse of the :lookup:`contains ` lookup - the objects returned will be those where the key-value pairs on the object are a subset of those in the value passed. It uses the SQL operator ``<@``. For -example:: +example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador', 'owner': 'Bob'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) @@ -457,7 +479,9 @@ example:: ~~~~~~~~~~~ Returns objects where the given key is in the data. Uses the SQL operator -``?``. For example:: +``?``. For example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) @@ -471,7 +495,9 @@ Returns objects where the given key is in the data. Uses the SQL operator ~~~~~~~~~~~~~~~~ Returns objects where any of the given keys are in the data. Uses the SQL -operator ``?|``. For example:: +operator ``?|``. For example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'owner': 'Bob'}) @@ -486,7 +512,9 @@ operator ``?|``. For example:: ~~~~~~~~~~~~ Returns objects where all of the given keys are in the data. Uses the SQL operator -``?&``. For example:: +``?&``. For example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) @@ -503,7 +531,9 @@ Returns objects where the array of keys is the given value. Note that the order is not guaranteed to be reliable, so this transform is mainly useful for using in conjunction with lookups on :class:`~django.contrib.postgres.fields.ArrayField`. Uses the SQL function -``akeys()``. For example:: +``akeys()``. For example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'toy': 'bone'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) @@ -520,7 +550,9 @@ Returns objects where the array of values is the given value. Note that the order is not guaranteed to be reliable, so this transform is mainly useful for using in conjunction with lookups on :class:`~django.contrib.postgres.fields.ArrayField`. Uses the SQL function -``avals()``. For example:: +``avals()``. For example: + +.. code-block:: pycon >>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'}) >>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'}) @@ -646,7 +678,9 @@ model:: def __str__(self): return self.name -We will also use the following example objects:: +We will also use the following example objects: + +.. code-block:: pycon >>> import datetime >>> from django.utils import timezone @@ -689,7 +723,9 @@ The ``contained_by`` lookup is also available on the non-range field types: :class:`~django.db.models.BigIntegerField`, :class:`~django.db.models.DecimalField`, :class:`~django.db.models.FloatField`, :class:`~django.db.models.DateField`, and -:class:`~django.db.models.DateTimeField`. For example:: +:class:`~django.db.models.DateTimeField`. For example: + +.. code-block:: pycon >>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange >>> Event.objects.filter( diff --git a/docs/ref/contrib/postgres/forms.txt b/docs/ref/contrib/postgres/forms.txt index 8f9dd449d1..95d705277b 100644 --- a/docs/ref/contrib/postgres/forms.txt +++ b/docs/ref/contrib/postgres/forms.txt @@ -23,7 +23,9 @@ Fields It specifies the underlying form field for the array. This is not used to render any HTML, but it is used to process the submitted data and - validate it. For example:: + validate it. For example: + + .. code-block:: pycon >>> from django import forms >>> from django.contrib.postgres.forms import SimpleArrayField @@ -45,7 +47,9 @@ Fields This is an optional argument which defaults to a comma: ``,``. This value is used to split the submitted data. It allows you to chain - ``SimpleArrayField`` for multidimensional data:: + ``SimpleArrayField`` for multidimensional data: + + .. code-block:: pycon >>> from django import forms >>> from django.contrib.postgres.forms import SimpleArrayField diff --git a/docs/ref/contrib/postgres/functions.txt b/docs/ref/contrib/postgres/functions.txt index 447af266a2..f5d9cdd873 100644 --- a/docs/ref/contrib/postgres/functions.txt +++ b/docs/ref/contrib/postgres/functions.txt @@ -20,7 +20,9 @@ operation to install it. .. _pgcrypto extension: https://www.postgresql.org/docs/current/pgcrypto.html -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.functions import RandomUUID >>> Article.objects.update(uuid=RandomUUID()) @@ -41,7 +43,9 @@ sets up a transaction and thus sets the time that ``TransactionNow()`` will return; nested calls create savepoints which do not affect the transaction time. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.functions import TransactionNow >>> Article.objects.filter(published__lte=TransactionNow()) diff --git a/docs/ref/contrib/postgres/lookups.txt b/docs/ref/contrib/postgres/lookups.txt index 3070227530..b4b072ffa8 100644 --- a/docs/ref/contrib/postgres/lookups.txt +++ b/docs/ref/contrib/postgres/lookups.txt @@ -23,7 +23,9 @@ extension using the operation. The ``trigram_similar`` lookup can be used on -:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`:: +:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`: + +.. code-block:: pycon >>> City.objects.filter(name__trigram_similar="Middlesborough") [''] @@ -47,7 +49,9 @@ extension using the operation. The ``trigram_word_similar`` lookup can be used on -:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`:: +:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`: + +.. code-block:: pycon >>> Sentence.objects.filter(name__trigram_word_similar='Middlesborough') [''] @@ -91,7 +95,9 @@ operation is available if you want to perform this activation using migrations). .. _unaccent extension on PostgreSQL: https://www.postgresql.org/docs/current/unaccent.html The ``unaccent`` lookup can be used on -:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`:: +:class:`~django.db.models.CharField` and :class:`~django.db.models.TextField`: + +.. code-block:: pycon >>> City.objects.filter(name__unaccent="México") [''] diff --git a/docs/ref/contrib/postgres/search.txt b/docs/ref/contrib/postgres/search.txt index dd78154b1e..cd737d3ed3 100644 --- a/docs/ref/contrib/postgres/search.txt +++ b/docs/ref/contrib/postgres/search.txt @@ -22,7 +22,9 @@ The ``search`` lookup .. fieldlookup:: search A common way to use full text search is to search a single term against a -single column in the database. For example:: +single column in the database. For example: + +.. code-block:: pycon >>> Entry.objects.filter(body_text__search='Cheese') [, ] @@ -42,7 +44,9 @@ To use the ``search`` lookup, ``'django.contrib.postgres'`` must be in your Searching against a single field is great but rather limiting. The ``Entry`` instances we're searching belong to a ``Blog``, which has a ``tagline`` field. -To query against both fields, use a ``SearchVector``:: +To query against both fields, use a ``SearchVector``: + +.. code-block:: pycon >>> from django.contrib.postgres.search import SearchVector >>> Entry.objects.annotate( @@ -56,7 +60,9 @@ arguments will be concatenated together using a space so that the search document includes them all. ``SearchVector`` objects can be combined together, allowing you to reuse them. -For example:: +For example: + +.. code-block:: pycon >>> Entry.objects.annotate( ... search=SearchVector('body_text') + SearchVector('blog__tagline'), @@ -96,7 +102,9 @@ Examples: >>> SearchQuery("'tomato' & ('red' | 'green')", search_type='raw') # boolean operators >>> SearchQuery("'tomato' ('red' OR 'green')", search_type='websearch') # websearch operators -``SearchQuery`` terms can be combined logically to provide more flexibility:: +``SearchQuery`` terms can be combined logically to provide more flexibility: + +.. code-block:: pycon >>> from django.contrib.postgres.search import SearchQuery >>> SearchQuery('meat') & SearchQuery('cheese') # AND @@ -117,7 +125,9 @@ sort of relevancy. PostgreSQL provides a ranking function which takes into account how often the query terms appear in the document, how close together the terms are in the document, and how important the part of the document is where they occur. The better the match, the higher the value of the rank. To -order by relevancy:: +order by relevancy: + +.. code-block:: pycon >>> from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector >>> vector = SearchVector('body_text') @@ -134,7 +144,9 @@ account. Provide an integer to the ``normalization`` parameter to control rank normalization. This integer is a bit mask, so you can combine multiple -behaviors:: +behaviors: + +.. code-block:: pycon >>> from django.db.models import Value >>> Entry.objects.annotate( @@ -182,7 +194,9 @@ between fragments. PostgreSQL's default is ``" ... "``. The PostgreSQL documentation has more details on `highlighting search results`_. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.search import SearchHeadline, SearchQuery >>> query = SearchQuery('red tomato') @@ -209,7 +223,9 @@ Changing the search configuration You can specify the ``config`` attribute to a :class:`SearchVector` and :class:`SearchQuery` to use a different search configuration. This allows using -different language parsers and dictionaries as defined by the database:: +different language parsers and dictionaries as defined by the database: + +.. code-block:: pycon >>> from django.contrib.postgres.search import SearchQuery, SearchVector >>> Entry.objects.annotate( @@ -217,7 +233,9 @@ different language parsers and dictionaries as defined by the database:: ... ).filter(search=SearchQuery('œuf', config='french')) [] -The value of ``config`` could also be stored in another column:: +The value of ``config`` could also be stored in another column: + +.. code-block:: pycon >>> from django.db.models import F >>> Entry.objects.annotate( @@ -231,7 +249,9 @@ Weighting queries ================= Every field may not have the same relevance in a query, so you can set weights -of various vectors before you combine them:: +of various vectors before you combine them: + +.. code-block:: pycon >>> from django.contrib.postgres.search import SearchQuery, SearchRank, SearchVector >>> vector = SearchVector('body_text', weight='A') + SearchVector('blog__tagline', weight='B') @@ -241,7 +261,9 @@ of various vectors before you combine them:: The weight should be one of the following letters: D, C, B, A. By default, these weights refer to the numbers ``0.1``, ``0.2``, ``0.4``, and ``1.0``, respectively. If you wish to weight them differently, pass a list of four -floats to :class:`SearchRank` as ``weights`` in the same order above:: +floats to :class:`SearchRank` as ``weights`` in the same order above: + +.. code-block:: pycon >>> rank = SearchRank(vector, query, weights=[0.2, 0.4, 0.6, 0.8]) >>> Entry.objects.annotate(rank=rank).filter(rank__gte=0.3).order_by('-rank') @@ -277,7 +299,9 @@ The PostgreSQL documentation has details on If this approach becomes too slow, you can add a ``SearchVectorField`` to your model. You'll need to keep it populated with triggers, for example, as described in the `PostgreSQL documentation`_. You can then query the field as -if it were an annotated ``SearchVector``:: +if it were an annotated ``SearchVector``: + +.. code-block:: pycon >>> Entry.objects.update(search_vector=SearchVector('body_text')) >>> Entry.objects.filter(search_vector='cheese') @@ -307,7 +331,9 @@ operation. Accepts a field name or expression, and a string or expression. Returns the trigram similarity between the two arguments. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.search import TrigramSimilarity >>> Author.objects.create(name='Katy Stevens') @@ -326,7 +352,9 @@ Usage example:: Accepts a string or expression, and a field name or expression. Returns the trigram word similarity between the two arguments. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.search import TrigramWordSimilarity >>> Author.objects.create(name='Katy Stevens') @@ -357,7 +385,9 @@ extent boundaries to match word boundaries. Accepts a field name or expression, and a string or expression. Returns the trigram distance between the two arguments. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.search import TrigramDistance >>> Author.objects.create(name='Katy Stevens') @@ -376,7 +406,9 @@ Usage example:: Accepts a string or expression, and a field name or expression. Returns the trigram word distance between the two arguments. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.contrib.postgres.search import TrigramWordDistance >>> Author.objects.create(name='Katy Stevens') diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index 45b7fe1a0e..02db2a2ec7 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -74,7 +74,9 @@ Via the Python API Redirects are represented by a standard :doc:`Django model `, which lives in :source:`django/contrib/redirects/models.py`. You can access redirect objects via the :doc:`Django database API `. - For example:: + For example: + + .. code-block:: pycon >>> from django.conf import settings >>> from django.contrib.redirects.models import Redirect diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 7dc3dced51..7dfe835252 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -634,7 +634,9 @@ Pinging Google via ``manage.py`` .. django-admin:: ping_google [sitemap_url] Once the sitemaps application is added to your project, you may also -ping Google using the ``ping_google`` management command:: +ping Google using the ``ping_google`` management command: + +.. code-block:: shell python manage.py ping_google [/sitemap.xml] diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index ea9e211964..e74ce97a97 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -241,7 +241,9 @@ Getting the current domain for full URLs Django's ``get_absolute_url()`` convention is nice for getting your objects' URL without the domain name, but in some cases you might want to display the full URL -- with ``http://`` and the domain and everything -- for an object. -To do this, you can use the sites framework. An example:: +To do this, you can use the sites framework. An example: + +.. code-block:: pycon >>> from django.contrib.sites.models import Site >>> obj = MyModel.objects.get(id=3) diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 429565a23c..7eab5dfd05 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -1004,7 +1004,9 @@ They share this interface: :meth:`.SyndicationFeed.writeString` Returns the feed as a string in the given encoding. -For example, to create an Atom 1.0 feed and print it to standard output:: +For example, to create an Atom 1.0 feed and print it to standard output: + +.. code-block:: pycon >>> from django.utils import feedgenerator >>> from datetime import datetime diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 6755085336..0885af35e1 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -352,7 +352,9 @@ Django uses PostgreSQL's identity columns to store auto-incrementing primary keys. An identity column is populated with values from a `sequence`_ that keeps track of the next available value. Manually assigning a value to an auto-incrementing field doesn't update the field's sequence, which might later -cause a conflict. For example:: +cause a conflict. For example: + +.. code-block:: pycon >>> from django.contrib.auth.models import User >>> User.objects.create(username='alice', pk=1) @@ -500,7 +502,9 @@ This needs to be done just once for your MySQL server, not per database. Creating your database ---------------------- -You can `create your database`_ using the command-line tools and this SQL:: +You can `create your database`_ using the command-line tools and this SQL: + +.. code-block:: sql CREATE DATABASE CHARACTER SET utf8; @@ -581,6 +585,8 @@ Here's a sample configuration which uses a MySQL option file:: } +.. code-block:: ini + # my.cnf [client] database = NAME @@ -650,7 +656,9 @@ If you're using a hosting service and can't change your server's default storage engine, you have a couple of options. * After the tables are created, execute an ``ALTER TABLE`` statement to - convert a table to a new storage engine (such as InnoDB):: + convert a table to a new storage engine (such as InnoDB): + + .. code-block:: sql ALTER TABLE ENGINE=INNODB; @@ -730,7 +738,9 @@ includes a fractional indication (e.g. ``DATETIME(6)``). Django will not upgrade existing columns to include fractional seconds if the database server supports it. If you want to enable them on an existing database, it's up to you to either manually update the column on the target database, by -executing a command like:: +executing a command like: + +.. code-block:: sql ALTER TABLE `your_table` MODIFY `your_datetime_column` DATETIME(6) @@ -1126,7 +1136,9 @@ database backends to modify its behavior, features, or configuration. Consider, for example, that you need to change a single database feature. First, you have to create a new directory with a ``base`` module in it. For -example:: +example: + +.. code-block:: text mysite/ ... diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 5e52fc282e..48eb6d09c0 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -65,7 +65,9 @@ Determining the version Run ``django-admin version`` to display the current Django version. -The output follows the schema described in :pep:`440`:: +The output follows the schema described in :pep:`440`: + +.. code-block:: text 1.4.dev17026 1.4a1 @@ -91,7 +93,9 @@ Uses the :doc:`system check framework ` to inspect the entire Django project for common problems. By default, all apps will be checked. You can check a subset of apps by -providing a list of app labels as arguments:: +providing a list of app labels as arguments: + +.. console:: django-admin check auth admin myapp @@ -100,13 +104,17 @@ providing a list of app labels as arguments:: The system check framework performs many different types of checks that are :ref:`categorized with tags `. You can use these tags to restrict the checks performed to just those in a particular category. -For example, to perform only models and compatibility checks, run:: +For example, to perform only models and compatibility checks, run: + +.. console:: django-admin check --tag models --tag compatibility .. django-admin-option:: --database DATABASE -Specifies the database to run checks requiring database access:: +Specifies the database to run checks requiring database access: + +.. console:: django-admin check --database default --database other @@ -124,7 +132,9 @@ You can use this option in your local development environment, but since your local development settings module may not have many of your production settings, you will probably want to point the ``check`` command at a different settings module, either by setting the :envvar:`DJANGO_SETTINGS_MODULE` environment -variable, or by passing the ``--settings`` option:: +variable, or by passing the ``--settings`` option: + +.. console:: django-admin check --deploy --settings=production_settings @@ -158,7 +168,9 @@ are excluded. Includes `fuzzy translations`_ into compiled files. -Example usage:: +Example usage: + +.. console:: django-admin compilemessages --locale=pt_BR django-admin compilemessages --locale=pt_BR --locale=fr -f @@ -176,7 +188,9 @@ Example usage:: Ignores directories matching the given :mod:`glob`-style pattern. Use multiple times to ignore more. -Example usage:: +Example usage: + +.. console:: django-admin compilemessages --ignore=cache --ignore=outdated/*/locale @@ -329,7 +343,9 @@ only that model will be excluded, rather than the entire application. You can also mix application names and model names. If you want to exclude multiple applications, pass ``--exclude`` more than -once:: +once: + +.. console:: django-admin dumpdata --exclude=auth --exclude=contenttypes @@ -370,7 +386,9 @@ Fixtures compression The output file can be compressed with one of the ``bz2``, ``gz``, ``lzma``, or ``xz`` formats by ending the filename with the corresponding extension. -For example, to output the data as a compressed JSON file:: +For example, to output the data as a compressed JSON file: + +.. console:: django-admin dumpdata -o mydata.json.gz @@ -520,7 +538,9 @@ Loading fixtures from ``stdin`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can use a dash as the fixture name to load input from ``sys.stdin``. For -example:: +example: + +.. console:: django-admin loaddata --format=json - @@ -529,7 +549,9 @@ is required to specify the :ref:`serialization format ` of the input (e.g., ``json`` or ``xml``). Loading from ``stdin`` is useful with standard input and output redirections. -For example:: +For example: + +.. console:: django-admin dumpdata --format=json --database=test app_label.ModelName | django-admin loaddata --format=json --database=prod - @@ -564,12 +586,16 @@ Updates the message files for all available languages. Specifies a list of file extensions to examine (default: ``html``, ``txt``, ``py`` or ``js`` if :option:`--domain` is ``js``). -Example usage:: +Example usage: + +.. console:: django-admin makemessages --locale=de --extension xhtml Separate multiple extensions with commas or use ``-e`` or ``--extension`` -multiple times:: +multiple times: + +.. console:: django-admin makemessages --locale=de --extension=html,txt --extension xml @@ -582,7 +608,9 @@ Specifies the locale(s) to process. Specifies the locale(s) to exclude from processing. If not provided, no locales are excluded. -Example usage:: +Example usage: + +.. console:: django-admin makemessages --locale=pt_BR django-admin makemessages --locale=pt_BR --locale=fr @@ -604,7 +632,9 @@ Specifies the domain of the messages files. Supported options are: Follows symlinks to directories when looking for new translation strings. -Example usage:: +Example usage: + +.. console:: django-admin makemessages --locale=de --symlinks @@ -615,7 +645,9 @@ multiple times to ignore more. These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``, ``'*.pyc'``. -Example usage:: +Example usage: + +.. console:: django-admin makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html @@ -925,39 +957,57 @@ Uses IPv6 for the development server. This changes the default IP address from Examples of using different ports and addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Port 8000 on IP address ``127.0.0.1``:: +Port 8000 on IP address ``127.0.0.1``: + +.. console:: django-admin runserver -Port 8000 on IP address ``1.2.3.4``:: +Port 8000 on IP address ``1.2.3.4``: + +.. console:: django-admin runserver 1.2.3.4:8000 -Port 7000 on IP address ``127.0.0.1``:: +Port 7000 on IP address ``127.0.0.1``: + +.. console:: django-admin runserver 7000 -Port 7000 on IP address ``1.2.3.4``:: +Port 7000 on IP address ``1.2.3.4``: + +.. console:: django-admin runserver 1.2.3.4:7000 -Port 8000 on IPv6 address ``::1``:: +Port 8000 on IPv6 address ``::1``: + +.. console:: django-admin runserver -6 -Port 7000 on IPv6 address ``::1``:: +Port 7000 on IPv6 address ``::1``: + +.. console:: django-admin runserver -6 7000 -Port 7000 on IPv6 address ``2001:0db8:1234:5678::9``:: +Port 7000 on IPv6 address ``2001:0db8:1234:5678::9``: + +.. console:: django-admin runserver [2001:0db8:1234:5678::9]:7000 -Port 8000 on IPv4 address of host ``localhost``:: +Port 8000 on IPv4 address of host ``localhost``: + +.. console:: django-admin runserver localhost:8000 -Port 8000 on IPv6 address of host ``localhost``:: +Port 8000 on IPv6 address of host ``localhost``: + +.. console:: django-admin runserver -6 localhost:8000 @@ -975,7 +1025,9 @@ you want to configure Django to serve static media, read .. django-admin:: sendtestemail [email [email ...]] Sends a test email (to confirm email sending through Django is working) to the -recipient(s) specified. For example:: +recipient(s) specified. For example: + +.. console:: django-admin sendtestemail foo@example.com bar@example.com @@ -1004,16 +1056,22 @@ Starts the Python interactive interpreter. Specifies the shell to use. By default, Django will use IPython_ or bpython_ if either is installed. If both are installed, specify which one you want like so: -IPython:: +IPython: + +.. console:: django-admin shell -i ipython -bpython:: +bpython: + +.. console:: django-admin shell -i bpython If you have a "rich" shell installed but want to force use of the "plain" -Python interpreter, use ``python`` as the interface name, like so:: +Python interpreter, use ``python`` as the interface name, like so: + +.. console:: django-admin shell -i python @@ -1028,7 +1086,9 @@ variable or the ``~/.pythonrc.py`` script is read. .. django-admin-option:: --command COMMAND, -c COMMAND -Lets you pass a command as a string to execute it as Django, like so:: +Lets you pass a command as a string to execute it as Django, like so: + +.. console:: django-admin shell --command="import django; print(django.__version__)" @@ -1177,7 +1237,9 @@ If the optional destination is provided, Django will use that existing directory rather than creating a new one. You can use '.' to denote the current working directory. -For example:: +For example: + +.. console:: django-admin startapp myapp /Users/jezdez/Code/myapp @@ -1191,7 +1253,9 @@ an uncompressed archive (``.tar``) or a compressed archive (``.tar.gz``, ``.tlz``, ``.zip``) containing the app template files. For example, this would look for an app template in the given directory when -creating the ``myapp`` app:: +creating the ``myapp`` app: + +.. console:: django-admin startapp --template=/Users/jezdez/Code/my_app_template myapp @@ -1200,7 +1264,9 @@ archives with the app template files, downloading and extracting them on the fly. For example, taking advantage of GitHub's feature to expose repositories as -zip files, you can use a URL like:: +zip files, you can use a URL like: + +.. console:: django-admin startapp --template=https://github.com/githubuser/django-app-template/archive/main.zip myapp @@ -1283,7 +1349,9 @@ If the optional destination is provided, Django will use that existing directory as the project directory, and create ``manage.py`` and the project package within it. Use '.' to denote the current working directory. -For example:: +For example: + +.. console:: django-admin startproject myproject /Users/jezdez/Code/myproject_repo @@ -1492,7 +1560,9 @@ Outputs timings, including database setup and total run time. Runs a Django development server (as in :djadmin:`runserver`) using data from the given fixture(s). -For example, this command:: +For example, this command: + +.. console:: django-admin testserver mydata.json @@ -1530,7 +1600,9 @@ exactly the same function as the argument to the :djadmin:`runserver` command. Examples: -To run the test server on port 7000 with ``fixture1`` and ``fixture2``:: +To run the test server on port 7000 with ``fixture1`` and ``fixture2``: + +.. console:: django-admin testserver --addrport 7000 fixture1 fixture2 django-admin testserver fixture1 fixture2 --addrport 7000 @@ -1539,7 +1611,9 @@ To run the test server on port 7000 with ``fixture1`` and ``fixture2``:: that it doesn't matter whether the options come before or after the fixture arguments.) -To run on 1.2.3.4:7000 with a ``test`` fixture:: +To run on 1.2.3.4:7000 with a ``test`` fixture: + +.. console:: django-admin testserver --addrport 1.2.3.4:7000 test @@ -1576,7 +1650,9 @@ the password whose username matches the current user. Specifies the database to query for the user. Defaults to ``default``. -Example usage:: +Example usage: + +.. console:: django-admin changepassword ringo @@ -1730,7 +1806,9 @@ variable. This option is unnecessary in ``manage.py``, because it takes care of setting the Python path for you. -Example usage:: +Example usage: + +.. console:: django-admin migrate --pythonpath='/home/djangoprojects/myproject' @@ -1746,7 +1824,9 @@ variable. This option is unnecessary in ``manage.py``, because it uses ``settings.py`` from the current project by default. -Example usage:: +Example usage: + +.. console:: django-admin migrate --settings=mysite.settings @@ -1758,7 +1838,9 @@ is raised. By default, ``django-admin`` will show an error message when a This option is ignored by :djadmin:`runserver`. -Example usage:: +Example usage: + +.. console:: django-admin migrate --traceback @@ -1774,7 +1856,9 @@ should print to the console. This option is ignored by :djadmin:`runserver`. -Example usage:: +Example usage: + +.. console:: django-admin migrate --verbosity 2 @@ -1784,7 +1868,9 @@ 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. -Example usage:: +Example usage: + +.. console:: django-admin runserver --no-color @@ -1801,7 +1887,9 @@ available if the :attr:`~django.core.management.BaseCommand.requires_system_checks` command attribute is not an empty list or tuple. -Example usage:: +Example usage: + +.. console:: django-admin migrate --skip-checks @@ -1834,7 +1922,9 @@ two third-party libraries are needed: * Install colorama_, a Python package that translates ANSI color codes into Windows API calls. Django commands will detect its presence and will make use of its services to color output just like on Unix-based platforms. - ``colorama`` can be installed via pip:: + ``colorama`` can be installed via pip: + + .. code-block:: doscon ...\> py -m pip install colorama @@ -1869,7 +1959,9 @@ ships with three color palettes: You select a palette by setting a :envvar:`DJANGO_COLORS` environment variable to specify the palette you want to use. For example, to specify the ``light`` palette under a Unix or OS/X BASH shell, you -would run the following at a command prompt:: +would run the following at a command prompt: + +.. code-block:: shell export DJANGO_COLORS="light" @@ -1925,7 +2017,9 @@ A color specification follows one of the following patterns: where ``role`` is the name of a valid color role, ``fg`` is the foreground color, ``bg`` is the background color and each ``option`` is one of the color modifying options. Multiple color specifications -are then separated by a semicolon. For example:: +are then separated by a semicolon. For example: + +.. code-block:: shell export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta" @@ -1935,7 +2029,9 @@ left uncolored. Colors can also be specified by extending a base palette. If you put a palette name in a color specification, all the colors implied by that -palette will be loaded. So:: +palette will be loaded. So: + +.. code-block:: shell export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta" @@ -1969,11 +2065,15 @@ The Python files created by :djadmin:`startproject`, :djadmin:`startapp`, present on your ``PATH``. If you have ``black`` globally installed, but do not wish it used for the -current project, you can set the ``PATH`` explicitly:: +current project, you can set the ``PATH`` explicitly: + +.. code-block:: shell PATH=path/to/venv/bin django-admin makemigrations -For commands using ``stdout`` you can pipe the output to ``black`` if needed:: +For commands using ``stdout`` you can pipe the output to ``black`` if needed: + +.. code-block:: shell django-admin inspectdb | black - diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index 63f5a9337a..253e3d2903 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -137,10 +137,14 @@ below) will also have a couple of extra methods: to point to it. If ``save`` is ``True``, the model's ``save()`` method will be called once the file is saved. That is, these two lines:: + .. code-block:: pycon + >>> car.photo.save('myphoto.jpg', content, save=False) >>> car.save() - are equivalent to:: + are equivalent to: + + .. code-block:: pycon >>> car.photo.save('myphoto.jpg', content, save=True) diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 6d296c537e..99a140ad0e 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -25,12 +25,16 @@ A :class:`Form` instance is either **bound** to a set of data, or **unbound**. .. class:: Form -To create an unbound :class:`Form` instance, instantiate the class:: +To create an unbound :class:`Form` instance, instantiate the class: + +.. code-block:: pycon >>> f = ContactForm() To bind data to a form, pass the data as a dictionary as the first parameter to -your :class:`Form` class constructor:: +your :class:`Form` class constructor: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -47,7 +51,9 @@ in a moment. .. attribute:: Form.is_bound If you need to distinguish between bound and unbound form instances at runtime, -check the value of the form's :attr:`~Form.is_bound` attribute:: +check the value of the form's :attr:`~Form.is_bound` attribute: + +.. code-block:: pycon >>> f = ContactForm() >>> f.is_bound @@ -56,7 +62,9 @@ check the value of the form's :attr:`~Form.is_bound` attribute:: >>> f.is_bound True -Note that passing an empty dictionary creates a *bound* form with empty data:: +Note that passing an empty dictionary creates a *bound* form with empty data: + +.. code-block:: pycon >>> f = ContactForm({}) >>> f.is_bound @@ -81,7 +89,9 @@ validation for fields that are interdependent. See The primary task of a :class:`Form` object is to validate data. With a bound :class:`Form` instance, call the :meth:`~Form.is_valid` method to run validation -and return a boolean designating whether the data was valid:: +and return a boolean designating whether the data was valid: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -93,7 +103,9 @@ and return a boolean designating whether the data was valid:: Let's try with some invalid data. In this case, ``subject`` is blank (an error, because all fields are required by default) and ``sender`` is not a valid -email address:: +email address: + +.. code-block:: pycon >>> data = {'subject': '', ... 'message': 'Hi there', @@ -106,7 +118,9 @@ email address:: .. attribute:: Form.errors Access the :attr:`~Form.errors` attribute to get a dictionary of error -messages:: +messages: + +.. code-block:: pycon >>> f.errors {'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']} @@ -214,7 +228,9 @@ Behavior of unbound forms ------------------------- It's meaningless to validate a form with no data, but, for the record, here's -what happens with unbound forms:: +what happens with unbound forms: + +.. code-block:: pycon >>> f = ContactForm() >>> f.is_valid() @@ -236,7 +252,9 @@ username of the current session. To accomplish this, use the :attr:`~Form.initial` argument to a :class:`Form`. This argument, if given, should be a dictionary mapping field names to initial values. Only include the fields for which you're specifying an initial value; -it's not necessary to include every field in your form. For example:: +it's not necessary to include every field in your form. For example: + +.. code-block:: pycon >>> f = ContactForm(initial={'subject': 'Hi there!'}) @@ -247,7 +265,9 @@ If a :class:`~django.forms.Field` defines :attr:`~Field.initial` *and* you include :attr:`~Form.initial` when instantiating the ``Form``, then the latter ``initial`` will have precedence. In this example, ``initial`` is provided both at the field level and at the form instance level, and the latter gets -precedence:: +precedence: + +.. code-block:: pycon >>> from django import forms >>> class CommentForm(forms.Form): @@ -271,7 +291,9 @@ It is recommended to use :attr:`BoundField.initial` over simpler interface. Also, unlike :meth:`~Form.get_initial_for_field()`, :attr:`BoundField.initial` caches its values. This is useful especially when dealing with callables whose return values can change (e.g. ``datetime.now`` or -``uuid.uuid4``):: +``uuid.uuid4``): + +.. code-block:: pycon >>> import uuid >>> class UUIDCommentForm(CommentForm): @@ -332,7 +354,9 @@ Accessing the fields from the form .. attribute:: Form.fields You can access the fields of :class:`Form` instance from its ``fields`` -attribute:: +attribute: + +.. code-block:: pycon >>> for row in f.fields.values(): print(row) ... @@ -343,7 +367,9 @@ attribute:: You can alter the field and :class:`.BoundField` of :class:`Form` instance to -change the way it is presented in the form:: +change the way it is presented in the form: + +.. code-block:: pycon >>> f.as_div().split("")[0] '
      ' @@ -353,7 +379,9 @@ change the way it is presented in the form:: Beware not to alter the ``base_fields`` attribute because this modification will influence all subsequent ``ContactForm`` instances within the same Python -process:: +process: + +.. code-block:: pycon >>> f.base_fields["subject"].label_suffix = "?" >>> another_f = CommentForm(auto_id=False) @@ -377,7 +405,9 @@ formats, ``DateField`` will always normalize it to a ``datetime.date`` object as long as it's valid. Once you've created a :class:`~Form` instance with a set of data and validated -it, you can access the clean data via its ``cleaned_data`` attribute:: +it, you can access the clean data via its ``cleaned_data`` attribute: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -394,7 +424,9 @@ always cleans the input into a string. We'll cover the encoding implications later in this document. If your data does *not* validate, the ``cleaned_data`` dictionary contains -only the valid fields:: +only the valid fields: + +.. code-block:: pycon >>> data = {'subject': '', ... 'message': 'Hi there', @@ -409,7 +441,9 @@ only the valid fields:: ``cleaned_data`` will always *only* contain a key for fields defined in the ``Form``, even if you pass extra data when you define the ``Form``. In this example, we pass a bunch of extra fields to the ``ContactForm`` constructor, -but ``cleaned_data`` contains only the form's fields:: +but ``cleaned_data`` contains only the form's fields: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -427,7 +461,9 @@ but ``cleaned_data`` contains only the form's fields:: When the ``Form`` is valid, ``cleaned_data`` will include a key and value for *all* its fields, even if the data didn't include a value for some optional fields. In this example, the data dictionary doesn't include a value for the -``nick_name`` field, but ``cleaned_data`` includes it, with an empty value:: +``nick_name`` field, but ``cleaned_data`` includes it, with an empty value: + +.. code-block:: pycon >>> from django import forms >>> class OptionalPersonForm(forms.Form): @@ -458,7 +494,9 @@ Outputting forms as HTML ======================== The second task of a ``Form`` object is to render itself as HTML. To do so, -``print`` it:: +``print`` it: + +.. code-block:: pycon >>> f = ContactForm() >>> print(f) @@ -471,7 +509,9 @@ If the form is bound to data, the HTML output will include that data appropriately. For example, if a field is represented by an ````, the data will be in the ``value`` attribute. If a field is represented by an ````, then that HTML will -include ``checked`` if appropriate:: +include ``checked`` if appropriate: + +.. code-block:: pycon >>> data = {'subject': 'hello', ... 'message': 'Hi there', @@ -658,7 +698,9 @@ The template used by ``as_p()``. Default: ``'django/forms/p.html'``. .. method:: Form.as_p() ``as_p()`` renders the form as a series of ``

      `` tags, with each ``

      `` -containing one field:: +containing one field: + +.. code-block:: pycon >>> f = ContactForm() >>> f.as_p() @@ -680,7 +722,9 @@ The template used by ``as_ul()``. Default: ``'django/forms/ul.html'``. ``as_ul()`` renders the form as a series of ``

    • `` tags, with each ``
    • `` containing one field. It does *not* include the ``
        `` or ``
      ``, so that -you can specify any HTML attributes on the ``
        `` for flexibility:: +you can specify any HTML attributes on the ``
          `` for flexibility: + +.. code-block:: pycon >>> f = ContactForm() >>> f.as_ul() @@ -700,7 +744,9 @@ The template used by ``as_table()``. Default: ``'django/forms/table.html'``. .. method:: Form.as_table() -``as_table()`` renders the form as an HTML ````:: +``as_table()`` renders the form as an HTML ``
          ``: + +.. code-block:: pycon >>> f = ContactForm() >>> f.as_table() @@ -737,7 +783,9 @@ attributes:: # ... and the rest of your fields here Once you've done that, rows will be given ``"error"`` and/or ``"required"`` -classes, as needed. The HTML will look something like:: +classes, as needed. The HTML will look something like: + +.. code-block:: pycon >>> f = ContactForm(data) >>> print(f.as_table()) @@ -779,7 +827,9 @@ Use the ``auto_id`` argument to the ``Form`` constructor to control the ``id`` and label behavior. This argument must be ``True``, ``False`` or a string. If ``auto_id`` is ``False``, then the form output will not include `` @@ -96,7 +100,9 @@ loop. You can use variables, too. For example, if you have two template variables, ``rowvalue1`` and ``rowvalue2``, you can alternate between their values like -this:: +this: + +.. code-block:: html+django {% for o in some_list %} @@ -105,7 +111,9 @@ this:: {% endfor %} Variables included in the cycle will be escaped. You can disable auto-escaping -with:: +with: + +.. code-block:: html+django {% for o in some_list %} @@ -113,7 +121,9 @@ with:: {% endfor %} -You can mix variables and strings:: +You can mix variables and strings: + +.. code-block:: html+django {% for o in some_list %} @@ -123,7 +133,9 @@ You can mix variables and strings:: In some cases you might want to refer to the current value of a cycle without advancing to the next value. To do this, -give the ``{% cycle %}`` tag a name, using "as", like this:: +give the ``{% cycle %}`` tag a name, using "as", like this: + +.. code-block:: html+django {% cycle 'row1' 'row2' as rowcolors %} @@ -131,7 +143,9 @@ From then on, you can insert the current value of the cycle wherever you'd like in your template by referencing the cycle name as a context variable. If you want to move the cycle to the next value independently of the original ``cycle`` tag, you can use another ``cycle`` tag and specify the name of the -variable. So, the following template:: +variable. So, the following template: + +.. code-block:: html+django @@ -142,7 +156,9 @@ variable. So, the following template:: -would output:: +would output: + +.. code-block:: html+django @@ -163,7 +179,9 @@ usage of ``{% cycle %}`` that initiates the cycle will itself produce the first value in the cycle. This could be a problem if you want to use the value in a nested loop or an included template. If you only want to declare the cycle but not produce the first value, you can add a -``silent`` keyword as the last keyword in the tag. For example:: +``silent`` keyword as the last keyword in the tag. For example: + +.. code-block:: html+django {% for obj in some_list %} {% cycle 'row1' 'row2' as rowcolors silent %} @@ -180,7 +198,9 @@ omitted, ``row1`` and ``row2`` would be emitted as normal text, outside the When the silent keyword is used on a cycle definition, the silence automatically applies to all subsequent uses of that specific cycle tag. The following template would output *nothing*, even though the second -call to ``{% cycle %}`` doesn't specify ``silent``:: +call to ``{% cycle %}`` doesn't specify ``silent``: + +.. code-block:: html+django {% cycle 'row1' 'row2' as rowcolors silent %} {% cycle rowcolors %} @@ -223,7 +243,9 @@ See :ref:`template-inheritance` for more information. Normally the template name is relative to the template loader's root directory. A string argument may also be a relative path starting with ``./`` or ``../``. -For example, assume the following directory structure:: +For example, assume the following directory structure: + +.. code-block:: text dir1/ template.html @@ -232,7 +254,9 @@ For example, assume the following directory structure:: base3.html base1.html -In ``template.html``, the following paths would be valid:: +In ``template.html``, the following paths would be valid: + +.. code-block:: html+django {% extends "./base2.html" %} {% extends "../base1.html" %} @@ -250,7 +274,9 @@ in variable syntax. Note that the block includes *all* the text between the ``filter`` and ``endfilter`` tags. -Sample usage:: +Sample usage: + +.. code-block:: html+django {% filter force_escape|lower %} This text will be HTML-escaped, and will appear in all lowercase. @@ -271,11 +297,15 @@ Outputs the first argument variable that is not "false" (i.e. exists, is not empty, is not a false boolean value, and is not a zero numeric value). Outputs nothing if all the passed variables are "false". -Sample usage:: +Sample usage: + +.. code-block:: html+django {% firstof var1 var2 var3 %} -This is equivalent to:: +This is equivalent to: + +.. code-block:: html+django {% if var1 %} {{ var1 }} @@ -286,17 +316,23 @@ This is equivalent to:: {% endif %} You can also use a literal string as a fallback value in case all -passed variables are False:: +passed variables are False: + +.. code-block:: html+django {% firstof var1 var2 var3 "fallback value" %} -This tag auto-escapes variable values. You can disable auto-escaping with:: +This tag auto-escapes variable values. You can disable auto-escaping with: + +.. code-block:: html+django {% autoescape off %} {% firstof var1 var2 var3 "fallback value" %} {% endautoescape %} -Or if only some variables should be escaped, you can use:: +Or if only some variables should be escaped, you can use: + +.. code-block:: html+django {% firstof var1 var2|safe var3 "fallback value"|safe %} @@ -310,7 +346,9 @@ output inside a variable. Loops over each item in an array, making the item available in a context variable. For example, to display a list of athletes provided in -``athlete_list``:: +``athlete_list``: + +.. code-block:: html+django
            {% for athlete in athlete_list %} @@ -324,7 +362,9 @@ You can loop over a list in reverse by using If you need to loop over a list of lists, you can unpack the values in each sublist into individual variables. For example, if your context contains a list of (x,y) coordinates called ``points``, you could use the -following to output the list of points:: +following to output the list of points: + +.. code-block:: html+django {% for x, y in points %} There is a point at {{ x }},{{ y }} @@ -332,7 +372,9 @@ following to output the list of points:: This can also be useful if you need to access the items in a dictionary. For example, if your context contained a dictionary ``data``, the following -would display the keys and values of the dictionary:: +would display the keys and values of the dictionary: + +.. code-block:: html+django {% for key, value in data.items %} {{ key }}: {{ value }} @@ -367,7 +409,9 @@ Variable Description --------------------- The ``for`` tag can take an optional ``{% empty %}`` clause whose text is -displayed if the given array is empty or could not be found:: +displayed if the given array is empty or could not be found: + +.. code-block:: html+django
              {% for athlete in athlete_list %} @@ -378,7 +422,9 @@ displayed if the given array is empty or could not be found::
            The above is equivalent to -- but shorter, cleaner, and possibly faster -than -- the following:: +than -- the following: + +.. code-block:: html+django
              {% if athlete_list %} @@ -397,7 +443,9 @@ than -- the following:: The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. exists, is not empty, and is not a false boolean value) the contents of the -block are output:: +block are output: + +.. code-block:: html+django {% if athlete_list %} Number of athletes: {{ athlete_list|length }} @@ -418,7 +466,9 @@ Boolean operators ~~~~~~~~~~~~~~~~~ :ttag:`if` tags may use ``and``, ``or`` or ``not`` to test a number of -variables or to negate a given variable:: +variables or to negate a given variable: + +.. code-block:: html+django {% if athlete_list and coach_list %} Both athletes and coaches are available. @@ -441,7 +491,9 @@ variables or to negate a given variable:: {% endif %} Use of both ``and`` and ``or`` clauses within the same tag is allowed, with -``and`` having higher precedence than ``or`` e.g.:: +``and`` having higher precedence than ``or`` e.g.: + +.. code-block:: html+django {% if athlete_list and coach_list or cheerleader_list %} @@ -461,7 +513,9 @@ follows: ``==`` operator ^^^^^^^^^^^^^^^ -Equality. Example:: +Equality. Example: + +.. code-block:: html+django {% if somevar == "x" %} This appears if variable somevar equals the string "x" @@ -470,7 +524,9 @@ Equality. Example:: ``!=`` operator ^^^^^^^^^^^^^^^ -Inequality. Example:: +Inequality. Example: + +.. code-block:: html+django {% if somevar != "x" %} This appears if variable somevar does not equal the string "x", @@ -480,7 +536,9 @@ Inequality. Example:: ``<`` operator ^^^^^^^^^^^^^^ -Less than. Example:: +Less than. Example: + +.. code-block:: html+django {% if somevar < 100 %} This appears if variable somevar is less than 100. @@ -489,7 +547,9 @@ Less than. Example:: ``>`` operator ^^^^^^^^^^^^^^ -Greater than. Example:: +Greater than. Example: + +.. code-block:: html+django {% if somevar > 0 %} This appears if variable somevar is greater than 0. @@ -498,7 +558,9 @@ Greater than. Example:: ``<=`` operator ^^^^^^^^^^^^^^^ -Less than or equal to. Example:: +Less than or equal to. Example: + +.. code-block:: html+django {% if somevar <= 100 %} This appears if variable somevar is less than 100 or equal to 100. @@ -507,7 +569,9 @@ Less than or equal to. Example:: ``>=`` operator ^^^^^^^^^^^^^^^ -Greater than or equal to. Example:: +Greater than or equal to. Example: + +.. code-block:: html+django {% if somevar >= 1 %} This appears if variable somevar is greater than 1 or equal to 1. @@ -518,7 +582,9 @@ Greater than or equal to. Example:: Contained within. This operator is supported by many Python containers to test whether the given value is in the container. The following are some examples -of how ``x in y`` will be interpreted:: +of how ``x in y`` will be interpreted: + +.. code-block:: html+django {% if "bc" in "abcdef" %} This appears since "bc" is a substring of "abcdef" @@ -542,7 +608,9 @@ Not contained within. This is the negation of the ``in`` operator. ``is`` operator ^^^^^^^^^^^^^^^ -Object identity. Tests if two values are the same object. Example:: +Object identity. Tests if two values are the same object. Example: + +.. code-block:: html+django {% if somevar is True %} This appears if and only if somevar is True. @@ -556,7 +624,9 @@ Object identity. Tests if two values are the same object. Example:: ^^^^^^^^^^^^^^^^^^^ Negated object identity. Tests if two values are not the same object. This is -the negation of the ``is`` operator. Example:: +the negation of the ``is`` operator. Example: + +.. code-block:: html+django {% if somevar is not True %} This appears if somevar is not True, or if somevar is not found in the @@ -570,7 +640,9 @@ the negation of the ``is`` operator. Example:: Filters ~~~~~~~ -You can also use filters in the :ttag:`if` expression. For example:: +You can also use filters in the :ttag:`if` expression. For example: + +.. code-block:: html+django {% if messages|length >= 100 %} You have lots of messages today! @@ -591,7 +663,9 @@ operators, from lowest to highest, is as follows: * ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=`` (This follows Python exactly). So, for example, the following complex -:ttag:`if` tag:: +:ttag:`if` tag: + +.. code-block:: html+django {% if a == b or c == d and e %} @@ -606,11 +680,15 @@ Sometimes that is better for clarity anyway, for the sake of those who do not know the precedence rules. The comparison operators cannot be 'chained' like in Python or in mathematical -notation. For example, instead of using:: +notation. For example, instead of using: + +.. code-block:: html+django {% if a > b > c %} (WRONG) -you should use:: +you should use: + +.. code-block:: html+django {% if a > b and b > c %} @@ -626,7 +704,9 @@ uses. 1. Checks its own rendered contents against its previous state and only displays the content if it has changed. For example, this displays a list of - days, only displaying the month if it changes:: + days, only displaying the month if it changes: + + .. code-block:: html+django

              Archive for {{ year }}

              @@ -637,7 +717,9 @@ uses. 2. If given one or more variables, check whether any variable has changed. For example, the following shows the date every time it changes, while - showing the hour if either the hour or the date has changed:: + showing the hour if either the hour or the date has changed: + + .. code-block:: html+django {% for date in days %} {% ifchanged date.date %} {{ date.date }} {% endifchanged %} @@ -647,7 +729,9 @@ uses. {% endfor %} The ``ifchanged`` tag can also take an optional ``{% else %}`` clause that -will be displayed if the value has not changed:: +will be displayed if the value has not changed: + +.. code-block:: html+django {% for match in matches %}
              {{ coach.name }} @@ -1009,7 +1131,9 @@ Notice how the first block ends with ``class="odd"`` and the new one starts with ``class="odd"``. Without the ``{% resetcycle %}`` tag, the second block would start with ``class="even"``. -You can also reset named cycle tags:: +You can also reset named cycle tags: + +.. code-block:: html+django {% for item in list %}

              @@ -1032,7 +1156,9 @@ every fifth row. Only the five-row cycle is reset when a category changes. Removes whitespace between HTML tags. This includes tab characters and newlines. -Example usage:: +Example usage: + +.. code-block:: html+django {% spaceless %}

              @@ -1040,12 +1166,16 @@ Example usage::

              {% endspaceless %} -This example would return this HTML:: +This example would return this HTML: + +.. code-block:: html+django

              Foo

              Only space between *tags* is removed -- not space between tags and text. In -this example, the space around ``Hello`` won't be stripped:: +this example, the space around ``Hello`` won't be stripped: + +.. code-block:: html+django {% spaceless %} @@ -1079,7 +1209,9 @@ Argument Outputs ``closecomment`` ``#}`` ================== ======= -Sample usage:: +Sample usage: + +.. code-block:: html+django The {% templatetag openblock %} characters open a block. @@ -1096,7 +1228,9 @@ given view and optional parameters. Any special characters in the resulting path will be encoded using :func:`~django.utils.encoding.iri_to_uri`. This is a way to output links without violating the DRY principle by having to -hard-code URLs in your templates:: +hard-code URLs in your templates: + +.. code-block:: html+django {% url 'some-url-name' v1 v2 %} @@ -1104,7 +1238,9 @@ The first argument is a :ref:`URL pattern name `. It can be a quoted literal or any other context variable. Additional arguments are optional and should be space-separated values that will be used as arguments in the URL. The example above shows passing positional arguments. Alternatively -you may use keyword syntax:: +you may use keyword syntax: + +.. code-block:: html+django {% url 'some-url-name' arg1=v1 arg2=v2 %} @@ -1137,7 +1273,9 @@ Note that if the URL you're reversing doesn't exist, you'll get an site to display an error page. If you'd like to retrieve a URL without displaying it, you can use a slightly -different call:: +different call: + +.. code-block:: html+django {% url 'some-url-name' arg arg2 as the_url %} @@ -1147,14 +1285,18 @@ The scope of the variable created by the ``as var`` syntax is the ``{% block %}`` in which the ``{% url %}`` tag appears. This ``{% url ... as var %}`` syntax will *not* cause an error if the view is -missing. In practice you'll use this to link to views that are optional:: +missing. In practice you'll use this to link to views that are optional: + +.. code-block:: html+django {% url 'some-url-name' as the_url %} {% if the_url %} Link to optional stuff {% endif %} -If you'd like to retrieve a namespaced URL, specify the fully qualified name:: +If you'd like to retrieve a namespaced URL, specify the fully qualified name: + +.. code-block:: html+django {% url 'myapp:view-name' %} @@ -1175,14 +1317,18 @@ by the context as to the current application. Stops the template engine from rendering the contents of this block tag. A common use is to allow a JavaScript template layer that collides with -Django's syntax. For example:: +Django's syntax. For example: + +.. code-block:: html+django {% verbatim %} {{if dying}}Still alive.{{/if}} {% endverbatim %} You can also designate a specific closing tag, allowing the use of -``{% endverbatim %}`` as part of the unrendered contents:: +``{% endverbatim %}`` as part of the unrendered contents: + +.. code-block:: html+django {% verbatim myblock %} Avoid template rendering via the {% verbatim %}{% endverbatim %} block. @@ -1196,7 +1342,9 @@ You can also designate a specific closing tag, allowing the use of For creating bar charts and such, this tag calculates the ratio of a given value to a maximum value, and then applies that ratio to a constant. -For example:: +For example: + +.. code-block:: html+django Bar @@ -1206,7 +1354,9 @@ image in the above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 which is rounded up to 88). In some cases you might want to capture the result of ``widthratio`` in a -variable. It can be useful, for instance, in a :ttag:`blocktranslate` like this:: +variable. It can be useful, for instance, in a :ttag:`blocktranslate` like this: + +.. code-block:: html+django {% widthratio this_value max_value max_width as width %} {% blocktranslate %}The width is: {{ width }}{% endblocktranslate %} @@ -1219,7 +1369,9 @@ variable. It can be useful, for instance, in a :ttag:`blocktranslate` like this: Caches a complex variable under a simpler name. This is useful when accessing an "expensive" method (e.g., one that hits the database) multiple times. -For example:: +For example: + +.. code-block:: html+django {% with total=business.employees.count %} {{ total }} employee{{ total|pluralize }} @@ -1228,7 +1380,9 @@ For example:: The populated variable (in the example above, ``total``) is only available between the ``{% with %}`` and ``{% endwith %}`` tags. -You can assign more than one context variable:: +You can assign more than one context variable: + +.. code-block:: html+django {% with alpha=1 beta=2 %} ... @@ -1249,7 +1403,9 @@ Built-in filter reference Adds the argument to the value. -For example:: +For example: + +.. code-block:: html+django {{ value|add:"2" }} @@ -1260,7 +1416,9 @@ it'll attempt to add the values together anyway. This will work on some data types (strings, list, etc.) and fail on others. If it fails, the result will be an empty string. -For example, if we have:: +For example, if we have: + +.. code-block:: html+django {{ first|add:second }} @@ -1279,7 +1437,9 @@ output will be ``[1, 2, 3, 4, 5, 6]``. Adds slashes before quotes. Useful for escaping strings in CSV, for example. -For example:: +For example: + +.. code-block:: html+django {{ value|addslashes }} @@ -1294,7 +1454,9 @@ If ``value`` is ``"I'm using Django"``, the output will be Capitalizes the first character of the value. If the first character is not a letter, this filter has no effect. -For example:: +For example: + +.. code-block:: html+django {{ value|capfirst }} @@ -1307,7 +1469,9 @@ If ``value`` is ``"django"``, the output will be ``"Django"``. Centers the value in a field of a given width. -For example:: +For example: + +.. code-block:: html+django "{{ value|center:"15" }}" @@ -1320,7 +1484,9 @@ If ``value`` is ``"Django"``, the output will be ``" Django "``. Removes all values of arg from the given string. -For example:: +For example: + +.. code-block:: html+django {{ value|cut:" " }} @@ -1431,7 +1597,9 @@ Format character Description Example output (January 1 1970 00:00:00 UTC). ================ ======================================== ===================== -For example:: +For example: + +.. code-block:: html+django {{ value|date:"D d M Y" }} @@ -1446,7 +1614,9 @@ specifiers shown in the table above. Note that predefined formats may vary depending on the current locale. Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, -for example, ``"es"``, then for:: +for example, ``"es"``, then for: + +.. code-block:: html+django {{ value|date:"SHORT_DATE_FORMAT" }} @@ -1454,7 +1624,9 @@ the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"`` format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``). When used without a format string, the ``DATE_FORMAT`` format specifier is -used. Assuming the same settings as the previous example:: +used. Assuming the same settings as the previous example: + +.. code-block:: html+django {{ value|date }} @@ -1464,7 +1636,9 @@ backslash-escaped, because otherwise each is a format string that displays the day and the timezone name, respectively. You can combine ``date`` with the :tfilter:`time` filter to render a full -representation of a ``datetime`` value. E.g.:: +representation of a ``datetime`` value. E.g.: + +.. code-block:: html+django {{ value|date:"D d M Y" }} {{ value|time:"H:i" }} @@ -1476,7 +1650,9 @@ representation of a ``datetime`` value. E.g.:: If value evaluates to ``False``, uses the given default. Otherwise, uses the value. -For example:: +For example: + +.. code-block:: html+django {{ value|default:"nothing" }} @@ -1493,7 +1669,9 @@ value. Note that if an empty string is given, the default value will *not* be used. Use the :tfilter:`default` filter if you want to fallback for empty strings. -For example:: +For example: + +.. code-block:: html+django {{ value|default_if_none:"nothing" }} @@ -1507,7 +1685,9 @@ If ``value`` is ``None``, the output will be ``nothing``. Takes a list of dictionaries and returns that list sorted by the key given in the argument. -For example:: +For example: + +.. code-block:: html+django {{ value|dictsort:"name" }} @@ -1531,7 +1711,9 @@ then the output would be: {'name': 'zed', 'age': 19}, ] -You can also do more complicated things like:: +You can also do more complicated things like: + +.. code-block:: html+django {% for book in books|dictsort:"author.age" %} * {{ book.title }} ({{ book.author.name }}) @@ -1547,14 +1729,18 @@ If ``books`` is: {'title': 'Alice', 'author': {'name': 'Lewis', 'age': 33}}, ] -then the output would be:: +then the output would be: + +.. code-block:: html+django * Alice (Lewis) * 1984 (George) * Timequake (Kurt) ``dictsort`` can also order a list of lists (or any other object implementing -``__getitem__()``) by elements at specified index. For example:: +``__getitem__()``) by elements at specified index. For example: + +.. code-block:: html+django {{ value|dictsort:0 }} @@ -1579,7 +1765,9 @@ then the output would be: ] You must pass the index as an integer rather than a string. The following -produce empty output:: +produce empty output: + +.. code-block:: html+django {{ values|dictsort:"0" }} @@ -1606,7 +1794,9 @@ but the returned value will be in reverse order. Returns ``True`` if the value is divisible by the argument. -For example:: +For example: + +.. code-block:: html+django {{ value|divisibleby:"3" }} @@ -1630,7 +1820,9 @@ applied to the result will only result in one round of escaping being done. So it is safe to use this function even in auto-escaping environments. If you want multiple escaping passes to be applied, use the :tfilter:`force_escape` filter. -For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off:: +For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off: + +.. code-block:: html+django {% autoescape off %} {{ title|escape }} @@ -1645,7 +1837,9 @@ Escapes characters for use in JavaScript strings. This does *not* make the string safe for use in HTML or JavaScript template literals, but does protect you from syntax errors when using templates to generate JavaScript/JSON. -For example:: +For example: + +.. code-block:: html+django {{ value|escapejs }} @@ -1660,7 +1854,9 @@ the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u00 Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``, ``'4.1 MB'``, ``'102 bytes'``, etc.). -For example:: +For example: + +.. code-block:: html+django {{ value|filesizeformat }} @@ -1681,7 +1877,9 @@ If ``value`` is 123456789, the output would be ``117.7 MB``. Returns the first item in a list. -For example:: +For example: + +.. code-block:: html+django {{ value|first }} @@ -1776,7 +1974,9 @@ want to apply other filters to the escaped results. Normally, you want to use the :tfilter:`escape` filter. For example, if you want to catch the ``

              `` HTML elements created by -the :tfilter:`linebreaks` filter:: +the :tfilter:`linebreaks` filter: + +.. code-block:: html+django {% autoescape off %} {{ body|linebreaks|force_escape }} @@ -1792,7 +1992,9 @@ digit, 2 is the second-right-most digit, etc. Returns the original value for invalid input (if input or argument is not an integer, or if argument is less than 1). Otherwise, output is always an integer. -For example:: +For example: + +.. code-block:: html+django {{ value|get_digit:"2" }} @@ -1810,7 +2012,9 @@ strings containing non-ASCII characters in a URL. It's safe to use this filter on a string that has already gone through the :tfilter:`urlencode` filter. -For example:: +For example: + +.. code-block:: html+django {{ value|iriencode }} @@ -1823,7 +2027,9 @@ If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&me=2"``. Joins a list with a string, like Python's ``str.join(list)`` -For example:: +For example: + +.. code-block:: html+django {{ value|join:" // " }} @@ -1840,7 +2046,9 @@ for use with JavaScript. **Argument:** The optional HTML "id" of the `` -With this name value, the template would be rendered as:: +With this name value, the template would be rendered as: + +.. code-block:: html+django Hello, @@ -476,7 +510,9 @@ Similarly, what if the name contained a ``'<'`` symbol, like this? username -That would result in a rendered template like this:: +That would result in a rendered template like this: + +.. code-block:: html+django Hello, username @@ -531,14 +567,18 @@ For individual variables ~~~~~~~~~~~~~~~~~~~~~~~~ To disable auto-escaping for an individual variable, use the :tfilter:`safe` -filter:: +filter: + +.. code-block:: html+django This will be escaped: {{ data }} This will not be escaped: {{ data|safe }} Think of *safe* as shorthand for *safe from further escaping* or *can be safely interpreted as HTML*. In this example, if ``data`` contains ``''``, -the output will be:: +the output will be: + +.. code-block:: html+django This will be escaped: <b> This will not be escaped: @@ -547,7 +587,9 @@ For template blocks ~~~~~~~~~~~~~~~~~~~ To control auto-escaping for a template, wrap the template (or a particular -section of the template) in the :ttag:`autoescape` tag, like so:: +section of the template) in the :ttag:`autoescape` tag, like so: + +.. code-block:: html+django {% autoescape off %} Hello {{ name }} @@ -555,7 +597,9 @@ section of the template) in the :ttag:`autoescape` tag, like so:: The :ttag:`autoescape` tag takes either ``on`` or ``off`` as its argument. At times, you might want to force auto-escaping when it would otherwise be -disabled. Here is an example template:: +disabled. Here is an example template: + +.. code-block:: html+django Auto-escaping is on by default. Hello {{ name }} @@ -590,7 +634,9 @@ just like all block tags. For example: Because auto-escaping is turned off in the base template, it will also be turned off in the child template, resulting in the following rendered -HTML when the ``greeting`` variable contains the string ``Hello!``:: +HTML when the ``greeting`` variable contains the string ``Hello!``: + +.. code-block:: html+django

              This & that

              Hello! @@ -614,7 +660,9 @@ danger of the :tfilter:`escape` filter *double-escaping* data -- the String literals and automatic escaping -------------------------------------- -As we mentioned earlier, filter arguments can be strings:: +As we mentioned earlier, filter arguments can be strings: + +.. code-block:: html+django {{ data|default:"This is a string literal." }} @@ -624,11 +672,15 @@ filter. The reasoning behind this is that the template author is in control of what goes into the string literal, so they can make sure the text is correctly escaped when the template is written. -This means you would write :: +This means you would write : + +.. code-block:: html+django {{ data|default:"3 < 2" }} -...rather than:: +...rather than: + +.. code-block:: html+django {{ data|default:"3 < 2" }} {# Bad! Don't do this. #} @@ -647,7 +699,9 @@ This means that templates have access to much more than just class attributes ORM provides the :ref:`"entry_set"` syntax for finding a collection of objects related on a foreign key. Therefore, given a model called "comment" with a foreign key relationship to a model called -"task" you can loop through all comments attached to a given task like this:: +"task" you can loop through all comments attached to a given task like this: + +.. code-block:: html+django {% for comment in task.comment_set.all %} {{ comment }} @@ -655,7 +709,9 @@ a model called "comment" with a foreign key relationship to a model called Similarly, :doc:`QuerySets` provide a ``count()`` method to count the number of objects they contain. Therefore, you can obtain a count -of all comments related to the current task with:: +of all comments related to the current task with: + +.. code-block:: html+django {{ task.comment_set.all.count }} @@ -686,7 +742,9 @@ Custom tag and filter libraries Certain applications provide custom tag and filter libraries. To access them in a template, ensure the application is in :setting:`INSTALLED_APPS` (we'd add ``'django.contrib.humanize'`` for this example), and then use the :ttag:`load` -tag in a template:: +tag in a template: + +.. code-block:: html+django {% load humanize %} @@ -698,7 +756,9 @@ makes the ``intcomma`` filter available for use. If you've enabled admin to find the list of custom libraries in your installation. The :ttag:`load` tag can take multiple library names, separated by spaces. -Example:: +Example: + +.. code-block:: html+django {% load humanize i18n %} diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index 87e8b7d0b7..b73814c861 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -174,7 +174,9 @@ further encoded when passed to ``iri_to_uri()``. This means you can pass a full URL to this function and it will not mess up the query string or anything like that. -An example might clarify things here:: +An example might clarify things here: + +.. code-block:: pycon >>> from urllib.parse import quote >>> from django.utils.encoding import iri_to_uri @@ -193,7 +195,9 @@ result. Similarly, Django provides :func:`django.utils.encoding.uri_to_iri()` which implements the conversion from URI to IRI as per :rfc:`3987#section-3.2`. -An example to demonstrate:: +An example to demonstrate: + +.. code-block:: pycon >>> from django.utils.encoding import uri_to_iri >>> uri_to_iri('/%E2%99%A5%E2%99%A5/?utf8=%E2%9C%93') @@ -309,7 +313,9 @@ and application server for the appropriate syntax and location to set this variable. See the :doc:`/howto/deployment/wsgi/modwsgi` for examples. In your development environment, you might need to add a setting to your -``~.bashrc`` analogous to::: +``~.bashrc`` analogous to: + +.. code-block:: shell export LANG="en_US.UTF-8" diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt index 2bde4d73ea..e375d55ec7 100644 --- a/docs/ref/urlresolvers.txt +++ b/docs/ref/urlresolvers.txt @@ -36,7 +36,9 @@ If the URL accepts arguments, you may pass them in ``args``. For example:: def myview(request): return HttpResponseRedirect(reverse('arch-summary', args=[1945])) -You can also pass ``kwargs`` instead of ``args``. For example:: +You can also pass ``kwargs`` instead of ``args``. For example: + +.. code-block:: pycon >>> reverse('admin:app_list', kwargs={'app_label': 'auth'}) '/admin/auth/' @@ -65,7 +67,9 @@ use for reversing. By default, the root URLconf for the current thread is used. .. note:: The string returned by ``reverse()`` is already - :ref:`urlquoted `. For example:: + :ref:`urlquoted `. For example: + + .. code-block:: pycon >>> reverse('cities', args=['Orléans']) '.../Orl%C3%A9ans/' diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index b1a08dc0e1..75e68aeed2 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -298,7 +298,9 @@ The functions defined in this module share the following properties: .. module:: django.utils.feedgenerator :synopsis: Syndication feed generation library -- used for generating RSS, etc. -Sample usage:: +Sample usage: + +.. code-block:: pycon >>> from django.utils import feedgenerator >>> feed = feedgenerator.Rss201rev2Feed( @@ -660,9 +662,11 @@ escaping HTML. Escapes all HTML/XML special characters with their Unicode escapes, so value is safe for use with JavaScript. Also wraps the escaped JSON in a ``' The ``encoder``, which defaults to @@ -806,7 +810,9 @@ appropriate entities. For building up fragments of HTML, you should normally be using :func:`django.utils.html.format_html` instead. - String marked safe will become unsafe again if modified. For example:: + String marked safe will become unsafe again if modified. For example: + + .. code-block:: pycon >>> mystr = 'Hello World ' >>> mystr = mark_safe(mystr) @@ -852,13 +858,17 @@ appropriate entities. #. Replacing any whitespace or repeated dashes with single dashes. #. Removing leading and trailing whitespace, dashes, and underscores. - For example:: + For example: + + .. code-block:: pycon >>> slugify(' Joel is a slug ') 'joel-is-a-slug' If you want to allow Unicode characters, pass ``allow_unicode=True``. For - example:: + example: + + .. code-block:: pycon >>> slugify('你好 World', allow_unicode=True) '你好-world' -- cgit v1.3
          ......
          ...