diff options
Diffstat (limited to 'docs/ref')
54 files changed, 2427 insertions, 816 deletions
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 </topics/db/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<int: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 </topics/pagination>`. 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() <class 'django.contrib.auth.models.User'> @@ -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 <django.contrib.contenttypes.models.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``:: <QuerySet [<TaggedItem: django>, <TaggedItem: python>]> 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() <QuerySet [<TaggedItem: django>, <TaggedItem: Web development>]> -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:: <QuerySet [<TaggedItem: django>]> 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') <QuerySet [<TaggedItem: django>, <TaggedItem: python>]> 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 </topics/db/aggregation>` 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(<field>__<lookup_type>=<parameter>) >>> 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(<field>__<lookup_type>=<parameter>) >>> qs = Elevation.objects.filter(<field>__<band_index>__<lookup_type>=<parameter>) >>> qs = Elevation.objects.filter(<field>__<lookup_type>=(<raster_input, <band_index>) -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 <https://postgis.net/docs/ST_AsBinary.html>`__, 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 <https://postgis.net/docs/ST_AsText.html>`__, 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 '<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>' .. 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 <https://trac.osgeo.org/geos/wiki/PreparedGeometry>`_. -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) <GEOSGeometry>`. - 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 <db name> $ psql <db name> @@ -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 <supported_units>` 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 <supported_units>` 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 <user_name> @@ -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 <user_name> 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 <user_name> 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 <user_name> 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] [<django.contrib.gis.gdal.feature.Feature object at 0x2f47690>, <django.contrib.gis.gdal.feature.Feature object at 0x2f47650>] -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 <geos>`. 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 </topics/db/sql>`, 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 %} <ul class="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 %} <ul class="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") <Publication: Publication object (1)> @@ -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 <https://en.wikipedia.org/wiki/Regression_analysis>`_):: +`wikipedia <https://en.wikipedia.org/wiki/Regression_analysis>`_): + +.. 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 <arrayfield.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 <ArrayField.size>` of the array. The lookups available after the transform are those from the -:attr:`base_field <ArrayField.base_field>`. For example:: +:attr:`base_field <ArrayField.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') <QuerySet [<Dog: Meg>]> -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') <QuerySet [<Dog: Rufus>, <Dog: Meg>]> -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 <hstorefield.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") ['<City: Middlesbrough>'] @@ -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') ['<Sentence: Gumby rides on the path of Middlesbrough>'] @@ -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") ['<City: Mexico>'] 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') [<Entry: Cheese on Toast recipes>, <Entry: Pizza Recipes>] @@ -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')) [<Entry: Pain perdu>] -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 </topics/db/models>`, which lives in :source:`django/contrib/redirects/models.py`. You can access redirect objects via the :doc:`Django database API </topics/db/queries>`. - 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 <dbname> 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 <tablename> 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 </ref/checks>` 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 <system-check-builtin-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 <serialization-formats>` 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:: <django.forms.fields.CharField object at 0x7ffaac6324d0> 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("</div>")[0] '<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject">' @@ -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 ``<input type="text">``, the data will be in the ``value`` attribute. If a field is represented by an ``<input type="checkbox">``, 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 ``<p>`` tags, with each ``<p>`` -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 ``<li>`` tags, with each ``<li>`` containing one field. It does *not* include the ``<ul>`` or ``</ul>``, so that -you can specify any HTML attributes on the ``<ul>`` for flexibility:: +you can specify any HTML attributes on the ``<ul>`` 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 ``<table>``:: +``as_table()`` renders the form as an HTML ``<table>``: + +.. 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 ``<label>`` -tags nor ``id`` attributes:: +tags nor ``id`` attributes: + +.. code-block:: pycon >>> f = ContactForm(auto_id=False) >>> print(f.as_div()) @@ -790,7 +840,9 @@ tags nor ``id`` attributes:: If ``auto_id`` is set to ``True``, then the form output *will* include ``<label>`` tags and will use the field name as its ``id`` for each form -field:: +field: + +.. code-block:: pycon >>> f = ContactForm(auto_id=True) >>> print(f.as_div()) @@ -803,7 +855,9 @@ If ``auto_id`` is set to a string containing the format character ``'%s'``, then the form output will include ``<label>`` tags, and will generate ``id`` attributes based on the format string. For example, for a format string ``'field_%s'``, a field named ``subject`` will get the ``id`` value -``'field_subject'``. Continuing our example:: +``'field_subject'``. Continuing our example: + +.. code-block:: pycon >>> f = ContactForm(auto_id='id_for_%s') >>> print(f.as_div()) @@ -823,7 +877,9 @@ A translatable string (defaults to a colon (``:``) in English) that will be appended after any label name when a form is rendered. It's possible to customize that character, or omit it entirely, using the -``label_suffix`` parameter:: +``label_suffix`` parameter: + +.. code-block:: pycon >>> f = ContactForm(auto_id='id_for_%s', label_suffix='') >>> print(f.as_div()) @@ -916,7 +972,9 @@ If you render a bound ``Form`` object, the act of rendering will automatically run the form's validation if it hasn't already happened, and the HTML output will include the validation errors as a ``<ul class="errorlist">`` near the field. The particular positioning of the error messages depends on the output -method you're using:: +method you're using: + +.. code-block:: pycon >>> data = {'subject': '', ... 'message': 'Hi there', @@ -1043,13 +1101,17 @@ they're not the only way a form object can be displayed. The ``__str__()`` method of this object displays the HTML for this field. To retrieve a single ``BoundField``, use dictionary lookup syntax on your form -using the field's name as the key:: +using the field's name as the key: + +.. code-block:: pycon >>> form = ContactForm() >>> print(form['subject']) <input id="id_subject" type="text" name="subject" maxlength="100" required> -To retrieve all ``BoundField`` objects, iterate the form:: +To retrieve all ``BoundField`` objects, iterate the form: + +.. code-block:: pycon >>> form = ContactForm() >>> for boundfield in form: print(boundfield) @@ -1058,7 +1120,9 @@ To retrieve all ``BoundField`` objects, iterate the form:: <input type="email" name="sender" id="id_sender" required> <input type="checkbox" name="cc_myself" id="id_cc_myself"> -The field-specific output honors the form object's ``auto_id`` setting:: +The field-specific output honors the form object's ``auto_id`` setting: + +.. code-block:: pycon >>> f = ContactForm(auto_id=False) >>> print(f['message']) @@ -1079,7 +1143,9 @@ Attributes of ``BoundField`` This property returns the data for this :class:`~django.forms.BoundField` extracted by the widget's :meth:`~django.forms.Widget.value_from_datadict` - method, or ``None`` if it wasn't given:: + method, or ``None`` if it wasn't given: + + .. code-block:: pycon >>> unbound_form = ContactForm() >>> print(unbound_form['subject'].data) @@ -1091,7 +1157,9 @@ Attributes of ``BoundField`` .. attribute:: BoundField.errors A :ref:`list-like object <ref-forms-error-list-format>` that is displayed - as an HTML ``<ul class="errorlist">`` when printed:: + as an HTML ``<ul class="errorlist">`` when printed: + + .. code-block:: pycon >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''} >>> f = ContactForm(data, auto_id=False) @@ -1160,7 +1228,9 @@ Attributes of ``BoundField`` :attr:`BoundField.initial` caches its return value, which is useful especially when dealing with callables whose return values can change (e.g. - ``datetime.now`` or ``uuid.uuid4``):: + ``datetime.now`` or ``uuid.uuid4``): + + .. code-block:: pycon >>> from datetime import datetime >>> class DatedCommentForm(CommentForm): @@ -1186,7 +1256,9 @@ Attributes of ``BoundField`` .. attribute:: BoundField.name - The name of this field in the form:: + The name of this field in the form: + + .. code-block:: pycon >>> f = ContactForm() >>> print(f['subject'].name) @@ -1204,7 +1276,9 @@ Attributes of ``BoundField`` Returns the lowercased class name of the wrapped field's widget, with any trailing ``input`` or ``widget`` removed. This may be used when building - forms where the layout is dependent upon the widget type. For example:: + forms where the layout is dependent upon the widget type. For example: + + .. code-block:: html+django {% for field in form %} {% if field.widget_type == 'checkbox' %} @@ -1240,7 +1314,9 @@ Methods of ``BoundField`` When you use Django's rendering shortcuts, CSS classes are used to indicate required form fields or fields that contain errors. If you're manually rendering a form, you can access these CSS classes using the - ``css_classes`` method:: + ``css_classes`` method: + + .. code-block:: pycon >>> f = ContactForm(data={'message': ''}) >>> f['message'].css_classes() @@ -1248,7 +1324,9 @@ Methods of ``BoundField`` If you want to provide some additional classes in addition to the error and required classes that may be required, you can provide - those classes as an argument:: + those classes as an argument: + + .. code-block:: pycon >>> f = ContactForm(data={'message': ''}) >>> f['message'].css_classes('foo bar') @@ -1281,7 +1359,9 @@ Methods of ``BoundField`` the field you declare, e.g. ``forms.CharField``. To separately render the label tag of a form field, you can call its - ``label_tag()`` method:: + ``label_tag()`` method: + + .. code-block:: pycon >>> f = ContactForm(data={'message': ''}) >>> print(f['message'].label_tag()) @@ -1308,7 +1388,9 @@ Methods of ``BoundField`` .. method:: BoundField.value() Use this method to render the raw value of this field as it would be rendered - by a ``Widget``:: + by a ``Widget``: + + .. code-block:: pycon >>> initial = {'subject': 'welcome'} >>> unbound_form = ContactForm(initial=initial) @@ -1368,7 +1450,9 @@ is a little more complicated than a normal form. Firstly, in order to upload files, you'll need to make sure that your ``<form>`` element correctly defines the ``enctype`` as -``"multipart/form-data"``:: +``"multipart/form-data"``: + +.. code-block:: html <form enctype="multipart/form-data" method="post" action="/foo/"> @@ -1377,7 +1461,9 @@ data is handled separately to normal form data, so when your form contains a ``FileField`` and ``ImageField``, you will need to specify a second argument when you bind your form. So if we extend our ContactForm to include an ``ImageField`` called ``mugshot``, we -need to bind the file data containing the mugshot image:: +need to bind the file data containing the mugshot image: + +.. code-block:: pycon # Bound form with an image field >>> from django.core.files.uploadedfile import SimpleUploadedFile @@ -1390,13 +1476,17 @@ need to bind the file data containing the mugshot image:: In practice, you will usually specify ``request.FILES`` as the source of file data (just like you use ``request.POST`` as the source of -form data):: +form data): + +.. code-block:: pycon # Bound form with an image field, data from the request >>> f = ContactFormWithMugshot(request.POST, request.FILES) Constructing an unbound form is the same as always -- omit both form data *and* -file data:: +file data: + +.. code-block:: pycon # Unbound form with an image field >>> f = ContactFormWithMugshot() @@ -1408,13 +1498,17 @@ Testing for multipart forms If you're writing reusable views or templates, you may not know ahead of time whether your form is a multipart form or not. The ``is_multipart()`` method -tells you whether the form requires multipart encoding for submission:: +tells you whether the form requires multipart encoding for submission: + +.. code-block:: pycon >>> f = ContactFormWithMugshot() >>> f.is_multipart() True -Here's an example of how you might use this in a template:: +Here's an example of how you might use this in a template: + +.. code-block:: html+django {% if form.is_multipart %} <form enctype="multipart/form-data" method="post" action="/foo/"> @@ -1436,7 +1530,9 @@ in the subclass. In this example, ``ContactFormWithPriority`` contains all the fields from ``ContactForm``, plus an additional field, ``priority``. The ``ContactForm`` -fields are ordered first:: +fields are ordered first: + +.. code-block:: pycon >>> class ContactFormWithPriority(ContactForm): ... priority = forms.CharField() @@ -1451,7 +1547,9 @@ fields are ordered first:: It's possible to subclass multiple forms, treating forms as mixins. In this example, ``BeatleForm`` subclasses both ``PersonForm`` and ``InstrumentForm`` (in that order), and its field list includes the fields from the parent -classes:: +classes: + +.. code-block:: pycon >>> from django import forms >>> class PersonForm(forms.Form): @@ -1469,7 +1567,9 @@ classes:: <div>Haircut type:<input type="text" name="haircut_type" required></div> It's possible to declaratively remove a ``Field`` inherited from a parent class -by setting the name of the field to ``None`` on the subclass. For example:: +by setting the name of the field to ``None`` on the subclass. For example: + +.. code-block:: pycon >>> from django import forms @@ -1491,7 +1591,9 @@ Prefixes for forms .. attribute:: Form.prefix You can put several Django forms inside one ``<form>`` tag. To give each -``Form`` its own namespace, use the ``prefix`` keyword argument:: +``Form`` its own namespace, use the ``prefix`` keyword argument: + +.. code-block:: pycon >>> mother = PersonForm(prefix="mother") >>> father = PersonForm(prefix="father") @@ -1502,7 +1604,9 @@ You can put several Django forms inside one ``<form>`` tag. To give each <div><label for="id_father-first_name">First name:</label><input type="text" name="father-first_name" required id="id_father-first_name"></div> <div><label for="id_father-last_name">Last name:</label><input type="text" name="father-last_name" required id="id_father-last_name"></div> -The prefix can also be specified on the form class:: +The prefix can also be specified on the form class: + +.. code-block:: pycon >>> class PersonForm(forms.Form): ... ... diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 3b59dd3b07..c685775e5e 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -20,7 +20,9 @@ you can also instantiate them and use them directly to get a better idea of how they work. Each ``Field`` instance has a ``clean()`` method, which takes a single argument and either raises a ``django.core.exceptions.ValidationError`` exception or returns the clean -value:: +value: + +.. code-block:: pycon >>> from django import forms >>> f = forms.EmailField() @@ -47,7 +49,9 @@ should *always* be accepted: By default, each ``Field`` class assumes the value is required, so if you pass an empty value -- either ``None`` or the empty string (``""``) -- then -``clean()`` will raise a ``ValidationError`` exception:: +``clean()`` will raise a ``ValidationError`` exception: + +.. code-block:: pycon >>> from django import forms >>> f = forms.CharField() @@ -71,7 +75,9 @@ an empty value -- either ``None`` or the empty string (``""``) -- then 'False' To specify that a field is *not* required, pass ``required=False`` to the -``Field`` constructor:: +``Field`` constructor: + +.. code-block:: pycon >>> f = forms.CharField(required=False) >>> f.clean('foo') @@ -112,7 +118,9 @@ spaces and upper-casing the first letter. Specify ``label`` if that default behavior doesn't result in an adequate label. Here's a full example ``Form`` that implements ``label`` for two of its fields. -We've specified ``auto_id=False`` to simplify the output:: +We've specified ``auto_id=False`` to simplify the output: + +.. code-block:: pycon >>> from django import forms >>> class CommentForm(forms.Form): @@ -131,7 +139,9 @@ We've specified ``auto_id=False`` to simplify the output:: .. attribute:: Field.label_suffix The ``label_suffix`` argument lets you override the form's -:attr:`~django.forms.Form.label_suffix` on a per-field basis:: +:attr:`~django.forms.Form.label_suffix` on a per-field basis: + +.. code-block:: pycon >>> class ContactForm(forms.Form): ... age = forms.IntegerField() @@ -154,7 +164,9 @@ rendering this ``Field`` in an unbound ``Form``. To specify dynamic initial data, see the :attr:`Form.initial` parameter. The use-case for this is when you want to display an "empty" form in which a -field is initialized to a particular value. For example:: +field is initialized to a particular value. For example: + +.. code-block:: pycon >>> from django import forms >>> class CommentForm(forms.Form): @@ -169,7 +181,9 @@ field is initialized to a particular value. For example:: You may be thinking, why not just pass a dictionary of the initial values as data when displaying the form? Well, if you do that, you'll trigger validation, -and the HTML output will include any validation errors:: +and the HTML output will include any validation errors: + +.. code-block:: pycon >>> class CommentForm(forms.Form): ... name = forms.CharField() @@ -187,7 +201,9 @@ forms, the HTML output will use the bound data. Also note that ``initial`` values are *not* used as "fallback" data in validation if a particular field's value is not given. ``initial`` values are -*only* intended for initial form display:: +*only* intended for initial form display: + +.. code-block:: pycon >>> class CommentForm(forms.Form): ... name = forms.CharField(initial='Your name') @@ -201,7 +217,9 @@ validation if a particular field's value is not given. ``initial`` values are >>> f.errors {'url': ['This field is required.'], 'name': ['This field is required.']} -Instead of a constant, you can also pass any callable:: +Instead of a constant, you can also pass any callable: + +.. code-block:: pycon >>> import datetime >>> class DateForm(forms.Form): @@ -233,7 +251,9 @@ Like the model field's :attr:`~django.db.models.Field.help_text`, this value isn't HTML-escaped in automatically-generated forms. Here's a full example ``Form`` that implements ``help_text`` for two of its -fields. We've specified ``auto_id=False`` to simplify the output:: +fields. We've specified ``auto_id=False`` to simplify the output: + +.. code-block:: pycon >>> from django import forms >>> class HelpTextContactForm(forms.Form): @@ -265,7 +285,9 @@ fields. We've specified ``auto_id=False`` to simplify the output:: The ``error_messages`` argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you -want to override. For example, here is the default error message:: +want to override. For example, here is the default error message: + +.. code-block:: pycon >>> from django import forms >>> generic = forms.CharField() @@ -274,7 +296,9 @@ want to override. For example, here is the default error message:: ... ValidationError: ['This field is required.'] -And here is a custom error message:: +And here is a custom error message: + +.. code-block:: pycon >>> name = forms.CharField(error_messages={'required': 'Please enter your name'}) >>> name.clean('') @@ -464,15 +488,15 @@ For each field, we describe the default widget used if you don't specify The field always accepts strings in ISO 8601 formatted dates or similar recognized by :func:`~django.utils.dateparse.parse_datetime`. Some examples - are:: + are: - * '2006-10-25 14:30:59' - * '2006-10-25T14:30:59' - * '2006-10-25 14:30' - * '2006-10-25T14:30' - * '2006-10-25T14:30Z' - * '2006-10-25T14:30+02:00' - * '2006-10-25' + * ``'2006-10-25 14:30:59'`` + * ``'2006-10-25T14:30:59'`` + * ``'2006-10-25 14:30'`` + * ``'2006-10-25T14:30'`` + * ``'2006-10-25T14:30Z'`` + * ``'2006-10-25T14:30+02:00'`` + * ``'2006-10-25'`` If no ``input_formats`` argument is provided, the default input formats are taken from :setting:`DATETIME_INPUT_FORMATS` and @@ -731,7 +755,9 @@ For each field, we describe the default widget used if you don't specify non-image data attributes, such as ``format``, ``height``, and ``width``, are available, methods that access the underlying image data, such as ``getdata()`` or ``getpixel()``, cannot be used without reopening the file. - For example:: + For example: + + .. code-block:: pycon >>> from PIL import Image >>> from django import forms diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 40c030669c..729bbc718e 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -86,7 +86,9 @@ buttons. :class:`Select` widgets are used by default on :class:`ChoiceField` fields. The choices displayed on the widget are inherited from the :class:`ChoiceField` and changing :attr:`ChoiceField.choices` will update :attr:`Select.choices`. For -example:: +example: + +.. code-block:: pycon >>> from django import forms >>> CHOICES = [('1', 'First'), ('2', 'Second')] @@ -137,7 +139,9 @@ For example, take the following form:: This form will include three default :class:`TextInput` widgets, with default rendering -- no CSS class, no extra attributes. This means that the input boxes -provided for each widget will be rendered exactly the same:: +provided for each widget will be rendered exactly the same: + +.. code-block:: pycon >>> f = CommentForm(auto_id=False) >>> f.as_table() @@ -232,7 +236,9 @@ foundation for custom widgets. '<input title="Your name" type="text" name="name" value="A name" size="10">' If you assign a value of ``True`` or ``False`` to an attribute, - it will be rendered as an HTML5 boolean attribute:: + it will be rendered as an HTML5 boolean attribute: + + .. code-block:: pycon >>> name = forms.TextInput(attrs={'required': True}) >>> name.render('name', 'A name') @@ -363,7 +369,9 @@ foundation for custom widgets. .. attribute:: MultiWidget.widgets - An iterable containing the widgets needed. For example:: + An iterable containing the widgets needed. For example: + + .. code-block:: pycon >>> from django.forms import MultiWidget, TextInput >>> widget = MultiWidget(widgets=[TextInput, TextInput]) @@ -375,7 +383,9 @@ foundation for custom widgets. ``(key, widget)`` pair, the key will be appended to the ``name`` of the widget in order to generate the attribute value. You may provide the empty string (``''``) for a single key, in order to suppress the suffix - for one widget. For example:: + for one widget. For example: + + .. code-block:: pycon >>> widget = MultiWidget(widgets={'': TextInput, 'last': TextInput}) >>> widget.render('name', ['john', 'paul']) diff --git a/docs/ref/models/conditional-expressions.txt b/docs/ref/models/conditional-expressions.txt index a58a938e09..8dd477a187 100644 --- a/docs/ref/models/conditional-expressions.txt +++ b/docs/ref/models/conditional-expressions.txt @@ -48,7 +48,9 @@ objects that have an ``output_field`` that is a :class:`~django.db.models.BooleanField`. The result is provided using the ``then`` keyword. -Some examples:: +Some examples: + +.. code-block:: pycon >>> from django.db.models import F, Q, When >>> # String arguments refer to fields; the following two examples are equivalent: @@ -83,7 +85,9 @@ Keep in mind that each of these values can be an expression. Since the ``then`` keyword argument is reserved for the result of the ``When()``, there is a potential conflict if a :class:`~django.db.models.Model` has a field named ``then``. This can be - resolved in two ways:: + resolved in two ways: + + .. code-block:: pycon >>> When(then__exact=0, then=1) >>> When(Q(then=0), then=1) @@ -99,7 +103,9 @@ A ``Case()`` expression is like the :keyword:`if` ... :keyword:`elif` ... truthful value. The ``result`` expression from the matching ``When()`` object is returned. -An example:: +An example: + +.. code-block:: pycon >>> >>> from datetime import date, timedelta @@ -133,7 +139,9 @@ argument is returned. If a ``default`` argument isn't provided, ``None`` is used. If we wanted to change our previous query to get the discount based on how long -the ``Client`` has been with us, we could do so using lookups:: +the ``Client`` has been with us, we could do so using lookups: + +.. code-block:: pycon >>> a_month_ago = date.today() - timedelta(days=30) >>> a_year_ago = date.today() - timedelta(days=365) @@ -156,7 +164,9 @@ the ``Client`` has been with us, we could do so using lookups:: ``Case()`` also works in a ``filter()`` clause. For example, to find gold clients that registered more than a month ago and platinum clients that -registered more than a year ago:: +registered more than a year ago: + +.. code-block:: pycon >>> a_month_ago = date.today() - timedelta(days=30) >>> a_year_ago = date.today() - timedelta(days=365) @@ -180,7 +190,9 @@ Conditional update Let's say we want to change the ``account_type`` for our clients to match their registration dates. We can do this using a conditional expression and the -:meth:`~django.db.models.query.QuerySet.update` method:: +:meth:`~django.db.models.query.QuerySet.update` method: + +.. code-block:: pycon >>> a_month_ago = date.today() - timedelta(days=30) >>> a_year_ago = date.today() - timedelta(days=365) @@ -204,7 +216,9 @@ Conditional aggregation What if we want to find out how many clients there are for each ``account_type``? We can use the ``filter`` argument of :ref:`aggregate -functions <aggregation-functions>` to achieve this:: +functions <aggregation-functions>` to achieve this: + +.. code-block:: pycon >>> # Create some more Clients first so we can have something to count >>> Client.objects.create( @@ -255,7 +269,9 @@ Conditional filter When a conditional expression returns a boolean value, it is possible to use it directly in filters. This means that it will not be added to the ``SELECT`` -columns, but you can still use it to filter results:: +columns, but you can still use it to filter results: + +.. code-block:: pycon >>> non_unique_account_type = Client.objects.filter( ... account_type=OuterRef('account_type'), diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index f33e4f5370..f6d597a266 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -35,7 +35,9 @@ Comparison and conversion functions Forces the result type of ``expression`` to be the one from ``output_field``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Cast @@ -56,7 +58,9 @@ first non-null value (note that an empty string is not considered a null value). Each argument must be of a similar type, so mixing text and numbers will result in a database error. -Usage examples:: +Usage examples: + +.. code-block:: pycon >>> # Get a screen name from least to most public >>> from django.db.models import Sum @@ -99,12 +103,16 @@ Usage examples:: Takes an expression and a collation name to query against. -For example, to filter case-insensitively in SQLite:: +For example, to filter case-insensitively in SQLite: + +.. code-block:: pycon >>> Author.objects.filter(name=Collate(Value('john'), 'nocase')) <QuerySet [<Author: John>, <Author: john>]> -It can also be used when ordering, for example with PostgreSQL:: +It can also be used when ordering, for example with PostgreSQL: + +.. code-block:: pycon >>> Author.objects.order_by(Collate('name', 'et-x-icu')) <QuerySet [<Author: Ursula>, <Author: Veronika>, <Author: Ülle>]> @@ -129,6 +137,8 @@ Usage example:: modified = models.DateTimeField(auto_now=True) blog = models.ForeignKey(Blog, on_delete=models.CASCADE) +.. code-block:: pycon + >>> from django.db.models.functions import Greatest >>> blog = Blog.objects.create(body='Greatest is the best.') >>> comment = Comment.objects.create(body='No, Least is better.', blog=blog) @@ -159,7 +169,9 @@ and ``comment.modified``. Takes a list of key-value pairs and returns a JSON object containing those pairs. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models import F >>> from django.db.models.functions import JSONObject, Lower @@ -272,7 +284,9 @@ returned when this timezone is active will be the same as above except for: databases and from Python's standard functions. This function will return ``1`` for Sunday, ``2`` for Monday, through ``7`` for Saturday. - The equivalent calculation in Python is:: + The equivalent calculation in Python is: + + .. code-block:: pycon >>> from datetime import datetime >>> dt = datetime(2015, 6, 15) @@ -292,7 +306,9 @@ Each ``lookup_name`` above has a corresponding ``Extract`` subclass (listed below) that should typically be used instead of the more verbose equivalent, e.g. use ``ExtractYear(...)`` rather than ``Extract(..., lookup_name='year')``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from datetime import datetime >>> from django.db.models.functions import Extract @@ -356,7 +372,9 @@ class is also a ``Transform`` registered on ``DateField`` and ``DateTimeField`` as ``__(lookup_name)``, e.g. ``__year``. Since ``DateField``\s don't have a time component, only ``Extract`` subclasses -that deal with date-parts can be used with ``DateField``:: +that deal with date-parts can be used with ``DateField``: + +.. code-block:: pycon >>> from datetime import datetime, timezone >>> from django.db.models.functions import ( @@ -406,7 +424,9 @@ These are logically equivalent to ``Extract('datetime_field', lookup_name)``. Each class is also a ``Transform`` registered on ``DateTimeField`` as ``__(lookup_name)``, e.g. ``__minute``. -``DateTimeField`` examples:: +``DateTimeField`` examples: + +.. code-block:: pycon >>> from datetime import datetime, timezone >>> from django.db.models.functions import ( @@ -443,7 +463,9 @@ When :setting:`USE_TZ` is ``True`` then datetimes are stored in the database in UTC. If a different timezone is active in Django, the datetime is converted to that timezone before the value is extracted. The example below converts to the Melbourne timezone (UTC +10:00), which changes the day, weekday, and hour -values that are returned:: +values that are returned: + +.. code-block:: pycon >>> from django.utils import timezone >>> import zoneinfo @@ -460,7 +482,9 @@ values that are returned:: {'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9} Explicitly passing the timezone to the ``Extract`` function behaves in the same -way, and takes priority over an active timezone:: +way, and takes priority over an active timezone: + +.. code-block:: pycon >>> import zoneinfo >>> melb = zoneinfo.ZoneInfo('Australia/Melbourne') @@ -482,7 +506,9 @@ way, and takes priority over an active timezone:: Returns the database server's current date and time when the query is executed, typically using the SQL ``CURRENT_TIMESTAMP``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Now >>> Article.objects.filter(published__lte=Now()) @@ -566,7 +592,9 @@ The subclasses are all defined as transforms, but they aren't registered with any fields, because the lookup names are already reserved by the ``Extract`` subclasses. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from datetime import datetime >>> from django.db.models import Count, DateTimeField @@ -622,7 +650,9 @@ with less precision. ``expression`` can have an ``output_field`` of either ``DateField`` or ``DateTimeField``. Since ``DateField``\s don't have a time component, only ``Trunc`` subclasses -that deal with date-parts can be used with ``DateField``:: +that deal with date-parts can be used with ``DateField``: + +.. code-block:: pycon >>> from datetime import datetime, timezone >>> from django.db.models import Count @@ -700,7 +730,9 @@ truncate all parts of the date up to ``kind`` and allow grouping or filtering datetimes with less precision. ``expression`` must have an ``output_field`` of ``DateTimeField``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from datetime import date, datetime, timezone >>> from django.db.models import Count @@ -753,7 +785,9 @@ with less precision. ``expression`` can have an ``output_field`` of either ``TimeField`` or ``DateTimeField``. Since ``TimeField``\s don't have a date component, only ``Trunc`` subclasses -that deal with time-parts can be used with ``TimeField``:: +that deal with time-parts can be used with ``TimeField``: + +.. code-block:: pycon >>> from datetime import datetime, timezone >>> from django.db.models import Count, TimeField @@ -802,7 +836,9 @@ We'll be using the following model in math function examples:: Returns the absolute value of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Abs >>> Vector.objects.create(x=-0.5, y=1.1) @@ -810,7 +846,9 @@ Usage example:: >>> vector.x_abs, vector.y_abs (0.5, 1.1) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Abs @@ -826,7 +864,9 @@ It can also be registered as a transform. For example:: Returns the arccosine of a numeric field or expression. The expression value must be within the range -1 to 1. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import ACos >>> Vector.objects.create(x=0.5, y=-0.9) @@ -834,7 +874,9 @@ Usage example:: >>> vector.x_acos, vector.y_acos (1.0471975511965979, 2.6905658417935308) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import ACos @@ -850,7 +892,9 @@ It can also be registered as a transform. For example:: Returns the arcsine of a numeric field or expression. The expression value must be in the range -1 to 1. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import ASin >>> Vector.objects.create(x=0, y=1) @@ -858,7 +902,9 @@ Usage example:: >>> vector.x_asin, vector.y_asin (0.0, 1.5707963267948966) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import ASin @@ -873,7 +919,9 @@ It can also be registered as a transform. For example:: Returns the arctangent of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import ATan >>> Vector.objects.create(x=3.12, y=6.987) @@ -881,7 +929,9 @@ Usage example:: >>> vector.x_atan, vector.y_atan (1.2606282660069106, 1.428638798133829) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import ATan @@ -896,7 +946,9 @@ It can also be registered as a transform. For example:: Returns the arctangent of ``expression1 / expression2``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import ATan2 >>> Vector.objects.create(x=2.5, y=1.9) @@ -912,7 +964,9 @@ Usage example:: Returns the smallest integer greater than or equal to a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Ceil >>> Vector.objects.create(x=3.12, y=7.0) @@ -920,7 +974,9 @@ Usage example:: >>> vector.x_ceil, vector.y_ceil (4.0, 7.0) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Ceil @@ -935,7 +991,9 @@ It can also be registered as a transform. For example:: Returns the cosine of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Cos >>> Vector.objects.create(x=-8.0, y=3.1415926) @@ -943,7 +1001,9 @@ Usage example:: >>> vector.x_cos, vector.y_cos (-0.14550003380861354, -0.9999999999999986) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Cos @@ -958,7 +1018,9 @@ It can also be registered as a transform. For example:: Returns the cotangent of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Cot >>> Vector.objects.create(x=12.0, y=1.0) @@ -966,7 +1028,9 @@ Usage example:: >>> vector.x_cot, vector.y_cot (-1.5726734063976826, 0.642092615934331) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Cot @@ -981,7 +1045,9 @@ It can also be registered as a transform. For example:: Converts a numeric field or expression from radians to degrees. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Degrees >>> Vector.objects.create(x=-1.57, y=3.14) @@ -989,7 +1055,9 @@ Usage example:: >>> vector.x_d, vector.y_d (-89.95437383553924, 179.9087476710785) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Degrees @@ -1005,7 +1073,9 @@ It can also be registered as a transform. For example:: Returns the value of ``e`` (the natural logarithm base) raised to the power of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Exp >>> Vector.objects.create(x=5.4, y=-2.0) @@ -1013,7 +1083,9 @@ Usage example:: >>> vector.x_exp, vector.y_exp (221.40641620418717, 0.1353352832366127) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Exp @@ -1029,7 +1101,9 @@ It can also be registered as a transform. For example:: Returns the largest integer value not greater than a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Floor >>> Vector.objects.create(x=5.4, y=-2.3) @@ -1037,7 +1111,9 @@ Usage example:: >>> vector.x_floor, vector.y_floor (5.0, -3.0) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Floor @@ -1052,7 +1128,9 @@ It can also be registered as a transform. For example:: Returns the natural logarithm a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Ln >>> Vector.objects.create(x=5.4, y=233.0) @@ -1060,7 +1138,9 @@ Usage example:: >>> vector.x_ln, vector.y_ln (1.6863989535702288, 5.4510384535657) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Ln @@ -1076,7 +1156,9 @@ It can also be registered as a transform. For example:: Accepts two numeric fields or expressions and returns the logarithm of the first to base of the second. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Log >>> Vector.objects.create(x=2.0, y=4.0) @@ -1092,7 +1174,9 @@ Usage example:: Accepts two numeric fields or expressions and returns the remainder of the first divided by the second (modulo operation). -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Mod >>> Vector.objects.create(x=5.4, y=2.3) @@ -1115,7 +1199,9 @@ Returns the value of the mathematical constant ``π``. Accepts two numeric fields or expressions and returns the value of the first raised to the power of the second. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Power >>> Vector.objects.create(x=2, y=-2) @@ -1130,7 +1216,9 @@ Usage example:: Converts a numeric field or expression from degrees to radians. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Radians >>> Vector.objects.create(x=-90, y=180) @@ -1138,7 +1226,9 @@ Usage example:: >>> vector.x_r, vector.y_r (-1.5707963267948966, 3.141592653589793) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Radians @@ -1162,7 +1252,9 @@ Rounds a numeric field or expression to ``precision`` (must be an integer) decimal places. By default, it rounds to the nearest integer. Whether half values are rounded up or down depends on the database. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Round >>> Vector.objects.create(x=5.4, y=-2.37) @@ -1170,7 +1262,9 @@ Usage example:: >>> vector.x_r, vector.y_r (5.0, -2.4) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Round @@ -1185,7 +1279,9 @@ It can also be registered as a transform. For example:: Returns the sign (-1, 0, 1) of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Sign >>> Vector.objects.create(x=5.4, y=-2.3) @@ -1193,7 +1289,9 @@ Usage example:: >>> vector.x_sign, vector.y_sign (1, -1) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Sign @@ -1208,7 +1306,9 @@ It can also be registered as a transform. For example:: Returns the sine of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Sin >>> Vector.objects.create(x=5.4, y=-2.3) @@ -1216,7 +1316,9 @@ Usage example:: >>> vector.x_sin, vector.y_sin (-0.7727644875559871, -0.7457052121767203) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Sin @@ -1231,7 +1333,9 @@ It can also be registered as a transform. For example:: Returns the square root of a nonnegative numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Sqrt >>> Vector.objects.create(x=4.0, y=12.0) @@ -1239,7 +1343,9 @@ Usage example:: >>> vector.x_sqrt, vector.y_sqrt (2.0, 3.46410) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Sqrt @@ -1254,7 +1360,9 @@ It can also be registered as a transform. For example:: Returns the tangent of a numeric field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Tan >>> Vector.objects.create(x=0, y=12) @@ -1262,7 +1370,9 @@ Usage example:: >>> vector.x_tan, vector.y_tan (0.0, -0.6358599286615808) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import FloatField >>> from django.db.models.functions import Tan @@ -1287,7 +1397,9 @@ function. Like :class:`Length`, it can be registered as a transform on ``IntegerField``. The default lookup name is ``chr``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Chr >>> Author.objects.create(name='Margaret Smith') @@ -1311,7 +1423,9 @@ This function will never have a null result. On backends where a null argument results in the entire expression being null, Django will ensure that each null part is converted to an empty string first. -Usage example:: +Usage example: + +.. code-block:: pycon >>> # Get the display name as "name (goes_by)" >>> from django.db.models import CharField, Value as V @@ -1333,7 +1447,9 @@ Usage example:: Returns the first ``length`` characters of the given text field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Left >>> Author.objects.create(name='Margaret Smith') @@ -1349,7 +1465,9 @@ Usage example:: Accepts a single text field or expression and returns the number of characters the value has. If the expression is null, then the length will also be null. -Usage example:: +Usage example: + +.. code-block:: pycon >>> # Get the length of the name and goes_by fields >>> from django.db.models.functions import Length @@ -1360,7 +1478,9 @@ Usage example:: >>> print(author.name_length, author.goes_by_length) (14, None) -It can also be registered as a transform. For example:: +It can also be registered as a transform. For example: + +.. code-block:: pycon >>> from django.db.models import CharField >>> from django.db.models.functions import Length @@ -1378,7 +1498,9 @@ representation. It can also be registered as a transform as described in :class:`Length`. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Lower >>> Author.objects.create(name='Margaret Smith') @@ -1395,7 +1517,9 @@ Returns the value of the given text field or expression padded on the left side with ``fill_text`` so that the resulting value is ``length`` characters long. The default ``fill_text`` is a space. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models import Value >>> from django.db.models.functions import LPad @@ -1423,7 +1547,9 @@ string. It can also be registered as a transform as described in :class:`Length`. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import MD5 >>> Author.objects.create(name='Margaret Smith') @@ -1444,7 +1570,9 @@ than one character long. It can also be registered as a transform as described in :class:`Length`. The default lookup name is ``ord``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Ord >>> Author.objects.create(name='Margaret Smith') @@ -1460,7 +1588,9 @@ Usage example:: Returns the value of the given text field or expression repeated ``number`` times. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Repeat >>> Author.objects.create(name='John', alias='j') @@ -1478,7 +1608,9 @@ Replaces all occurrences of ``text`` with ``replacement`` in ``expression``. The default replacement text is the empty string. The arguments to the function are case-sensitive. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models import Value >>> from django.db.models.functions import Replace @@ -1500,7 +1632,9 @@ expression in reverse order. It can also be registered as a transform as described in :class:`Length`. The default lookup name is ``reverse``. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Reverse >>> Author.objects.create(name='Margaret Smith') @@ -1515,7 +1649,9 @@ Usage example:: Returns the last ``length`` characters of the given text field or expression. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Right >>> Author.objects.create(name='Margaret Smith') @@ -1553,7 +1689,9 @@ the string. They can also be registered as transforms as described in :class:`Length`. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import SHA1 >>> Author.objects.create(name='Margaret Smith') @@ -1581,7 +1719,9 @@ Returns a positive integer corresponding to the 1-indexed position of the first occurrence of ``substring`` inside ``string``, or 0 if ``substring`` is not found. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models import Value as V >>> from django.db.models.functions import StrIndex @@ -1613,7 +1753,9 @@ Returns a substring of length ``length`` from the field or expression starting at position ``pos``. The position is 1-indexed, so the position must be greater than 0. If ``length`` is ``None``, then the rest of the string will be returned. -Usage example:: +Usage example: + +.. code-block:: pycon >>> # Set the alias to the first 5 characters of the name as lowercase >>> from django.db.models.functions import Lower, Substr @@ -1631,7 +1773,9 @@ Usage example:: Returns the value of the given text field or expression with leading and trailing spaces removed. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Trim >>> Author.objects.create(name=' John ', alias='j') @@ -1650,7 +1794,9 @@ representation. It can also be registered as a transform as described in :class:`Length`. -Usage example:: +Usage example: + +.. code-block:: pycon >>> from django.db.models.functions import Upper >>> Author.objects.create(name='Margaret Smith') diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index e1edad2e4d..6a59822e8e 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -232,7 +232,9 @@ directly support ``output_field`` you will need to wrap the expression with F('active_at') + F('duration'), output_field=DateTimeField())) When referencing relational fields such as ``ForeignKey``, ``F()`` returns the -primary key value rather than a model instance:: +primary key value rather than a model instance: + +.. code-block:: pycon >> car = Company.objects.annotate(built_by=F('manufacturer'))[0] >> car.manufacturer @@ -547,7 +549,9 @@ You can add an explicit subquery to a ``QuerySet`` using the ``Subquery`` expression. For example, to annotate each post with the email address of the author of the -newest comment on that post:: +newest comment on that post: + +.. code-block:: pycon >>> from django.db.models import OuterRef, Subquery >>> newest = Comment.objects.filter(post=OuterRef('pk')).order_by('-created_at') @@ -584,7 +588,9 @@ outer queryset is resolved. Instances of ``OuterRef`` may be used in conjunction with nested instances of ``Subquery`` to refer to a containing queryset that isn't the immediate parent. For example, this queryset would need to be within a nested pair of -``Subquery`` instances to resolve correctly:: +``Subquery`` instances to resolve correctly: + +.. code-block:: pycon >>> Book.objects.filter(author=OuterRef(OuterRef('pk'))) @@ -593,7 +599,9 @@ Limiting a subquery to a single column There are times when a single column must be returned from a ``Subquery``, for instance, to use a ``Subquery`` as the target of an ``__in`` lookup. To return -all comments for posts published within the last day:: +all comments for posts published within the last day: + +.. code-block:: pycon >>> from datetime import timedelta >>> from django.utils import timezone @@ -608,7 +616,9 @@ Limiting the subquery to a single row ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To prevent a subquery from returning multiple rows, a slice (``[:1]``) of the -queryset is used:: +queryset is used: + +.. code-block:: pycon >>> subquery = Subquery(newest.values('email')[:1]) >>> Post.objects.annotate(newest_commenter_email=subquery) @@ -630,7 +640,9 @@ many cases it will perform better than a subquery since the database is able to stop evaluation of the subquery when a first matching row is found. For example, to annotate each post with whether or not it has a comment from -within the last day:: +within the last day: + +.. code-block:: pycon >>> from django.db.models import Exists, OuterRef >>> from datetime import timedelta @@ -668,7 +680,9 @@ Filtering on a ``Subquery()`` or ``Exists()`` expressions ``Subquery()`` that returns a boolean value and ``Exists()`` may be used as a ``condition`` in :class:`~django.db.models.expressions.When` expressions, or to -directly filter a queryset:: +directly filter a queryset: + +.. code-block:: pycon >>> recent_comments = Comment.objects.filter(...) # From above >>> Post.objects.filter(Exists(recent_comments)) @@ -684,7 +698,9 @@ combination of :meth:`~.QuerySet.filter`, :meth:`~.QuerySet.values`, and :meth:`~.QuerySet.annotate` to get the subquery grouping correct. Assuming both models have a ``length`` field, to find posts where the post -length is greater than the total length of all combined comments:: +length is greater than the total length of all combined comments: + +.. code-block:: pycon >>> from django.db.models import OuterRef, Subquery, Sum >>> comments = Comment.objects.filter(post=OuterRef('pk')).order_by().values('post') @@ -710,7 +726,9 @@ Raw SQL expressions .. class:: RawSQL(sql, params, output_field=None) Sometimes database expressions can't easily express a complex ``WHERE`` clause. -In these edge cases, use the ``RawSQL`` expression. For example:: +In these edge cases, use the ``RawSQL`` expression. For example: + +.. code-block:: pycon >>> from django.db.models.expressions import RawSQL >>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (param,))) @@ -719,7 +737,9 @@ These extra lookups may not be portable to different database engines (because you're explicitly writing SQL code) and violate the DRY principle, so you should avoid them if possible. -``RawSQL`` expressions can also be used as the target of ``__in`` filters:: +``RawSQL`` expressions can also be used as the target of ``__in`` filters: + +.. code-block:: pycon >>> queryset.filter(id__in=RawSQL("select id from sometable where col = %s", (param,))) @@ -732,7 +752,9 @@ should avoid them if possible. your SQL with user-provided data. You also must not quote placeholders in the SQL string. This example is - vulnerable to SQL injection because of the quotes around ``%s``:: + vulnerable to SQL injection because of the quotes around ``%s``: + + .. code-block:: pycon RawSQL("select col from sometable where othercol = '%s'") # unsafe! @@ -789,7 +811,9 @@ computation. See :ref:`window-frames` for details. Support for ``order_by`` by field name references was added. For example, to annotate each movie with the average rating for the movies by -the same studio in the same genre and release year:: +the same studio in the same genre and release year: + +.. code-block:: pycon >>> from django.db.models import Avg, F, Window >>> Movie.objects.annotate( @@ -807,7 +831,9 @@ same partition and frame. For example, you could modify the previous example to also include the best and worst rating in each movie's group (same studio, genre, and release year) by using three window functions in the same query. The partition and ordering from the previous example is extracted into a dictionary -to reduce repetition:: +to reduce repetition: + +.. code-block:: pycon >>> from django.db.models import Avg, F, Max, Min, Window >>> window = { @@ -833,7 +859,9 @@ performing aggregation. For example, a query that relies on aggregation and has an ``OR``-ed filter against a window function and a field is not supported. Applying combined predicates post-aggregation could cause rows that would normally be excluded -from groups to be included:: +from groups to be included: + +.. code-block:: pycon >>> qs = Movie.objects.annotate( >>> category_rank=Window( @@ -882,7 +910,9 @@ ordinary sequence of rows. This attribute is set to ``'ROWS'``. -Both classes return SQL with the template:: +Both classes return SQL with the template: + +.. code-block:: sql %(frame_type)s BETWEEN %(start)s AND %(end)s @@ -913,7 +943,9 @@ includes both the ``start`` and ``end`` points, this may be expressed with:: If a movie's "peers" are described as movies released by the same studio in the same genre in the same year, this ``RowRange`` example annotates each movie -with the average rating of a movie's two prior and two following peers:: +with the average rating of a movie's two prior and two following peers: + +.. code-block:: pycon >>> from django.db.models import Avg, F, RowRange, Window >>> Movie.objects.annotate( @@ -929,7 +961,9 @@ If the database supports it, you can specify the start and end points based on values of an expression in the partition. If the ``released`` field of the ``Movie`` model stores the release month of each movies, this ``ValueRange`` example annotates each movie with the average rating of a movie's peers -released between twelve months before and twelve months after the each movie:: +released between twelve months before and twelve months after the each movie: + +.. code-block:: pycon >>> from django.db.models import Avg, F, ValueRange, Window >>> Movie.objects.annotate( @@ -1016,7 +1050,9 @@ calling the appropriate methods on the wrapped expression. .. method:: get_source_expressions() - Returns an ordered list of inner expressions. For example:: + Returns an ordered list of inner expressions. For example: + + .. code-block:: pycon >>> Sum(F('foo')).get_source_expressions() [F('foo')] @@ -1194,7 +1230,9 @@ to play nice with other query expressions:: def set_source_expressions(self, expressions): self.expressions = expressions -Let's see how it works:: +Let's see how it works: + +.. code-block:: pycon >>> from django.db.models import F, Value, CharField >>> qs = Company.objects.annotate( diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 8d75280a54..81f3013892 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -249,7 +249,9 @@ the ``.name`` and ``.value`` properties on the members. If you don't need to have the human-readable names translated, you can have them inferred from the member name (replacing underscores with spaces and using -title-case):: +title-case): + +.. code-block:: pycon >>> class Vehicle(models.TextChoices): ... CAR = 'C' @@ -274,7 +276,9 @@ Django provides an ``IntegerChoices`` class. For example:: It is also possible to make use of the `Enum Functional API <https://docs.python.org/3/library/enum.html#functional-api>`_ with the caveat -that labels are automatically generated as highlighted above:: +that labels are automatically generated as highlighted above: + +.. code-block:: pycon >>> MedalType = models.TextChoices('MedalType', 'GOLD SILVER BRONZE') >>> MedalType.choices @@ -1597,7 +1601,9 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in ``Artist`` can be deleted even if that implies deleting an ``Album`` which is referenced by a ``Song``, because ``Song`` also references - ``Artist`` itself through a cascading relationship. For example:: + ``Artist`` itself through a cascading relationship. For example: + + .. code-block:: pycon >>> artist_one = Artist.objects.create(name='artist one') >>> artist_two = Artist.objects.create(name='artist two') @@ -2025,7 +2031,9 @@ With the following example:: related_name='supervisor_of', ) -your resulting ``User`` model will have the following attributes:: +your resulting ``User`` model will have the following attributes: + +.. code-block:: pycon >>> user = User.objects.get(pk=1) >>> hasattr(user, 'myspecialuser') diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 9028788500..dc73267427 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -125,7 +125,9 @@ Refreshing objects from database ================================ If you delete a field from a model instance, accessing it again reloads the -value from the database:: +value from the database: + +.. code-block:: pycon >>> obj = MyModel.objects.first() >>> del obj.field @@ -435,7 +437,9 @@ Auto-incrementing primary keys If a model has an :class:`~django.db.models.AutoField` — an auto-incrementing primary key — then that auto-incremented value will be calculated and saved as -an attribute on your object the first time you call ``save()``:: +an attribute on your object the first time you call ``save()``: + +.. code-block:: pycon >>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') >>> b2.id # Returns None, because b2 doesn't have an ID yet. @@ -467,7 +471,9 @@ Explicitly specifying auto-primary-key values If a model has an :class:`~django.db.models.AutoField` but you want to define a new object's ID explicitly when saving, define it explicitly before saving, -rather than relying on the auto-assignment of the ID:: +rather than relying on the auto-assignment of the ID: + +.. code-block:: pycon >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') >>> b3.id # Returns 3. @@ -593,7 +599,9 @@ Updating attributes based on existing fields Sometimes you'll need to perform a simple arithmetic task on a field, such as incrementing or decrementing the current value. One way of achieving this is -doing the arithmetic in Python like:: +doing the arithmetic in Python like: + +.. code-block:: pycon >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') >>> product.number_sold += 1 @@ -608,7 +616,9 @@ the update relative to the original field value, rather than as an explicit assignment of a new value. Django provides :class:`F expressions <django.db.models.F>` for performing this kind of relative update. Using :class:`F expressions <django.db.models.F>`, the previous example is expressed -as:: +as: + +.. code-block:: pycon >>> from django.db.models import F >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') @@ -882,7 +892,7 @@ For example:: name = models.CharField(max_length=60) shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES) -:: +.. code-block:: pycon >>> p = Person(name="Fred Flintstone", shirt_size="L") >>> p.save() diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index a882fcb05a..4426e8bfcd 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -234,20 +234,26 @@ not be looking at your Django code. For example:: and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For example, assuming that a ``Question`` object has multiple related ``Answer`` objects, the list returned contains the primary keys of the related ``Answer`` - objects:: + objects: + + .. code-block:: pycon >>> question = Question.objects.get(id=1) >>> question.get_answer_order() [1, 2, 3] The order of a ``Question`` object's related ``Answer`` objects can be set by - passing in a list of ``Answer`` primary keys:: + passing in a list of ``Answer`` primary keys: + + .. code-block:: pycon >>> question.set_answer_order([3, 1, 2]) The related objects also get two methods, ``get_next_in_order()`` and ``get_previous_in_order()``, which can be used to access those objects in their - proper order. Assuming the ``Answer`` objects are ordered by ``id``:: + proper order. Assuming the ``Answer`` objects are ordered by ``id``: + + .. code-block:: pycon >>> answer = Answer.objects.get(id=2) >>> answer.get_next_in_order() diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 57c64e32cf..54797d363b 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -107,7 +107,9 @@ than the results that are currently in the database. If you only want to pickle the necessary information to recreate the ``QuerySet`` from the database at a later time, pickle the ``query`` attribute of the ``QuerySet``. You can then recreate the original ``QuerySet`` (without -any results loaded) using some code like this:: +any results loaded) using some code like this: + +.. code-block:: pycon >>> import pickle >>> query = pickle.loads(s) # Assuming 's' is the pickled string. @@ -122,7 +124,9 @@ described here. .. admonition:: Restrictions on ``QuerySet.values_list()`` If you recreate :meth:`QuerySet.values_list` using the pickled ``query`` - attribute, it will be converted to :meth:`QuerySet.values`:: + attribute, it will be converted to :meth:`QuerySet.values`: + + .. code-block:: pycon >>> import pickle >>> qs = Blog.objects.values_list('id', 'name') @@ -277,7 +281,9 @@ that reference a single field can be anonymous arguments. Everything else must be a keyword argument. For example, if you were manipulating a list of blogs, you may want -to determine how many entries have been made in each blog:: +to determine how many entries have been made in each blog: + +.. code-block:: pycon >>> from django.db.models import Count >>> q = Blog.objects.annotate(Count('entry')) @@ -290,7 +296,9 @@ to determine how many entries have been made in each blog:: The ``Blog`` model doesn't define an ``entry__count`` attribute by itself, but by using a keyword argument to specify the aggregate function, you can -control the name of the annotation:: +control the name of the annotation: + +.. code-block:: pycon >>> q = Blog.objects.annotate(number_of_entries=Count('entry')) # The number of entries on the first blog, using the name provided @@ -313,7 +321,9 @@ Not selecting the unused value removes redundant work from the database which should result in better performance. For example, if you want to find blogs with more than 5 entries, but are not -interested in the exact number of entries, you could do this:: +interested in the exact number of entries, you could do this: + +.. code-block:: pycon >>> from django.db.models import Count >>> blogs = Blog.objects.alias(entries=Count('entry')).filter(entries__gt=5) @@ -532,7 +542,9 @@ field names, the database will only compare the specified field names. value in column ``a``. If you don't specify an order, you'll get some arbitrary row. -Examples (those after the first will only work on PostgreSQL):: +Examples (those after the first will only work on PostgreSQL): + +.. code-block:: pycon >>> Author.objects.distinct() [...] @@ -579,7 +591,9 @@ Each of those dictionaries represents an object, with the keys corresponding to the attribute names of model objects. This example compares the dictionaries of ``values()`` with the normal model -objects:: +objects: + +.. code-block:: pycon # This list contains a Blog object. >>> Blog.objects.filter(name__startswith='Beatles') @@ -595,7 +609,9 @@ the fields, each dictionary will contain only the field keys/values for the fields you specify. If you don't specify the fields, each dictionary will contain a key and value for every field in the database table. -Example:: +Example: + +.. code-block:: pycon >>> Blog.objects.values() <QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]> @@ -603,14 +619,18 @@ Example:: <QuerySet [{'id': 1, 'name': 'Beatles Blog'}]> The ``values()`` method also takes optional keyword arguments, -``**expressions``, which are passed through to :meth:`annotate`:: +``**expressions``, which are passed through to :meth:`annotate`: + +.. code-block:: pycon >>> from django.db.models.functions import Lower >>> Blog.objects.values(lower_name=Lower('name')) <QuerySet [{'lower_name': 'beatles blog'}]> You can use built-in and :doc:`custom lookups </howto/custom-lookups>` in -ordering. For example:: +ordering. For example: + +.. code-block:: pycon >>> from django.db.models import CharField >>> from django.db.models.functions import Lower @@ -620,7 +640,9 @@ ordering. For example:: An aggregate within a ``values()`` clause is applied before other arguments within the same ``values()`` clause. If you need to group by another value, -add it to an earlier ``values()`` clause instead. For example:: +add it to an earlier ``values()`` clause instead. For example: + +.. code-block:: pycon >>> from django.db.models import Count >>> Blog.objects.values('entry__authors', entries=Count('entry')) @@ -639,7 +661,9 @@ A few subtleties that are worth mentioning: or ``foo_id`` and you will get back the same thing (the dictionary key will match the field name you passed in). - For example:: + For example: + + .. code-block:: pycon >>> Entry.objects.values() <QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]> @@ -666,7 +690,9 @@ A few subtleties that are worth mentioning: * Combining transforms and aggregates requires the use of two :meth:`annotate` calls, either explicitly or as keyword arguments to :meth:`values`. As above, if the transform has been registered on the relevant field type the first - :meth:`annotate` can be omitted, thus the following examples are equivalent:: + :meth:`annotate` can be omitted, thus the following examples are equivalent: + + .. code-block:: pycon >>> from django.db.models import CharField, Count >>> from django.db.models.functions import Lower @@ -698,7 +724,9 @@ but it doesn't really matter. This is your chance to really flaunt your individualism. You can also refer to fields on related models with reverse relations through -``OneToOneField``, ``ForeignKey`` and ``ManyToManyField`` attributes:: +``OneToOneField``, ``ForeignKey`` and ``ManyToManyField`` attributes: + +.. code-block:: pycon >>> Blog.objects.values('name', 'entry__headline') <QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'}, @@ -728,7 +756,9 @@ You can also refer to fields on related models with reverse relations through This is similar to ``values()`` except that instead of returning dictionaries, it returns tuples when iterated over. Each tuple contains the value from the respective field or expression passed into the ``values_list()`` call — so the -first item is the first field, etc. For example:: +first item is the first field, etc. For example: + +.. code-block:: pycon >>> Entry.objects.values_list('id', 'headline') <QuerySet [(1, 'First entry'), ...]> @@ -738,7 +768,9 @@ first item is the first field, etc. For example:: If you only pass in a single field, you can also pass in the ``flat`` parameter. If ``True``, this will mean the returned results are single values, -rather than one-tuples. An example should make the difference clearer:: +rather than one-tuples. An example should make the difference clearer: + +.. code-block:: pycon >>> Entry.objects.values_list('id').order_by('id') <QuerySet[(1,), (2,), (3,), ...]> @@ -749,7 +781,9 @@ rather than one-tuples. An example should make the difference clearer:: It is an error to pass in ``flat`` when there is more than one field. You can pass ``named=True`` to get results as a -:func:`~python:collections.namedtuple`:: +:func:`~python:collections.namedtuple`: + +.. code-block:: pycon >>> Entry.objects.values_list('id', 'headline', named=True) <QuerySet [Row(id=1, headline='First entry'), ...]> @@ -761,7 +795,9 @@ If you don't pass any values to ``values_list()``, it will return all the fields in the model, in the order they were declared. A common need is to get a specific field value of a certain model instance. To -achieve that, use ``values_list()`` followed by a ``get()`` call:: +achieve that, use ``values_list()`` followed by a ``get()`` call: + +.. code-block:: pycon >>> Entry.objects.values_list('headline', flat=True).get(pk=1) 'First entry' @@ -773,7 +809,9 @@ other multivalued relations (such as the one-to-many relation of a reverse foreign key) because the "one row, one object" assumption doesn't hold. For example, notice the behavior when querying across a -:class:`~django.db.models.ManyToManyField`:: +:class:`~django.db.models.ManyToManyField`: + +.. code-block:: pycon >>> Author.objects.values_list('name', 'entry__headline') <QuerySet [('Noam Chomsky', 'Impressions of Gaza'), @@ -785,7 +823,9 @@ Authors with multiple entries appear multiple times and authors without any entries have ``None`` for the entry headline. Similarly, when querying a reverse foreign key, ``None`` appears for entries -not having any author:: +not having any author: + +.. code-block:: pycon >>> Entry.objects.values_list('authors') <QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]> @@ -823,7 +863,9 @@ given ``type``. ``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or ``'DESC'``. This specifies how to order the results. -Examples:: +Examples: + +.. code-block:: pycon >>> Entry.objects.dates('pub_date', 'year') [datetime.date(2005, 1, 1)] @@ -899,7 +941,9 @@ Calling ``none()`` will create a queryset that never returns any objects and no query will be executed when accessing the results. A ``qs.none()`` queryset is an instance of ``EmptyQuerySet``. -Examples:: +Examples: + +.. code-block:: pycon >>> Entry.objects.none() <QuerySet []> @@ -941,7 +985,9 @@ of other models. Passing different models works as long as the ``SELECT`` list is the same in all ``QuerySet``\s (at least the types, the names don't matter as long as the types are in the same order). In such cases, you must use the column names from the first ``QuerySet`` in ``QuerySet`` methods applied to the -resulting ``QuerySet``. For example:: +resulting ``QuerySet``. For example: + +.. code-block:: pycon >>> qs1 = Author.objects.values_list('name') >>> qs2 = Entry.objects.values_list('headline') @@ -972,7 +1018,9 @@ See :meth:`union` for some restrictions. .. method:: difference(*other_qs) Uses SQL's ``EXCEPT`` operator to keep only elements present in the -``QuerySet`` but not in some other ``QuerySet``\s. For example:: +``QuerySet`` but not in some other ``QuerySet``\s. For example: + +.. code-block:: pycon >>> qs1.difference(qs2, qs3) @@ -1078,7 +1126,9 @@ specified. This is not recommended in most cases as it is likely to make the underlying query more complex, and return more data, than is actually needed. If you need to clear the list of related fields added by past calls of -``select_related`` on a ``QuerySet``, you can pass ``None`` as a parameter:: +``select_related`` on a ``QuerySet``, you can pass ``None`` as a parameter: + +.. code-block:: pycon >>> without_relations = queryset.select_related(None) @@ -1133,7 +1183,9 @@ For example, suppose you have these models:: ", ".join(topping.name for topping in self.toppings.all()), ) -and run:: +and run: + +.. code-block:: pycon >>> Pizza.objects.all() ["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"... @@ -1203,12 +1255,16 @@ fields. Suppose we have an additional model to the example above:: The following are all legal: +.. code-block:: pycon + >>> Restaurant.objects.prefetch_related('pizzas__toppings') This will prefetch all pizzas belonging to restaurants, and all toppings belonging to those pizzas. This will result in a total of 3 database queries - one for the restaurants, one for the pizzas, and one for the toppings. +.. code-block:: pycon + >>> Restaurant.objects.prefetch_related('best_pizza__toppings') This will fetch the best pizza and all the toppings for the best pizza for each @@ -1216,7 +1272,9 @@ restaurant. This will be done in 3 database queries - one for the restaurants, one for the 'best pizzas', and one for the toppings. The ``best_pizza`` relationship could also be fetched using ``select_related`` -to reduce the query count to 2:: +to reduce the query count to 2: + +.. code-block:: pycon >>> Restaurant.objects.select_related('best_pizza').prefetch_related('best_pizza__toppings') @@ -1330,7 +1388,9 @@ where prefetching with a custom ``QuerySet`` is useful: When using multiple databases, ``Prefetch`` will respect your choice of database. If the inner query does not specify a database, it will use the -database selected by the outer query. All of the following are valid:: +database selected by the outer query. All of the following are valid: + +.. code-block:: pycon >>> # Both inner and outer queries will use the 'replica' database >>> Restaurant.objects.prefetch_related('pizzas__toppings').using('replica') @@ -1398,14 +1458,18 @@ generated by a ``QuerySet``. that we can enhance the QuerySet API to allow removing ``extra()``. We are no longer improving or fixing bugs for this method. - For example, this use of ``extra()``:: + For example, this use of ``extra()``: + + .. code-block:: pycon >>> qs.extra( ... select={'val': "select col from sometable where othercol = %s"}, ... select_params=(someparam,), ... ) - is equivalent to:: + is equivalent to: + + .. code-block:: pycon >>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,))) @@ -1772,7 +1836,9 @@ evaluated against if you are using more than one database. The only argument this method takes is the alias of a database, as defined in :setting:`DATABASES`. -For example:: +For example: + +.. code-block:: pycon # queries the database with the 'default' alias. >>> Entry.objects.all() @@ -1840,7 +1906,9 @@ lock, that still allows creating rows that merely reference locked rows PostgreSQL documentation has more details about `row-level lock modes <https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-ROWS>`_. -You can't use ``select_for_update()`` on nullable relations:: +You can't use ``select_for_update()`` on nullable relations: + +.. code-block:: pycon >>> Person.objects.select_related('hometown').select_for_update() Traceback (most recent call last): @@ -1848,7 +1916,9 @@ You can't use ``select_for_update()`` on nullable relations:: django.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join To avoid that restriction, you can exclude null objects if you don't care about -them:: +them: + +.. code-block:: pycon >>> Person.objects.select_related('hometown').select_for_update().exclude(hometown=None) <QuerySet [<Person: ...)>, ...]> @@ -2199,7 +2269,9 @@ whenever a request to a page has a side effect on your data. For more, see chapters = models.ManyToManyField(Chapter) You can use ``get_or_create()`` through Book's chapters field, but it only - fetches inside the context of that book:: + fetches inside the context of that book: + + .. code-block:: pycon >>> book = Book.objects.create(title="Ulysses") >>> book.chapters.get_or_create(title="Telemachus") @@ -2292,7 +2364,9 @@ exists in the database, an :exc:`~django.db.IntegrityError` is raised. This method inserts the provided list of objects into the database in an efficient manner (generally only 1 query, no matter how many objects there -are), and returns created objects as a list, in the same order as provided:: +are), and returns created objects as a list, in the same order as provided: + +.. code-block:: pycon >>> objs = Entry.objects.bulk_create([ ... Entry(headline='This is a test'), @@ -2372,7 +2446,9 @@ support it). This method efficiently updates the given fields on the provided model instances, generally with one query, and returns the number of objects -updated:: +updated: + +.. code-block:: pycon >>> objs = [ ... Entry.objects.create(headline='Entry 1'), @@ -2465,7 +2541,9 @@ in the queryset are returned. ``field_name`` must be a unique field or a distinct field (if there's only one field specified in :meth:`distinct`). ``field_name`` defaults to the primary key. -Example:: +Example: + +.. code-block:: pycon >>> Blog.objects.in_bulk([1]) {1: <Blog: Beatles Blog>} @@ -2726,14 +2804,18 @@ aggregated. Complex aggregates cannot use anonymous arguments and must specify a keyword argument as an alias. For example, when you are working with blog entries, you may want to know the -number of authors that have contributed blog entries:: +number of authors that have contributed blog entries: + +.. code-block:: pycon >>> from django.db.models import Count >>> q = Blog.objects.aggregate(Count('entry')) {'entry__count': 16} By using a keyword argument to specify the aggregate function, you can -control the name of the aggregation value that is returned:: +control the name of the aggregation value that is returned: + +.. code-block:: pycon >>> q = Blog.objects.aggregate(number_of_entries=Count('entry')) {'number_of_entries': 16} @@ -2832,31 +2914,41 @@ the number of rows matched (which may not be equal to the number of rows updated if some rows already have the new value). For example, to turn comments off for all blog entries published in 2010, -you could do this:: +you could do this: + +.. code-block:: pycon >>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False) (This assumes your ``Entry`` model has fields ``pub_date`` and ``comments_on``.) You can update multiple fields — there's no limit on how many. For example, -here we update the ``comments_on`` and ``headline`` fields:: +here we update the ``comments_on`` and ``headline`` fields: + +.. code-block:: pycon >>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old') The ``update()`` method is applied instantly, and the only restriction on the :class:`.QuerySet` that is updated is that it can only update columns in the -model's main table, not on related models. You can't do this, for example:: +model's main table, not on related models. You can't do this, for example: + +.. code-block:: pycon >>> Entry.objects.update(blog__name='foo') # Won't work! -Filtering based on related fields is still possible, though:: +Filtering based on related fields is still possible, though: + +.. code-block:: pycon >>> Entry.objects.filter(blog__id=1).update(comments_on=True) You cannot call ``update()`` on a :class:`.QuerySet` that has had a slice taken or can otherwise no longer be filtered. -The ``update()`` method returns the number of affected rows:: +The ``update()`` method returns the number of affected rows: + +.. code-block:: pycon >>> Entry.objects.filter(id=64).update(comments_on=True) 1 @@ -2930,7 +3022,9 @@ The ``delete()`` is applied instantly. You cannot call ``delete()`` on a :class:`.QuerySet` that has had a slice taken or can otherwise no longer be filtered. -For example, to delete all the entries in a particular blog:: +For example, to delete all the entries in a particular blog: + +.. code-block:: pycon >>> b = Blog.objects.get(pk=1) @@ -2941,7 +3035,9 @@ For example, to delete all the entries in a particular blog:: By default, Django's :class:`~django.db.models.ForeignKey` emulates the SQL constraint ``ON DELETE CASCADE`` — in other words, any objects with foreign keys pointing at the objects to be deleted will be deleted along with them. -For example:: +For example: + +.. code-block:: pycon >>> blogs = Blog.objects.all() @@ -3000,7 +3096,9 @@ database would execute the query, including any indexes or joins that would be used. Knowing these details may help you improve the performance of slow queries. -For example, when using PostgreSQL:: +For example, when using PostgreSQL: + +.. code-block:: pycon >>> print(Blog.objects.filter(title='My Blog').explain()) Seq Scan on blog (cost=0.00..35.50 rows=10 width=12) @@ -3019,7 +3117,9 @@ default, which is usually text-based. PostgreSQL supports ``'TEXT'``, PostgreSQL's ``'TEXT'`` output and is used by default, if supported. Some databases accept flags that can return more information about the query. -Pass these flags as keyword arguments. For example, when using PostgreSQL:: +Pass these flags as keyword arguments. For example, when using PostgreSQL: + +.. code-block:: pycon >>> print(Blog.objects.filter(title='My Blog').explain(verbose=True, analyze=True)) Seq Scan on public.blog (cost=0.00..35.50 rows=10 width=12) (actual time=0.004..0.004 rows=10 loops=1) @@ -4044,7 +4144,9 @@ in code that receives a list of model instances as opposed to a ``QuerySet``; for example, when fetching models from a cache or instantiating them manually. Pass an iterable of model instances (must all be of the same class) and the -lookups or :class:`Prefetch` objects you want to prefetch for. For example:: +lookups or :class:`Prefetch` objects you want to prefetch for. For example: + +.. code-block:: pycon >>> from django.db.models import prefetch_related_objects >>> restaurants = fetch_top_restaurants_from_cache() # A list of Restaurants @@ -4073,7 +4175,9 @@ relationship but on the annotation name (``pizzas_vegetarian`` in example below). For example, to find restaurants that have vegetarian pizzas with -``'mozzarella'`` in the name:: +``'mozzarella'`` in the name: + +.. code-block:: pycon >>> from django.db.models import FilteredRelation, Q >>> Restaurant.objects.annotate( @@ -4082,7 +4186,9 @@ For example, to find restaurants that have vegetarian pizzas with ... ), ... ).filter(pizzas_vegetarian__name__icontains='mozzarella') -If there are a large number of pizzas, this queryset performs better than:: +If there are a large number of pizzas, this queryset performs better than: + +.. code-block:: pycon >>> Restaurant.objects.filter( ... pizzas__vegetarian=True, diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index 1b1aad7425..d56b0fb33e 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -43,7 +43,9 @@ Related objects reference Adds the specified model objects to the related object set. - Example:: + Example: + + .. code-block:: pycon >>> b = Blog.objects.get(id=1) >>> e = Entry.objects.get(id=234) @@ -88,7 +90,9 @@ Related objects reference *Asynchronous version*: ``acreate`` Creates a new object, saves it and puts it in the related object set. - Returns the newly created object:: + Returns the newly created object: + + .. code-block:: pycon >>> b = Blog.objects.get(id=1) >>> e = b.entry_set.create( @@ -99,7 +103,9 @@ Related objects reference # No need to call e.save() at this point -- it's already been saved. - This is equivalent to (but simpler than):: + This is equivalent to (but simpler than): + + .. code-block:: pycon >>> b = Blog.objects.get(id=1) >>> e = Entry( @@ -129,7 +135,9 @@ Related objects reference *Asynchronous version*: ``aremove`` - Removes the specified model objects from the related object set:: + Removes the specified model objects from the related object set: + + .. code-block:: pycon >>> b = Blog.objects.get(id=1) >>> e = Entry.objects.get(id=234) @@ -176,7 +184,9 @@ Related objects reference *Asynchronous version*: ``aclear`` - Removes all objects from the related object set:: + Removes all objects from the related object set: + + .. code-block:: pycon >>> b = Blog.objects.get(id=1) >>> b.entry_set.clear() @@ -200,7 +210,9 @@ Related objects reference *Asynchronous version*: ``aset`` - Replace the set of related objects:: + Replace the set of related objects: + + .. code-block:: pycon >>> new_list = [obj1, obj2, obj3] >>> e.related_set.set(new_list) diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index ebcd9ee523..63fa9be9b5 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -179,7 +179,9 @@ All attributes should be considered read-only, unless stated otherwise. the request. The name of each header is stylized with title-casing (e.g. ``User-Agent``) - when it's displayed. You can access headers case-insensitively:: + when it's displayed. You can access headers case-insensitively: + + .. code-block:: pycon >>> request.headers {'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6', ...} @@ -200,7 +202,9 @@ All attributes should be considered read-only, unless stated otherwise. Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) For use in, for example, Django templates, headers can also be looked up - using underscores in place of hyphens:: + using underscores in place of hyphens: + + .. code-block:: html+django {{ request.headers.user_agent }} @@ -381,7 +385,9 @@ Methods attached to the cookie value to ensure the cookie is not older than ``max_age`` seconds. - For example:: + For example: + + .. code-block:: pycon >>> request.get_signed_cookie('name') 'Tony' @@ -411,7 +417,9 @@ Methods .. method:: HttpRequest.accepts(mime_type) Returns ``True`` if the request ``Accept`` header matches the ``mime_type`` - argument:: + argument: + + .. code-block:: pycon >>> request.accepts('text/html') True @@ -492,7 +500,9 @@ a subclass of dictionary. Exceptions are outlined here: .. classmethod:: QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None) Creates a new ``QueryDict`` with keys from ``iterable`` and each value - equal to ``value``. For example:: + equal to ``value``. For example: + + .. code-block:: pycon >>> QueryDict.fromkeys(['a', 'a', 'b'], value='val') <QueryDict: {'a': ['val', 'val'], 'b': ['val']}> @@ -530,7 +540,9 @@ a subclass of dictionary. Exceptions are outlined here: Takes either a ``QueryDict`` or a dictionary. Like :meth:`dict.update`, except it *appends* to the current dictionary items rather than replacing - them. For example:: + them. For example: + + .. code-block:: pycon >>> q = QueryDict('a=1', mutable=True) >>> q.update({'a': '2'}) @@ -543,7 +555,9 @@ a subclass of dictionary. Exceptions are outlined here: Like :meth:`dict.items`, except this uses the same last-value logic as :meth:`__getitem__` and returns an iterator object instead of a view object. - For example:: + For example: + + .. code-block:: pycon >>> q = QueryDict('a=1&a=2&a=3') >>> list(q.items()) @@ -553,7 +567,9 @@ a subclass of dictionary. Exceptions are outlined here: Like :meth:`dict.values`, except this uses the same last-value logic as :meth:`__getitem__` and returns an iterator instead of a view object. For - example:: + example: + + .. code-block:: pycon >>> q = QueryDict('a=1&a=2&a=3') >>> list(q.values()) @@ -588,7 +604,9 @@ In addition, ``QueryDict`` has the following methods: .. method:: QueryDict.lists() Like :meth:`items()`, except it includes all values, as a list, for each - member of the dictionary. For example:: + member of the dictionary. For example: + + .. code-block:: pycon >>> q = QueryDict('a=1&a=2&a=3') >>> q.lists() @@ -597,7 +615,9 @@ In addition, ``QueryDict`` has the following methods: .. method:: QueryDict.pop(key) Returns a list of values for the given key and removes them from the - dictionary. Raises ``KeyError`` if the key does not exist. For example:: + dictionary. Raises ``KeyError`` if the key does not exist. For example: + + .. code-block:: pycon >>> q = QueryDict('a=1&a=2&a=3', mutable=True) >>> q.pop('a') @@ -608,7 +628,9 @@ In addition, ``QueryDict`` has the following methods: Removes an arbitrary member of the dictionary (since there's no concept of ordering), and returns a two value tuple containing the key and a list of all values for the key. Raises ``KeyError`` when called on an empty - dictionary. For example:: + dictionary. For example: + + .. code-block:: pycon >>> q = QueryDict('a=1&a=2&a=3', mutable=True) >>> q.popitem() @@ -618,7 +640,9 @@ In addition, ``QueryDict`` has the following methods: Returns a ``dict`` representation of ``QueryDict``. For every (key, list) pair in ``QueryDict``, ``dict`` will have (key, item), where item is one - element of the list, using the same logic as :meth:`QueryDict.__getitem__`:: + element of the list, using the same logic as :meth:`QueryDict.__getitem__`: + + .. code-block:: pycon >>> q = QueryDict('a=1&a=3&a=5') >>> q.dict() @@ -626,14 +650,18 @@ In addition, ``QueryDict`` has the following methods: .. method:: QueryDict.urlencode(safe=None) - Returns a string of the data in query string format. For example:: + Returns a string of the data in query string format. For example: + + .. code-block:: pycon >>> q = QueryDict('a=2&b=3&b=5') >>> q.urlencode() 'a=2&b=3&b=5' Use the ``safe`` parameter to pass characters which don't require encoding. - For example:: + For example: + + .. code-block:: pycon >>> q = QueryDict(mutable=True) >>> q['next'] = '/a&b/' @@ -659,7 +687,9 @@ Passing strings ~~~~~~~~~~~~~~~ Typical usage is to pass the contents of the page, as a string, bytestring, -or :class:`memoryview`, to the :class:`HttpResponse` constructor:: +or :class:`memoryview`, to the :class:`HttpResponse` constructor: + +.. code-block:: pycon >>> from django.http import HttpResponse >>> response = HttpResponse("Here's the text of the web page.") @@ -668,7 +698,9 @@ or :class:`memoryview`, to the :class:`HttpResponse` constructor:: >>> response = HttpResponse(memoryview(b'Memoryview as well.')) But if you want to add content incrementally, you can use ``response`` as a -file-like object:: +file-like object: + +.. code-block:: pycon >>> response = HttpResponse() >>> response.write("<p>Here's the text of the web page.</p>") @@ -691,13 +723,17 @@ Setting header fields ~~~~~~~~~~~~~~~~~~~~~ To set or remove a header field in your response, use -:attr:`HttpResponse.headers`:: +:attr:`HttpResponse.headers`: + +.. code-block:: pycon >>> response = HttpResponse() >>> response.headers['Age'] = 120 >>> del response.headers['Age'] -You can also manipulate headers by treating your response like a dictionary:: +You can also manipulate headers by treating your response like a dictionary: + +.. code-block:: pycon >>> response = HttpResponse() >>> response['Age'] = 120 @@ -709,7 +745,9 @@ by ``HttpResponse``. When using this interface, unlike a dictionary, ``del`` doesn't raise ``KeyError`` if the header field doesn't exist. -You can also set headers on instantiation:: +You can also set headers on instantiation: + +.. code-block:: pycon >>> response = HttpResponse(headers={'Age': 120}) @@ -728,7 +766,9 @@ Telling the browser to treat the response as a file attachment To tell the browser to treat the response as a file attachment, set the ``Content-Type`` and ``Content-Disposition`` headers. For example, this is how -you might return a Microsoft Excel spreadsheet:: +you might return a Microsoft Excel spreadsheet: + +.. code-block:: pycon >>> response = HttpResponse(my_data, headers={ ... 'Content-Type': 'application/vnd.ms-excel', @@ -1030,7 +1070,9 @@ Custom response classes ~~~~~~~~~~~~~~~~~~~~~~~ If you find yourself needing a response class that Django doesn't provide, you -can create it with the help of :py:class:`http.HTTPStatus`. For example:: +can create it with the help of :py:class:`http.HTTPStatus`. For example: + +.. code-block:: pycon from http import HTTPStatus from django.http import HttpResponse @@ -1069,7 +1111,9 @@ can create it with the help of :py:class:`http.HTTPStatus`. For example:: Usage ----- -Typical usage could look like:: +Typical usage could look like: + +.. code-block:: pycon >>> from django.http import JsonResponse >>> response = JsonResponse({'foo': 'bar'}) @@ -1080,7 +1124,9 @@ Serializing non-dictionary objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to serialize objects other than ``dict`` you must set the ``safe`` -parameter to ``False``:: +parameter to ``False``: + +.. code-block:: pycon >>> response = JsonResponse([1, 2, 3], safe=False) @@ -1104,7 +1150,9 @@ Changing the default JSON encoder ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you need to use a different JSON encoder class you can pass the ``encoder`` -parameter to the constructor method:: +parameter to the constructor method: + +.. code-block:: pycon >>> response = JsonResponse(data, encoder=MyJSONEncoder) @@ -1249,7 +1297,9 @@ Attributes when they can be guessed from contents of ``open_file``. ``FileResponse`` accepts any file-like object with binary content, for example -a file open in binary mode like so:: +a file open in binary mode like so: + +.. code-block:: pycon >>> from django.http import FileResponse >>> response = FileResponse(open('myfile.png', 'rb')) diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 315438fee8..45823f98f9 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1724,7 +1724,9 @@ formats defined in this file. For example, if :setting:`FORMAT_MODULE_PATH` is set to ``mysite.formats``, and current language is ``en`` (English), Django will expect a directory tree -like:: +like: + +.. code-block:: text mysite/ formats/ diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index 1d21e2debe..13ce2cc3f4 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -327,7 +327,9 @@ If we connected a handler like this:: m2m_changed.connect(toppings_changed, sender=Pizza.toppings.through) -and then did something like this:: +and then did something like this: + +.. code-block:: pycon >>> p = Pizza.objects.create(...) >>> t = Topping.objects.create(...) @@ -357,7 +359,9 @@ Argument Value ``using`` ``"default"`` (since the default router sends writes here) ============== ============================================================ -And if we would then do something like this:: +And if we would then do something like this: + +.. code-block:: pycon >>> t.pizza_set.remove(p) diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index abbc12742b..059d651957 100644 --- a/docs/ref/template-response.txt +++ b/docs/ref/template-response.txt @@ -218,7 +218,9 @@ subsequent rendering calls do not change the response content. However, when ``response.content`` is explicitly assigned, the change is always applied. If you want to force the content to be re-rendered, you can reevaluate the rendered content, and assign -the content of the response manually:: +the content of the response manually: + +.. code-block:: pycon # Set up a rendered TemplateResponse >>> from django.template.response import TemplateResponse diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 2e0adb0046..c628a8c87a 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -216,7 +216,9 @@ different contexts. .. method:: Template.render(context) Call the :class:`Template` object's ``render()`` method with a - :class:`Context` to "fill" the template:: + :class:`Context` to "fill" the template: + + .. code-block:: pycon >>> from django.template import Context, Template >>> template = Template("My name is {{ my_name }}.") @@ -248,7 +250,9 @@ interpreted as a literal string and not using the value of the variable "bar", if one exists in the template context. The template system uses the first lookup type that works. It's short-circuit -logic. Here are a few examples:: +logic. Here are a few examples: + +.. code-block:: pycon >>> from django.template import Context, Template >>> t = Template("My name is {{ person.first_name }}.") @@ -269,7 +273,9 @@ logic. Here are a few examples:: "The first stooge in the list is Larry." If any part of the variable is callable, the template system will try calling -it. Example:: +it. Example: + +.. code-block:: pycon >>> class PersonClass2: ... def name(self): @@ -287,7 +293,9 @@ straight lookups. Here are some things to keep in mind: *does* have a ``silent_variable_failure`` attribute whose value is ``True``, the variable will render as the value of the engine's ``string_if_invalid`` configuration option (an empty string, by default). - Example:: + Example: + + .. code-block:: pycon >>> t = Template("My name is {{ person.first_name }}.") >>> class PersonClass3: @@ -325,9 +333,11 @@ straight lookups. Here are some things to keep in mind: A good example is the :meth:`~django.db.models.Model.delete` method on each Django model object. The template system shouldn't be allowed to do - something like this:: + something like this: + + .. code-block:: html+django - I will now delete this valuable data. {{ data.delete }} + I will now delete this valuable data. {{ data.delete }} To prevent this, set an ``alters_data`` attribute on the callable variable. The template system won't call a variable if it has @@ -400,14 +410,18 @@ A similar issue exists if you want to include these sequences in template filter or tag arguments. For example, when parsing a block tag, Django's template parser looks for the first occurrence of ``%}`` after a ``{%``. This prevents the use of ``"%}"`` as a string literal. For example, a ``TemplateSyntaxError`` -will be raised for the following expressions:: +will be raised for the following expressions: + +.. code-block:: html+django {% include "template.html" tvar="Some string literal with %} in it." %} {% with tvar="Some string literal with %} in it." %}{% endwith %} The same issue can be triggered by using a reserved sequence in filter -arguments:: +arguments: + +.. code-block:: html+django {{ some.variable|default:"}}" }} @@ -422,7 +436,9 @@ Playing with ``Context`` objects Most of the time, you'll instantiate :class:`Context` objects by passing in a fully-populated dictionary to ``Context()``. But you can add and delete items from a ``Context`` object once it's been instantiated, too, using standard -dictionary syntax:: +dictionary syntax: + +.. code-block:: pycon >>> from django.template import Context >>> c = Context({"foo": "bar"}) @@ -453,7 +469,9 @@ dictionary syntax:: A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it. If you ``pop()`` too much, it'll raise -``django.template.ContextPopException``:: +``django.template.ContextPopException``: + +.. code-block:: pycon >>> c = Context() >>> c['foo'] = 'first level' diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 5804f455bd..99a7447e91 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -12,8 +12,6 @@ documentation for any custom tags or filters installed. Built-in tag reference ====================== -.. highlight:: html+django - .. templatetag:: autoescape ``autoescape`` @@ -32,7 +30,9 @@ The only exceptions are variables that are already marked as "safe" from escaping, either by the code that populated the variable, or because it has had the :tfilter:`safe` or :tfilter:`escape` filters applied. -Sample usage:: +Sample usage: + +.. code-block:: html+django {% autoescape on %} {{ body }} @@ -55,7 +55,9 @@ Ignores everything between ``{% comment %}`` and ``{% endcomment %}``. An optional note may be inserted in the first tag. For example, this is useful when commenting out code for documenting why the code was disabled. -Sample usage:: +Sample usage: + +.. code-block:: html+django <p>Rendered text with {{ pub_date|date:"c" }}</p> {% comment "Optional note" %} @@ -82,7 +84,9 @@ argument is produced on the first encounter, the second argument on the second encounter, and so forth. Once all arguments are exhausted, the tag cycles to the first argument and produces it again. -This tag is particularly useful in a loop:: +This tag is particularly useful in a loop: + +.. code-block:: html+django {% for o in some_list %} <tr class="{% cycle 'row1' 'row2' %}"> @@ -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 %} <tr class="{% cycle rowvalue1 rowvalue2 %}"> @@ -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 %} <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}"> @@ -113,7 +121,9 @@ with:: </tr> {% endfor %} -You can mix variables and strings:: +You can mix variables and strings: + +.. code-block:: html+django {% for o in some_list %} <tr class="{% cycle 'row1' rowvalue2 'row3' %}"> @@ -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 <tr> <td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td> @@ -142,7 +156,9 @@ variable. So, the following template:: <td class="{{ rowcolors }}">...</td> </tr> -would output:: +would output: + +.. code-block:: html+django <tr> <td class="row1">...</td> @@ -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 "<strong>fallback value</strong>" %} {% 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 "<strong>fallback value</strong>"|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 <ul> {% 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 <ul> {% for athlete in athlete_list %} @@ -378,7 +422,9 @@ displayed if the given array is empty or could not be found:: </ul> The above is equivalent to -- but shorter, cleaner, and possibly faster -than -- the following:: +than -- the following: + +.. code-block:: html+django <ul> {% 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 <h1>Archive for {{ year }}</h1> @@ -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 %} <div style="background-color: @@ -670,7 +754,9 @@ Loads a template and renders it with the current context. This is a way of The template name can either be a variable or a hard-coded (quoted) string, in either single or double quotes. -This example includes the contents of the template ``"foo/bar.html"``:: +This example includes the contents of the template ``"foo/bar.html"``: + +.. code-block:: html+django {% include "foo/bar.html" %} @@ -679,7 +765,9 @@ A string argument may also be a relative path starting with ``./`` or ``../`` as described in the :ttag:`extends` tag. This example includes the contents of the template whose name is contained in -the variable ``template_name``:: +the variable ``template_name``: + +.. code-block:: html+django {% include template_name %} @@ -696,21 +784,29 @@ includes it. This example produces the output ``"Hello, John!"``: * Context: variable ``person`` is set to ``"John"`` and variable ``greeting`` is set to ``"Hello"``. -* Template:: +* Template: + + .. code-block:: html+django {% include "name_snippet.html" %} -* The ``name_snippet.html`` template:: +* The ``name_snippet.html`` template: + + .. code-block:: html+django {{ greeting }}, {{ person|default:"friend" }}! -You can pass additional context to the template using keyword arguments:: +You can pass additional context to the template using keyword arguments: + +.. code-block:: html+django {% include "name_snippet.html" with person="Jane" greeting="Hello" %} If you want to render the context only with the variables provided (or even no variables at all), use the ``only`` option. No other variables are -available to the included template:: +available to the included template: + +.. code-block:: html+django {% include "name_snippet.html" with greeting="Hi" only %} @@ -735,13 +831,17 @@ Loads a custom template tag set. For example, the following template would load all the tags and filters registered in ``somelibrary`` and ``otherlibrary`` located in package -``package``:: +``package``: + +.. code-block:: html+django {% load somelibrary package.otherlibrary %} You can also selectively load individual filters or tags from a library, using the ``from`` argument. In this example, the template tags/filters named ``foo`` -and ``bar`` will be loaded from ``somelibrary``:: +and ``bar`` will be loaded from ``somelibrary``: + +.. code-block:: html+django {% load foo bar from somelibrary %} @@ -756,7 +856,9 @@ more information. Displays random "lorem ipsum" Latin text. This is useful for providing sample data in templates. -Usage:: +Usage: + +.. code-block:: html+django {% lorem [count] [method] [random] %} @@ -791,14 +893,18 @@ Displays the current date and/or time, using a format according to the given string. Such string can contain format specifiers characters as described in the :tfilter:`date` filter section. -Example:: +Example: + +.. code-block:: html+django It is {% now "jS F Y H:i" %} Note that you can backslash-escape a format string if you want to use the "raw" value. In this example, both "o" and "f" are backslash-escaped, because otherwise each is a format string that displays the year and the time, -respectively:: +respectively: + +.. code-block:: html+django It is the {% now "jS \o\f F" %} @@ -810,13 +916,17 @@ This would display as "It is the 4th of September". :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`SHORT_DATE_FORMAT` or :setting:`SHORT_DATETIME_FORMAT`. The predefined formats may vary depending on the current locale and - if :doc:`/topics/i18n/formatting` is enabled, e.g.:: + if :doc:`/topics/i18n/formatting` is enabled, e.g.: + + .. code-block:: html+django It is {% now "SHORT_DATETIME_FORMAT" %} You can also use the syntax ``{% now "Y" as current_year %}`` to store the output (as a string) inside a variable. This is useful if you want to use -``{% now %}`` inside a template tag like :ttag:`blocktranslate` for example:: +``{% now %}`` inside a template tag like :ttag:`blocktranslate` for example: + +.. code-block:: html+django {% now "Y" as current_year %} {% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %} @@ -860,7 +970,9 @@ like this: * Tokyo: 33,000,000 You can use the ``{% regroup %}`` tag to group the list of cities by country. -The following snippet of template code would accomplish this:: +The following snippet of template code would accomplish this: + +.. code-block:: html+django {% regroup cities by country as country_list %} @@ -891,7 +1003,9 @@ attribute and calling the result ``country_list``. with country='India'). Because ``{% regroup %}`` produces :py:func:`~collections.namedtuple` objects, -you can also write the previous example as:: +you can also write the previous example as: + +.. code-block:: html+django {% regroup cities by country as country_list %} @@ -951,7 +1065,9 @@ The easiest solution to this gotcha is to make sure in your view code that the data is ordered according to how you want to display it. Another solution is to sort the data in the template using the -:tfilter:`dictsort` filter, if your data is in a list of dictionaries:: +:tfilter:`dictsort` filter, if your data is in a list of dictionaries: + +.. code-block:: html+django {% regroup cities|dictsort:"country" by country as country_list %} @@ -961,14 +1077,18 @@ Grouping on other properties Any valid template lookup is a legal grouping attribute for the regroup tag, including methods, attributes, dictionary keys and list items. For example, if the "country" field is a foreign key to a class with -an attribute "description," you could use:: +an attribute "description," you could use: + +.. code-block:: html+django {% regroup cities by country.description as country_list %} Or, if ``country`` is a field with ``choices``, it will have a :meth:`~django.db.models.Model.get_FOO_display` method available as an attribute, allowing you to group on the display string rather than the -``choices`` key:: +``choices`` key: + +.. code-block:: html+django {% regroup cities by get_country_display as country_list %} @@ -984,7 +1104,9 @@ Resets a previous `cycle`_ so that it restarts from its first item at its next encounter. Without arguments, ``{% resetcycle %}`` will reset the last ``{% cycle %}`` defined in the template. -Example usage:: +Example usage: + +.. code-block:: html+django {% for coach in coach_list %} <h1>{{ coach.name }}</h1> @@ -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 %} <p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}"> @@ -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 %} <p> @@ -1040,12 +1166,16 @@ Example usage:: </p> {% endspaceless %} -This example would return this HTML:: +This example would return this HTML: + +.. code-block:: html+django <p><a href="foo/">Foo</a></p> 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 %} <strong> @@ -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 <naming-url-patterns>`. 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 %} <a href="{{ the_url }}">Link to optional stuff</a> {% 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 <img src="bar.png" alt="Bar" height="10" width="{% widthratio this_value max_value max_width %}"> @@ -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 ``<p>`` 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 ``<script>`` tag. -For example:: +For example: + +.. code-block:: html+django {{ value|json_script:"hello-data" }} @@ -1878,7 +2086,9 @@ executable code. Returns the last item in a list. -For example:: +For example: + +.. code-block:: html+django {{ value|last }} @@ -1892,7 +2102,9 @@ string ``"d"``. Returns the length of the value. This works for both strings and lists. -For example:: +For example: + +.. code-block:: html+django {{ value|length }} @@ -1910,7 +2122,9 @@ The filter returns ``0`` for an undefined variable. Returns ``True`` if the value's length is the argument, or ``False`` otherwise. -For example:: +For example: + +.. code-block:: html+django {{ value|length_is:"4" }} @@ -1926,7 +2140,9 @@ Replaces line breaks in plain text with appropriate HTML; a single newline becomes an HTML line break (``<br>``) and a new line followed by a blank line becomes a paragraph break (``</p>``). -For example:: +For example: + +.. code-block:: html+django {{ value|linebreaks }} @@ -1941,7 +2157,9 @@ slug</p>``. Converts all newlines in a piece of plain text to HTML line breaks (``<br>``). -For example:: +For example: + +.. code-block:: html+django {{ value|linebreaksbr }} @@ -1955,17 +2173,23 @@ slug``. Displays text with line numbers. -For example:: +For example: + +.. code-block:: html+django {{ value|linenumbers }} -If ``value`` is:: +If ``value`` is: + +.. code-block:: html+django one two three -the output will be:: +the output will be: + +.. code-block:: html+django 1. one 2. two @@ -1980,7 +2204,9 @@ Left-aligns the value in a field of a given width. **Argument:** field size -For example:: +For example: + +.. code-block:: html+django "{{ value|ljust:"10" }}" @@ -1993,7 +2219,9 @@ If ``value`` is ``Django``, the output will be ``"Django "``. Converts a string into all lowercase. -For example:: +For example: + +.. code-block:: html+django {{ value|lower }} @@ -2008,7 +2236,9 @@ If ``value`` is ``Totally LOVING this Album!``, the output will be Returns the value turned into a list. For a string, it's a list of characters. For an integer, the argument is cast to a string before creating a list. -For example:: +For example: + +.. code-block:: html+django {{ value|make_list }} @@ -2027,7 +2257,9 @@ equivalent. The input doesn't have to be a valid phone number. This will happily convert any string. -For example:: +For example: + +.. code-block:: html+django {{ value|phone2numeric }} @@ -2041,7 +2273,9 @@ If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``. Returns a plural suffix if the value is not ``1``, ``'1'``, or an object of length 1. By default, this suffix is ``'s'``. -Example:: +Example: + +.. code-block:: html+django You have {{ num_messages }} message{{ num_messages|pluralize }}. @@ -2051,14 +2285,18 @@ If ``num_messages`` is ``2`` the output will be ``You have 2 messages.`` For words that require a suffix other than ``'s'``, you can provide an alternate suffix as a parameter to the filter. -Example:: +Example: + +.. code-block:: html+django You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}. For words that don't pluralize by simple suffix, you can specify both a singular and plural suffix, separated by a comma. -Example:: +Example: + +.. code-block:: html+django You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}. @@ -2078,7 +2316,9 @@ A wrapper around :func:`pprint.pprint` -- for debugging, really. Returns a random item from the given list. -For example:: +For example: + +.. code-block:: html+django {{ value|random }} @@ -2093,7 +2333,9 @@ Right-aligns the value in a field of a given width. **Argument:** field size -For example:: +For example: + +.. code-block:: html+django "{{ value|rjust:"10" }}" @@ -2111,7 +2353,9 @@ autoescaping is off, this filter has no effect. If you are chaining filters, a filter applied after ``safe`` can make the contents unsafe again. For example, the following code - prints the variable as is, unescaped:: + prints the variable as is, unescaped: + + .. code-block:: html+django {{ var|safe|escape }} @@ -2122,7 +2366,9 @@ autoescaping is off, this filter has no effect. Applies the :tfilter:`safe` filter to each element of a sequence. Useful in conjunction with other filters that operate on sequences, such as -:tfilter:`join`. For example:: +:tfilter:`join`. For example: + +.. code-block:: html+django {{ some_list|safeseq|join:", " }} @@ -2141,7 +2387,9 @@ Uses the same syntax as Python's list slicing. See https://diveinto.org/python3/native-datatypes.html#slicinglists for an introduction. -Example:: +Example: + +.. code-block:: html+django {{ some_list|slice:":2" }} @@ -2156,7 +2404,9 @@ Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't alphanumerics, underscores, or hyphens. Converts to lowercase. Also strips leading and trailing whitespace. -For example:: +For example: + +.. code-block:: html+django {{ value|slugify }} @@ -2171,7 +2421,9 @@ Formats the variable according to the argument, a string formatting specifier. This specifier uses the :ref:`old-string-formatting` syntax, with the exception that the leading "%" is dropped. -For example:: +For example: + +.. code-block:: html+django {{ value|stringformat:"E" }} @@ -2184,7 +2436,9 @@ If ``value`` is ``10``, the output will be ``1.000000E+01``. Makes all possible efforts to strip all [X]HTML tags. -For example:: +For example: + +.. code-block:: html+django {{ value|striptags }} @@ -2212,7 +2466,9 @@ Given format can be the predefined one :setting:`TIME_FORMAT`, or a custom format, same as the :tfilter:`date` filter. Note that the predefined format is locale-dependent. -For example:: +For example: + +.. code-block:: html+django {{ value|time:"H:i" }} @@ -2222,7 +2478,9 @@ the string ``"01:23"``. Note that you can backslash-escape a format string if you want to use the "raw" value. In this example, both "h" and "m" are backslash-escaped, because otherwise each is a format string that displays the hour and the month, -respectively:: +respectively: + +.. code-block:: html+django {{ value|time:"H\h i\m" }} @@ -2231,7 +2489,9 @@ This would display as "01h 23m". Another example: Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, -for example, ``"de"``, then for:: +for example, ``"de"``, then for: + +.. code-block:: html+django {{ value|time:"TIME_FORMAT" }} @@ -2250,11 +2510,15 @@ accept the timezone-related :ref:`format specifiers <date-and-time-formatting-specifiers>` ``'e'``, ``'O'`` , ``'T'`` and ``'Z'``. When used without a format string, the ``TIME_FORMAT`` format specifier is -used:: +used: + +.. code-block:: html+django {{ value|time }} -is the same as:: +is the same as: + +.. code-block:: html+django {{ value|time:"TIME_FORMAT" }} @@ -2269,7 +2533,9 @@ Takes an optional argument that is a variable containing the date to use as the comparison point (without the argument, the comparison point is *now*). For example, if ``blog_date`` is a date instance representing midnight on 1 June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006, -then the following would return "8 hours":: +then the following would return "8 hours": + +.. code-block:: html+django {{ blog_date|timesince:comment_date }} @@ -2290,7 +2556,9 @@ given date or datetime. For example, if today is 1 June 2006 and Takes an optional argument that is a variable containing the date to use as the comparison point (instead of *now*). If ``from_date`` contains 22 June -2006, then the following will return "1 week":: +2006, then the following will return "1 week": + +.. code-block:: html+django {{ conference_date|timeuntil:from_date }} @@ -2308,7 +2576,9 @@ Converts a string into titlecase by making words start with an uppercase character and the remaining characters lowercase. This tag makes no effort to keep "trivial words" in lowercase. -For example:: +For example: + +.. code-block:: html+django {{ value|title }} @@ -2324,7 +2594,9 @@ Truncated strings will end with a translatable ellipsis character ("…"). **Argument:** Number of characters to truncate to -For example:: +For example: + +.. code-block:: html+django {{ value|truncatechars:7 }} @@ -2339,7 +2611,9 @@ Similar to :tfilter:`truncatechars`, except that it is aware of HTML tags. Any tags that are opened in the string and not closed before the truncation point are closed immediately after the truncation. -For example:: +For example: + +.. code-block:: html+django {{ value|truncatechars_html:7 }} @@ -2357,7 +2631,9 @@ Truncates a string after a certain number of words. **Argument:** Number of words to truncate after -For example:: +For example: + +.. code-block:: html+django {{ value|truncatewords:2 }} @@ -2377,7 +2653,9 @@ are closed immediately after the truncation. This is less efficient than :tfilter:`truncatewords`, so should only be used when it is being passed HTML text. -For example:: +For example: + +.. code-block:: html+django {{ value|truncatewords_html:2 }} @@ -2396,7 +2674,9 @@ WITHOUT opening and closing ``<ul>`` tags. The list is assumed to be in the proper format. For example, if ``var`` contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then -``{{ var|unordered_list }}`` would return:: +``{{ var|unordered_list }}`` would return: + +.. code-block:: html+django <li>States <ul> @@ -2417,7 +2697,9 @@ contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then Converts a string into all uppercase. -For example:: +For example: + +.. code-block:: html+django {{ value|upper }} @@ -2430,7 +2712,9 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``. Escapes a value for use in a URL. -For example:: +For example: + +.. code-block:: html+django {{ value|urlencode }} @@ -2441,7 +2725,9 @@ An optional argument containing the characters which should not be escaped can be provided. If not provided, the '/' character is assumed safe. An empty string can be -provided when *all* characters should be escaped. For example:: +provided when *all* characters should be escaped. For example: + +.. code-block:: html+django {{ value|urlencode:"" }} @@ -2469,7 +2755,9 @@ punctuation (opening parens), and ``urlize`` will still do the right thing. Links generated by ``urlize`` have a ``rel="nofollow"`` attribute added to them. -For example:: +For example: + +.. code-block:: html+django {{ value|urlize }} @@ -2504,7 +2792,9 @@ truncates URLs longer than the given character limit. **Argument:** Number of characters that link text should be truncated to, including the ellipsis that's added if truncation is necessary. -For example:: +For example: + +.. code-block:: html+django {{ value|urlizetrunc:15 }} @@ -2521,7 +2811,9 @@ As with urlize_, this filter should only be applied to plain text. Returns the number of words. -For example:: +For example: + +.. code-block:: html+django {{ value|wordcount }} @@ -2536,11 +2828,15 @@ Wraps words at specified line length. **Argument:** number of characters at which to wrap the text -For example:: +For example: + +.. code-block:: html+django {{ value|wordwrap:5 }} -If ``value`` is ``Joel is a slug``, the output would be:: +If ``value`` is ``Joel is a slug``, the output would be: + +.. code-block:: html+django Joel is a @@ -2555,7 +2851,9 @@ Maps values for ``True``, ``False``, and (optionally) ``None``, to the strings "yes", "no", "maybe", or a custom mapping passed as a comma-separated list, and returns one of those strings according to the value: -For example:: +For example: + +.. code-block:: html+django {{ value|yesno:"yeah,no,maybe" }} @@ -2629,19 +2927,25 @@ A set of Django template filters useful for adding a "human touch" to data. See To link to static files that are saved in :setting:`STATIC_ROOT` Django ships with a :ttag:`static` template tag. If the :mod:`django.contrib.staticfiles` app is installed, the tag will serve files using ``url()`` method of the -storage specified by ``staticfiles`` in :setting:`STORAGES`. For example:: +storage specified by ``staticfiles`` in :setting:`STORAGES`. For example: + +.. code-block:: html+django {% load static %} <img src="{% static 'images/hi.jpg' %}" alt="Hi!"> It is also able to consume standard context variables, e.g. assuming a -``user_stylesheet`` variable is passed to the template:: +``user_stylesheet`` variable is passed to the template: + +.. code-block:: html+django {% load static %} <link rel="stylesheet" href="{% static user_stylesheet %}" media="screen"> If you'd like to retrieve a static URL without displaying it, you can use a -slightly different call:: +slightly different call: + +.. code-block:: html+django {% load static %} {% static "images/hi.jpg" as myphoto %} @@ -2659,13 +2963,17 @@ slightly different call:: You should prefer the :ttag:`static` template tag, but if you need more control over exactly where and how :setting:`STATIC_URL` is injected into the template, -you can use the :ttag:`get_static_prefix` template tag:: +you can use the :ttag:`get_static_prefix` template tag: + +.. code-block:: html+django {% load static %} <img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!"> There's also a second form you can use to avoid extra processing if you need -the value multiple times:: +the value multiple times: + +.. code-block:: html+django {% load static %} {% get_static_prefix as STATIC_PREFIX %} @@ -2679,7 +2987,9 @@ the value multiple times:: ~~~~~~~~~~~~~~~~~~~~ Similar to the :ttag:`get_static_prefix`, ``get_media_prefix`` populates a -template variable with the media prefix :setting:`MEDIA_URL`, e.g.:: +template variable with the media prefix :setting:`MEDIA_URL`, e.g.: + +.. code-block:: html+django {% load static %} <body data-media-url="{% get_media_prefix %}"> diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt index 5a4cce379b..16a3682086 100644 --- a/docs/ref/templates/language.txt +++ b/docs/ref/templates/language.txt @@ -34,8 +34,6 @@ or Jinja2_, you should feel right at home with Django's templates. Templates ========= -.. highlight:: html+django - A template is a text file. It can generate any text-based format (HTML, XML, CSV, etc.). @@ -100,7 +98,9 @@ Use a dot (``.``) to access attributes of a variable. This lookup order can cause some unexpected behavior with objects that override dictionary lookup. For example, consider the following code snippet - that attempts to loop over a ``collections.defaultdict``:: + that attempts to loop over a ``collections.defaultdict``: + + .. code-block:: html+django {% for k, v in defaultdict.items %} Do something with k and v here... @@ -151,7 +151,9 @@ used template filters: :tfilter:`default` If a variable is false or empty, use given default. Otherwise, use the - value of the variable. For example:: + value of the variable. For example: + + .. code-block:: html+django {{ value|default:"nothing" }} @@ -160,7 +162,9 @@ used template filters: :tfilter:`length` Returns the length of the value. This works for both strings and lists. - For example:: + For example: + + .. code-block:: html+django {{ value|length }} @@ -168,7 +172,9 @@ used template filters: :tfilter:`filesizeformat` Formats the value like a "human-readable" file size (i.e. ``'13 KB'``, - ``'4.1 MB'``, ``'102 bytes'``, etc.). For example:: + ``'4.1 MB'``, ``'102 bytes'``, etc.). For example: + + .. code-block:: html+django {{ value|filesizeformat }} @@ -203,7 +209,9 @@ tags: :ttag:`for` Loop over each item in an array. For example, to display a list of athletes - provided in ``athlete_list``:: + provided in ``athlete_list``: + + .. code-block:: html+django <ul> {% for athlete in athlete_list %} @@ -213,7 +221,9 @@ tags: :ttag:`if`, ``elif``, and ``else`` Evaluates a variable, and if that variable is "true" the contents of the - block are displayed:: + block are displayed: + + .. code-block:: html+django {% if athlete_list %} Number of athletes: {{ athlete_list|length }} @@ -229,7 +239,9 @@ tags: should be out..." will be displayed. If both lists are empty, "No athletes." will be displayed. - You can also use filters and various operators in the :ttag:`if` tag:: + You can also use filters and various operators in the :ttag:`if` tag: + + .. code-block:: html+django {% if athlete_list|length > 1 %} Team: {% for athlete in athlete_list %} ... {% endfor %} @@ -264,11 +276,15 @@ Comments To comment-out part of a line in a template, use the comment syntax: ``{# #}``. -For example, this template would render as ``'hello'``:: +For example, this template would render as ``'hello'``: + +.. code-block:: html+django {# greeting #}hello -A comment can contain any template code, invalid or not. For example:: +A comment can contain any template code, invalid or not. For example: + +.. code-block:: html+django {# {% if foo %}bar{% else %} #} @@ -286,7 +302,9 @@ engine is template inheritance. Template inheritance allows you to build a base "skeleton" template that contains all the common elements of your site and defines **blocks** that child templates can override. -Let's look at template inheritance by starting with an example:: +Let's look at template inheritance by starting with an example: + +.. code-block:: html+django <!DOCTYPE html> <html lang="en"> @@ -319,7 +337,9 @@ In this example, the :ttag:`block` tag defines three blocks that child templates can fill in. All the :ttag:`block` tag does is to tell the template engine that a child template may override those portions of the template. -A child template might look like this:: +A child template might look like this: + +.. code-block:: html+django {% extends "base.html" %} @@ -339,7 +359,9 @@ this template, first it locates the parent -- in this case, "base.html". At that point, the template engine will notice the three :ttag:`block` tags in ``base.html`` and replace those blocks with the contents of the child template. Depending on the value of ``blog_entries``, the output might look -like:: +like: + +.. code-block:: html+django <!DOCTYPE html> <html lang="en"> @@ -416,13 +438,17 @@ Here are some tips for working with inheritance: * Variables created outside of a :ttag:`{% block %}<block>` using the template tag ``as`` syntax can't be used inside the block. For example, this template - doesn't render anything:: + doesn't render anything: + + .. code-block:: html+django {% translate "Title" as title %} {% block content %}{{ title }}{% endblock %} * For extra readability, you can optionally give a *name* to your - ``{% endblock %}`` tag. For example:: + ``{% endblock %}`` tag. For example: + + .. code-block:: html+django {% block content %} ... @@ -434,7 +460,9 @@ Here are some tips for working with inheritance: * :ttag:`{% block %}<block>` tags are evaluated first. That's why the content of a block is always overridden, regardless of the truthiness of surrounding tags. For example, this template will *always* override the content of the - ``title`` block:: + ``title`` block: + + .. code-block:: html+django {% if change_title %} {% block title %}Hello!{% endblock title %} @@ -455,16 +483,22 @@ Automatic HTML escaping When generating HTML from templates, there's always a risk that a variable will include characters that affect the resulting HTML. For example, consider this -template fragment:: +template fragment: + +.. code-block:: html+django Hello, {{ name }} At first, this seems like a harmless way to display a user's name, but consider -what would happen if the user entered their name as this:: +what would happen if the user entered their name as this: + +.. code-block:: html+django <script>alert('hello')</script> -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, <script>alert('hello')</script> @@ -476,7 +510,9 @@ Similarly, what if the name contained a ``'<'`` symbol, like this? <b>username -That would result in a rendered template like this:: +That would result in a rendered template like this: + +.. code-block:: html+django Hello, <b>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 ``'<b>'``, -the output will be:: +the output will be: + +.. code-block:: html+django This will be escaped: <b> This will not be escaped: <b> @@ -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 ``<b>Hello!</b>``:: +HTML when the ``greeting`` variable contains the string ``<b>Hello!</b>``: + +.. code-block:: html+django <h1>This & that</h1> <b>Hello!</b> @@ -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"<topics-db-queries-related>` 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</ref/models/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 <uri-and-iri-handling>`. For example:: + :ref:`urlquoted <uri-and-iri-handling>`. 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 ``<script>`` tag. If the ``element_id`` parameter is not ``None``, the - ``<script>`` tag is given the passed id. For example:: + ``<script>`` tag is given the passed id. For example: + + .. code-block:: pycon - >> json_script({"hello": "world"}, element_id="hello-data") + >>> json_script({"hello": "world"}, element_id="hello-data") '<script id="hello-data" type="application/json">{"hello": "world"}</script>' 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 = '<b>Hello World</b> ' >>> 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' |