mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-22 17:16:24 +00:00
Code Issues 25 Releases Wiki Activity

Added missing pycon directives in various docs.

Browse Source
This commit is contained in:
Mariusz Felisiak 2023-10-25 12:27:27 +02:00 committed by GitHub
parent ee104251c4
commit 718b32c691
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 295 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
docs/ref/contrib/gis/gdal.txt
View File

@ -1246,25 +1246,31 @@ blue.
sources (using the sample data from the GeoDjango tests; see also the sources (using the sample data from the GeoDjango tests; see also the
:ref:`gdal_sample_data` section). :ref:`gdal_sample_data` section).
.. code-block:: pycon
>>> from django.contrib.gis.gdal import GDALRaster >>> from django.contrib.gis.gdal import GDALRaster
>>> rst = GDALRaster('/path/to/your/raster.tif', write=False) >>> rst = GDALRaster("/path/to/your/raster.tif", write=False)
>>> rst.name >>> rst.name
'/path/to/your/raster.tif' '/path/to/your/raster.tif'
>>> rst.width, rst.height # This file has 163 x 174 pixels >>> rst.width, rst.height # This file has 163 x 174 pixels
(163, 174) (163, 174)
>>> rst = GDALRaster({ # Creates an in-memory raster >>> rst = GDALRaster(
... 'srid': 4326, ... { # Creates an in-memory raster
... 'width': 4, ... "srid": 4326,
... 'height': 4, ... "width": 4,
... 'datatype': 1, ... "height": 4,
... 'bands': [{ ... "datatype": 1,
... 'data': (2, 3), ... "bands": [
... 'offset': (1, 1), ... {
... 'size': (2, 2), ... "data": (2, 3),
... 'shape': (2, 1), ... "offset": (1, 1),
... 'nodata_value': 5, ... "size": (2, 2),
... }] ... "shape": (2, 1),
... }) ... "nodata_value": 5,
... }
... ],
... }
... )
>>> rst.srs.srid >>> rst.srs.srid
4326 4326
>>> rst.width, rst.height >>> rst.width, rst.height
@ -1274,7 +1280,7 @@ blue.
[5, 2, 3, 5], [5, 2, 3, 5],
[5, 2, 3, 5], [5, 2, 3, 5],
[5, 5, 5, 5]], dtype=uint8) [5, 5, 5, 5]], dtype=uint8)
>>> rst_file = open('/path/to/your/raster.tif', 'rb') >>> rst_file = open("/path/to/your/raster.tif", "rb")
>>> rst_bytes = rst_file.read() >>> rst_bytes = rst_file.read()
>>> rst = GDALRaster(rst_bytes) >>> rst = GDALRaster(rst_bytes)
>>> rst.is_vsi_based >>> rst.is_vsi_based
@ -1287,7 +1293,9 @@ blue.
The name of the source which is equivalent to the input file path or the name The name of the source which is equivalent to the input file path or the name
provided upon instantiation. provided upon instantiation.
>>> GDALRaster({'width': 10, 'height': 10, 'name': 'myraster', 'srid': 4326}).name .. code-block:: pycon
>>> GDALRaster({"width": 10, "height": 10, "name": "myraster", "srid": 4326}).name
'myraster' 'myraster'
.. attribute:: driver .. attribute:: driver
@ -1302,15 +1310,27 @@ blue.
An in-memory raster is created through the following example: An in-memory raster is created through the following example:
>>> GDALRaster({'width': 10, 'height': 10, 'srid': 4326}).driver.name .. code-block:: pycon
>>> GDALRaster({"width": 10, "height": 10, "srid": 4326}).driver.name
'MEM' 'MEM'
A file based GeoTiff raster is created through the following example: A file based GeoTiff raster is created through the following example:
.. code-block:: pycon
>>> import tempfile >>> import tempfile
>>> rstfile = tempfile.NamedTemporaryFile(suffix='.tif') >>> rstfile = tempfile.NamedTemporaryFile(suffix=".tif")
>>> rst = GDALRaster({'driver': 'GTiff', 'name': rstfile.name, 'srid': 4326, >>> rst = GDALRaster(
... 'width': 255, 'height': 255, 'nr_of_bands': 1}) ... {
... "driver": "GTiff",
... "name": rstfile.name,
... "srid": 4326,
... "width": 255,
... "height": 255,
... "nr_of_bands": 1,
... }
... )
>>> rst.name >>> rst.name
'/tmp/tmp7x9H4J.tif' # The exact filename will be different on your computer '/tmp/tmp7x9H4J.tif' # The exact filename will be different on your computer
>>> rst.driver.name >>> rst.driver.name
@ -1320,14 +1340,18 @@ blue.
The width of the source in pixels (X-axis). The width of the source in pixels (X-axis).
>>> GDALRaster({'width': 10, 'height': 20, 'srid': 4326}).width .. code-block:: pycon
>>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).width
10 10
.. attribute:: height .. attribute:: height
The height of the source in pixels (Y-axis). The height of the source in pixels (Y-axis).
>>> GDALRaster({'width': 10, 'height': 20, 'srid': 4326}).height .. code-block:: pycon
>>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).height
20 20
.. attribute:: srs .. attribute:: srs
@ -1337,7 +1361,9 @@ blue.
setting it to an other :class:`SpatialReference` or providing any input setting it to an other :class:`SpatialReference` or providing any input
that is accepted by the :class:`SpatialReference` constructor. that is accepted by the :class:`SpatialReference` constructor.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.srs.srid >>> rst.srs.srid
4326 4326
>>> rst.srs = 3086 >>> rst.srs = 3086
@ -1350,7 +1376,9 @@ blue.
property is a shortcut to getting or setting the SRID through the property is a shortcut to getting or setting the SRID through the
:attr:`srs` attribute. :attr:`srs` attribute.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.srid >>> rst.srid
4326 4326
>>> rst.srid = 3086 >>> rst.srid = 3086
@ -1374,7 +1402,9 @@ blue.
The default is ``[0.0, 1.0, 0.0, 0.0, 0.0, -1.0]``. The default is ``[0.0, 1.0, 0.0, 0.0, 0.0, -1.0]``.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.geotransform >>> rst.geotransform
[0.0, 1.0, 0.0, 0.0, 0.0, -1.0] [0.0, 1.0, 0.0, 0.0, 0.0, -1.0]
@ -1384,7 +1414,9 @@ blue.
reference system of the source, as a point object with ``x`` and ``y`` reference system of the source, as a point object with ``x`` and ``y``
members. members.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.origin >>> rst.origin
[0.0, 0.0] [0.0, 0.0]
>>> rst.origin.x = 1 >>> rst.origin.x = 1
@ -1397,7 +1429,9 @@ blue.
object with ``x`` and ``y`` members. See :attr:`geotransform` for more object with ``x`` and ``y`` members. See :attr:`geotransform` for more
information. information.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.scale >>> rst.scale
[1.0, -1.0] [1.0, -1.0]
>>> rst.scale.x = 2 >>> rst.scale.x = 2
@ -1410,7 +1444,9 @@ blue.
with ``x`` and ``y`` members. In case of north up images, these with ``x`` and ``y`` members. In case of north up images, these
coefficients are both ``0``. coefficients are both ``0``.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.skew >>> rst.skew
[0.0, 0.0] [0.0, 0.0]
>>> rst.skew.x = 3 >>> rst.skew.x = 3
@ -1423,7 +1459,9 @@ blue.
``(xmin, ymin, xmax, ymax)`` in the spatial reference system of the ``(xmin, ymin, xmax, ymax)`` in the spatial reference system of the
source. source.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.extent >>> rst.extent
(0.0, -20.0, 10.0, 0.0) (0.0, -20.0, 10.0, 0.0)
>>> rst.origin.x = 100 >>> rst.origin.x = 100
@ -1434,8 +1472,16 @@ blue.
List of all bands of the source, as :class:`GDALBand` instances. List of all bands of the source, as :class:`GDALBand` instances.
>>> rst = GDALRaster({"width": 1, "height": 2, 'srid': 4326, .. code-block:: pycon
... "bands": [{"data": [0, 1]}, {"data": [2, 3]}]})
>>> rst = GDALRaster(
... {
... "width": 1,
... "height": 2,
... "srid": 4326,
... "bands": [{"data": [0, 1]}, {"data": [2, 3]}],
... }
... )
>>> len(rst.bands) >>> len(rst.bands)
2 2
>>> rst.bands[1].data() >>> rst.bands[1].data()
@ -1478,12 +1524,18 @@ blue.
For example, the warp function can be used for aggregating a raster to For example, the warp function can be used for aggregating a raster to
the double of its original pixel scale: the double of its original pixel scale:
>>> rst = GDALRaster({ .. code-block:: pycon
... "width": 6, "height": 6, "srid": 3086,
... "origin": [500000, 400000], >>> rst = GDALRaster(
... "scale": [100, -100], ... {
... "bands": [{"data": range(36), "nodata_value": 99}] ... "width": 6,
... }) ... "height": 6,
... "srid": 3086,
... "origin": [500000, 400000],
... "scale": [100, -100],
... "bands": [{"data": range(36), "nodata_value": 99}],
... }
... )
>>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3}) >>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3})
>>> target.bands[0].data() >>> target.bands[0].data()
array([[ 7., 9., 11.], array([[ 7., 9., 11.],
@ -1512,12 +1564,18 @@ blue.
argument. Consult the :attr:`~GDALRaster.warp` documentation for detail argument. Consult the :attr:`~GDALRaster.warp` documentation for detail
on those arguments. on those arguments.
>>> rst = GDALRaster({ .. code-block:: pycon
... "width": 6, "height": 6, "srid": 3086,
... "origin": [500000, 400000], >>> rst = GDALRaster(
... "scale": [100, -100], ... {
... "bands": [{"data": range(36), "nodata_value": 99}] ... "width": 6,
... }) ... "height": 6,
... "srid": 3086,
... "origin": [500000, 400000],
... "scale": [100, -100],
... "bands": [{"data": range(36), "nodata_value": 99}],
... }
... )
>>> target_srs = SpatialReference(4326) >>> target_srs = SpatialReference(4326)
>>> target = rst.transform(target_srs) >>> target = rst.transform(target_srs)
>>> target.origin >>> target.origin
@ -1543,13 +1601,15 @@ blue.
To remove a metadata item, use ``None`` as the metadata value. To remove a metadata item, use ``None`` as the metadata value.
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) .. code-block:: pycon
>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.metadata >>> rst.metadata
{} {}
>>> rst.metadata = {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}} >>> rst.metadata = {"DEFAULT": {"OWNER": "Django", "VERSION": "1.0"}}
>>> rst.metadata >>> rst.metadata
{'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}} {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}}
>>> rst.metadata = {'DEFAULT': {'OWNER': None, 'VERSION': '2.0'}} >>> rst.metadata = {"DEFAULT": {"OWNER": None, "VERSION": "2.0"}}
>>> rst.metadata >>> rst.metadata
{'DEFAULT': {'VERSION': '2.0'}} {'DEFAULT': {'VERSION': '2.0'}}
@ -1687,7 +1747,11 @@ blue.
For example: For example:
>>> rst = GDALRaster({'width': 4, 'height': 4, 'srid': 4326, 'datatype': 1, 'nr_of_bands': 1}) .. code-block:: pycon
>>> rst = GDALRaster(
... {"width": 4, "height": 4, "srid": 4326, "datatype": 1, "nr_of_bands": 1}
... )
>>> bnd = rst.bands[0] >>> bnd = rst.bands[0]
>>> bnd.data(range(16)) >>> bnd.data(range(16))
>>> bnd.data() >>> bnd.data()
@ -1704,7 +1768,7 @@ blue.
[ 4, -1, -2, 7], [ 4, -1, -2, 7],
[ 8, -3, -4, 11], [ 8, -3, -4, 11],
[12, 13, 14, 15]], dtype=int8) [12, 13, 14, 15]], dtype=int8)
>>> bnd.data(data='\x9d\xa8\xb3\xbe', offset=(1, 1), size=(2, 2)) >>> bnd.data(data="\x9d\xa8\xb3\xbe", offset=(1, 1), size=(2, 2))
>>> bnd.data() >>> bnd.data()
array([[ 0, 1, 2, 3], array([[ 0, 1, 2, 3],
[ 4, -99, -88, 7], [ 4, -99, -88, 7],

16
docs/ref/contrib/postgres/search.txt
View File

@ -94,13 +94,17 @@ Examples:
.. _Full Text Search docs: https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES .. _Full Text Search docs: https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES
.. code-block:: pycon
>>> from django.contrib.postgres.search import SearchQuery >>> from django.contrib.postgres.search import SearchQuery
>>> SearchQuery('red tomato') # two keywords >>> SearchQuery("red tomato") # two keywords
>>> SearchQuery('tomato red') # same results as above >>> SearchQuery("tomato red") # same results as above
>>> SearchQuery('red tomato', search_type='phrase') # a phrase >>> SearchQuery("red tomato", search_type="phrase") # a phrase
>>> SearchQuery('tomato red', search_type='phrase') # a different phrase >>> SearchQuery("tomato red", search_type="phrase") # a different phrase
>>> SearchQuery("'tomato' & ('red' | 'green')", search_type='raw') # boolean operators >>> SearchQuery("'tomato' & ('red' | 'green')", search_type="raw") # boolean operators
>>> SearchQuery("'tomato' ('red' OR 'green')", search_type='websearch') # websearch 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:

21
docs/ref/forms/api.txt
View File

@ -148,6 +148,8 @@ if validation has side effects, those side effects will only be triggered once.
Returns a ``dict`` that maps fields to their original ``ValidationError`` Returns a ``dict`` that maps fields to their original ``ValidationError``
instances. instances.
.. code-block:: pycon
>>> f.errors.as_data() >>> f.errors.as_data()
{'sender': [ValidationError(['Enter a valid email address.'])], {'sender': [ValidationError(['Enter a valid email address.'])],
'subject': [ValidationError(['This field is required.'])]} 'subject': [ValidationError(['This field is required.'])]}
@ -170,6 +172,8 @@ messages in ``Form.errors``.
Returns the errors serialized as JSON. Returns the errors serialized as JSON.
.. code-block:: pycon
>>> f.errors.as_json() >>> f.errors.as_json()
{"sender": [{"message": "Enter a valid email address.", "code": "invalid"}], {"sender": [{"message": "Enter a valid email address.", "code": "invalid"}],
"subject": [{"message": "This field is required.", "code": "required"}]} "subject": [{"message": "This field is required.", "code": "required"}]}
@ -325,10 +329,14 @@ Checking which form data has changed
Use the ``has_changed()`` method on your ``Form`` when you need to check if the Use the ``has_changed()`` method on your ``Form`` when you need to check if the
form data has been changed from the initial data. form data has been changed from the initial data.
>>> data = {'subject': 'hello', .. code-block:: pycon
... 'message': 'Hi there',
... 'sender': 'foo@example.com', >>> data = {
... 'cc_myself': True} ... "subject": "hello",
... "message": "Hi there",
... "sender": "foo@example.com",
... "cc_myself": True,
... }
>>> f = ContactForm(data, initial=data) >>> f = ContactForm(data, initial=data)
>>> f.has_changed() >>> f.has_changed()
False False
@ -336,6 +344,8 @@ form data has been changed from the initial data.
When the form is submitted, we reconstruct it and provide the original data When the form is submitted, we reconstruct it and provide the original data
so that the comparison can be done: so that the comparison can be done:
.. code-block:: pycon
>>> f = ContactForm(request.POST, initial=data) >>> f = ContactForm(request.POST, initial=data)
>>> f.has_changed() >>> f.has_changed()
@ -350,9 +360,12 @@ The ``changed_data`` attribute returns a list of the names of the fields whose
values in the form's bound data (usually ``request.POST``) differ from what was values in the form's bound data (usually ``request.POST``) differ from what was
provided in :attr:`~Form.initial`. It returns an empty list if no data differs. provided in :attr:`~Form.initial`. It returns an empty list if no data differs.
.. code-block:: pycon
>>> f = ContactForm(request.POST, initial=data) >>> f = ContactForm(request.POST, initial=data)
>>> if f.has_changed(): >>> if f.has_changed():
... print("The following fields changed: %s" % ", ".join(f.changed_data)) ... print("The following fields changed: %s" % ", ".join(f.changed_data))
...
>>> f.changed_data >>> f.changed_data
['subject', 'message'] ['subject', 'message']

6
docs/ref/forms/fields.txt
View File

@ -1183,11 +1183,13 @@ Slightly complex built-in ``Field`` classes
The list of fields that should be used to validate the field's value (in The list of fields that should be used to validate the field's value (in
the order in which they are provided). the order in which they are provided).
.. code-block:: pycon
>>> from django.forms import ComboField >>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) >>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('test@example.com') >>> f.clean("test@example.com")
'test@example.com' 'test@example.com'
>>> f.clean('longemailaddress@example.com') >>> f.clean("longemailaddress@example.com")
Traceback (most recent call last): Traceback (most recent call last):
... ...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).'] ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

12
docs/ref/models/database-functions.txt
View File

@ -89,11 +89,13 @@ Usage examples:
A Python value passed to ``Coalesce`` on MySQL may be converted to an A Python value passed to ``Coalesce`` on MySQL may be converted to an
incorrect type unless explicitly cast to the correct database type: incorrect type unless explicitly cast to the correct database type:
>>> from django.db.models import DateTimeField .. code-block:: pycon
>>> from django.db.models.functions import Cast, Coalesce
>>> from django.utils import timezone >>> from django.db.models import DateTimeField
>>> now = timezone.now() >>> from django.db.models.functions import Cast, Coalesce
>>> Coalesce('updated', Cast(now, DateTimeField())) >>> from django.utils import timezone
>>> now = timezone.now()
>>> Coalesce("updated", Cast(now, DateTimeField()))
``Collate`` ``Collate``
----------- -----------

83
docs/ref/models/querysets.txt
View File

@ -997,6 +997,8 @@ databases don't allow ``LIMIT`` or ``OFFSET`` in the combined queries.
Uses SQL's ``INTERSECT`` operator to return the shared elements of two or more Uses SQL's ``INTERSECT`` operator to return the shared elements of two or more
``QuerySet``\s. For example: ``QuerySet``\s. For example:
.. code-block:: pycon
>>> qs1.intersection(qs2, qs3) >>> qs1.intersection(qs2, qs3)
See :meth:`union` for some restrictions. See :meth:`union` for some restrictions.
@ -1197,7 +1199,9 @@ item in the Pizza ``QuerySet``.
We can reduce to just two queries using ``prefetch_related``: We can reduce to just two queries using ``prefetch_related``:
>>> Pizza.objects.prefetch_related('toppings') .. code-block:: pycon
>>> Pizza.objects.prefetch_related("toppings")
This implies a ``self.toppings.all()`` for each ``Pizza``; now each time This implies a ``self.toppings.all()`` for each ``Pizza``; now each time
``self.toppings.all()`` is called, instead of having to go to the database for ``self.toppings.all()`` is called, instead of having to go to the database for
@ -1241,7 +1245,9 @@ database.
results, and retrieve data using a fresh database query. So, if you write results, and retrieve data using a fresh database query. So, if you write
the following: the following:
>>> pizzas = Pizza.objects.prefetch_related('toppings') .. code-block:: pycon
>>> pizzas = Pizza.objects.prefetch_related("toppings")
>>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas] >>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]
...then the fact that ``pizza.toppings.all()`` has been prefetched will not ...then the fact that ``pizza.toppings.all()`` has been prefetched will not
@ -1301,7 +1307,9 @@ Chaining ``prefetch_related`` calls will accumulate the lookups that are
prefetched. To clear any ``prefetch_related`` behavior, pass ``None`` as a prefetched. To clear any ``prefetch_related`` behavior, pass ``None`` as a
parameter: parameter:
>>> non_prefetched = qs.prefetch_related(None) .. code-block:: pycon
>>> non_prefetched = qs.prefetch_related(None)
One difference to note when using ``prefetch_related`` is that objects created One difference to note when using ``prefetch_related`` is that objects created
by a query can be shared between the different objects that they are related to by a query can be shared between the different objects that they are related to
@ -1332,20 +1340,28 @@ the prefetch operation.
In its simplest form ``Prefetch`` is equivalent to the traditional string based In its simplest form ``Prefetch`` is equivalent to the traditional string based
lookups: lookups:
.. code-block:: pycon
>>> from django.db.models import Prefetch >>> from django.db.models import Prefetch
>>> Restaurant.objects.prefetch_related(Prefetch('pizzas__toppings')) >>> Restaurant.objects.prefetch_related(Prefetch("pizzas__toppings"))
You can provide a custom queryset with the optional ``queryset`` argument. You can provide a custom queryset with the optional ``queryset`` argument.
This can be used to change the default ordering of the queryset: This can be used to change the default ordering of the queryset:
.. code-block:: pycon
>>> Restaurant.objects.prefetch_related( >>> Restaurant.objects.prefetch_related(
... Prefetch('pizzas__toppings', queryset=Toppings.objects.order_by('name'))) ... Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name"))
... )
Or to call :meth:`~django.db.models.query.QuerySet.select_related()` when Or to call :meth:`~django.db.models.query.QuerySet.select_related()` when
applicable to reduce the number of queries even further: applicable to reduce the number of queries even further:
.. code-block:: pycon
>>> Pizza.objects.prefetch_related( >>> Pizza.objects.prefetch_related(
... Prefetch('restaurants', queryset=Restaurant.objects.select_related('best_pizza'))) ... Prefetch("restaurants", queryset=Restaurant.objects.select_related("best_pizza"))
... )
You can also assign the prefetched result to a custom attribute with the optional You can also assign the prefetched result to a custom attribute with the optional
``to_attr`` argument. The result will be stored directly in a list. ``to_attr`` argument. The result will be stored directly in a list.
@ -1353,32 +1369,42 @@ You can also assign the prefetched result to a custom attribute with the optiona
This allows prefetching the same relation multiple times with a different This allows prefetching the same relation multiple times with a different
``QuerySet``; for instance: ``QuerySet``; for instance:
.. code-block:: pycon
>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True) >>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related( >>> Restaurant.objects.prefetch_related(
... Prefetch('pizzas', to_attr='menu'), ... Prefetch("pizzas", to_attr="menu"),
... Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu')) ... Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
... )
Lookups created with custom ``to_attr`` can still be traversed as usual by other Lookups created with custom ``to_attr`` can still be traversed as usual by other
lookups: lookups:
.. code-block:: pycon
>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True) >>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related( >>> Restaurant.objects.prefetch_related(
... Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu'), ... Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
... 'vegetarian_menu__toppings') ... "vegetarian_menu__toppings",
... )
Using ``to_attr`` is recommended when filtering down the prefetch result as it is Using ``to_attr`` is recommended when filtering down the prefetch result as it is
less ambiguous than storing a filtered result in the related manager's cache: less ambiguous than storing a filtered result in the related manager's cache:
.. code-block:: pycon
>>> queryset = Pizza.objects.filter(vegetarian=True) >>> queryset = Pizza.objects.filter(vegetarian=True)
>>> >>>
>>> # Recommended: >>> # Recommended:
>>> restaurants = Restaurant.objects.prefetch_related( >>> restaurants = Restaurant.objects.prefetch_related(
... Prefetch('pizzas', queryset=queryset, to_attr='vegetarian_pizzas')) ... Prefetch("pizzas", queryset=queryset, to_attr="vegetarian_pizzas")
... )
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas >>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
>>> >>>
>>> # Not recommended: >>> # Not recommended:
>>> restaurants = Restaurant.objects.prefetch_related( >>> restaurants = Restaurant.objects.prefetch_related(
... Prefetch('pizzas', queryset=queryset)) ... Prefetch("pizzas", queryset=queryset),
... )
>>> vegetarian_pizzas = restaurants[0].pizzas.all() >>> vegetarian_pizzas = restaurants[0].pizzas.all()
Custom prefetching also works with single related relations like Custom prefetching also works with single related relations like
@ -1394,10 +1420,13 @@ where prefetching with a custom ``QuerySet`` is useful:
* You want to use performance optimization techniques like * You want to use performance optimization techniques like
:meth:`deferred fields <defer()>`: :meth:`deferred fields <defer()>`:
>>> queryset = Pizza.objects.only('name') .. code-block:: pycon
>>> queryset = Pizza.objects.only("name")
>>> >>>
>>> restaurants = Restaurant.objects.prefetch_related( >>> restaurants = Restaurant.objects.prefetch_related(
... Prefetch('best_pizza', queryset=queryset)) ... Prefetch("best_pizza", queryset=queryset)
... )
When using multiple databases, ``Prefetch`` will respect your choice of 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. If the inner query does not specify a database, it will use the
@ -1427,20 +1456,26 @@ database selected by the outer query. All of the following are valid:
Take the following examples: Take the following examples:
>>> prefetch_related('pizzas__toppings', 'pizzas') .. code-block:: pycon
>>> prefetch_related("pizzas__toppings", "pizzas")
This works even though it's unordered because ``'pizzas__toppings'`` This works even though it's unordered because ``'pizzas__toppings'``
already contains all the needed information, therefore the second argument already contains all the needed information, therefore the second argument
``'pizzas'`` is actually redundant. ``'pizzas'`` is actually redundant.
>>> prefetch_related('pizzas__toppings', Prefetch('pizzas', queryset=Pizza.objects.all())) .. code-block:: pycon
>>> prefetch_related("pizzas__toppings", Prefetch("pizzas", queryset=Pizza.objects.all()))
This will raise a ``ValueError`` because of the attempt to redefine the This will raise a ``ValueError`` because of the attempt to redefine the
queryset of a previously seen lookup. Note that an implicit queryset was queryset of a previously seen lookup. Note that an implicit queryset was
created to traverse ``'pizzas'`` as part of the ``'pizzas__toppings'`` created to traverse ``'pizzas'`` as part of the ``'pizzas__toppings'``
lookup. lookup.
>>> prefetch_related('pizza_list__toppings', Prefetch('pizzas', to_attr='pizza_list')) .. code-block:: pycon
>>> prefetch_related("pizza_list__toppings", Prefetch("pizzas", to_attr="pizza_list"))
This will trigger an ``AttributeError`` because ``'pizza_list'`` doesn't exist yet This will trigger an ``AttributeError`` because ``'pizza_list'`` doesn't exist yet
when ``'pizza_list__toppings'`` is being processed. when ``'pizza_list__toppings'`` is being processed.
@ -4058,12 +4093,14 @@ The ``lookup`` argument describes the relations to follow and works the same
as the string based lookups passed to as the string based lookups passed to
:meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example: :meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example:
.. code-block:: pycon
>>> from django.db.models import Prefetch >>> from django.db.models import Prefetch
>>> Question.objects.prefetch_related(Prefetch('choice_set')).get().choice_set.all() >>> Question.objects.prefetch_related(Prefetch("choice_set")).get().choice_set.all()
<QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]> <QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>
# This will only execute two queries regardless of the number of Question # This will only execute two queries regardless of the number of Question
# and Choice objects. # and Choice objects.
>>> Question.objects.prefetch_related(Prefetch('choice_set')) >>> Question.objects.prefetch_related(Prefetch("choice_set"))
<QuerySet [<Question: What's up?>]> <QuerySet [<Question: What's up?>]>
The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup. The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup.
@ -4071,17 +4108,21 @@ This is useful to further filter down the prefetch operation, or to call
:meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched :meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched
relation, hence reducing the number of queries even further: relation, hence reducing the number of queries even further:
.. code-block:: pycon
>>> voted_choices = Choice.objects.filter(votes__gt=0) >>> voted_choices = Choice.objects.filter(votes__gt=0)
>>> voted_choices >>> voted_choices
<QuerySet [<Choice: The sky>]> <QuerySet [<Choice: The sky>]>
>>> prefetch = Prefetch('choice_set', queryset=voted_choices) >>> prefetch = Prefetch("choice_set", queryset=voted_choices)
>>> Question.objects.prefetch_related(prefetch).get().choice_set.all() >>> Question.objects.prefetch_related(prefetch).get().choice_set.all()
<QuerySet [<Choice: The sky>]> <QuerySet [<Choice: The sky>]>
The ``to_attr`` argument sets the result of the prefetch operation to a custom The ``to_attr`` argument sets the result of the prefetch operation to a custom
attribute: attribute:
>>> prefetch = Prefetch('choice_set', queryset=voted_choices, to_attr='voted_choices') .. code-block:: pycon
>>> prefetch = Prefetch("choice_set", queryset=voted_choices, to_attr="voted_choices")
>>> Question.objects.prefetch_related(prefetch).get().voted_choices >>> Question.objects.prefetch_related(prefetch).get().voted_choices
[<Choice: The sky>] [<Choice: The sky>]
>>> Question.objects.prefetch_related(prefetch).get().choice_set.all() >>> Question.objects.prefetch_related(prefetch).get().choice_set.all()

20
docs/ref/request-response.txt
View File

@ -371,12 +371,14 @@ Methods
Otherwise the absolute URI is built using the server variables available in Otherwise the absolute URI is built using the server variables available in
this request. For example: this request. For example:
>>> request.build_absolute_uri() .. code-block:: pycon
'https://example.com/music/bands/the_beatles/?print=true'
>>> request.build_absolute_uri('/bands/') >>> request.build_absolute_uri()
'https://example.com/bands/' 'https://example.com/music/bands/the_beatles/?print=true'
>>> request.build_absolute_uri('https://example2.com/bands/') >>> request.build_absolute_uri("/bands/")
'https://example2.com/bands/' 'https://example.com/bands/'
>>> request.build_absolute_uri("https://example2.com/bands/")
'https://example2.com/bands/'
.. note:: .. note::
@ -494,8 +496,10 @@ a subclass of dictionary. Exceptions are outlined here:
Instantiates a ``QueryDict`` object based on ``query_string``. Instantiates a ``QueryDict`` object based on ``query_string``.
>>> QueryDict('a=1&a=2&c=3') .. code-block:: pycon
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>
>>> QueryDict("a=1&a=2&c=3")
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>
If ``query_string`` is not passed in, the resulting ``QueryDict`` will be If ``query_string`` is not passed in, the resulting ``QueryDict`` will be
empty (it will have no keys or values). empty (it will have no keys or values).

57
docs/ref/templates/api.txt
View File

@ -498,24 +498,30 @@ If you ``pop()`` too much, it'll raise
You can also use ``push()`` as a context manager to ensure a matching ``pop()`` You can also use ``push()`` as a context manager to ensure a matching ``pop()``
is called. is called.
.. code-block:: pycon
>>> c = Context() >>> c = Context()
>>> c['foo'] = 'first level' >>> c["foo"] = "first level"
>>> with c.push(): >>> with c.push():
... c['foo'] = 'second level' ... c["foo"] = "second level"
... c['foo'] ... c["foo"]
...
'second level' 'second level'
>>> c['foo'] >>> c["foo"]
'first level' 'first level'
All arguments passed to ``push()`` will be passed to the ``dict`` constructor All arguments passed to ``push()`` will be passed to the ``dict`` constructor
used to build the new context level. used to build the new context level.
.. code-block:: pycon
>>> c = Context() >>> c = Context()
>>> c['foo'] = 'first level' >>> c["foo"] = "first level"
>>> with c.push(foo='second level'): >>> with c.push(foo="second level"):
... c['foo'] ... c["foo"]
...
'second level' 'second level'
>>> c['foo'] >>> c["foo"]
'first level' 'first level'
.. method:: Context.update(other_dict) .. method:: Context.update(other_dict)
@ -525,26 +531,31 @@ object also defines an ``update()`` method. This works like ``push()``
but takes a dictionary as an argument and pushes that dictionary onto but takes a dictionary as an argument and pushes that dictionary onto
the stack instead of an empty one. the stack instead of an empty one.
.. code-block:: pycon
>>> c = Context() >>> c = Context()
>>> c['foo'] = 'first level' >>> c["foo"] = "first level"
>>> c.update({'foo': 'updated'}) >>> c.update({"foo": "updated"})
{'foo': 'updated'} {'foo': 'updated'}
>>> c['foo'] >>> c["foo"]
'updated' 'updated'
>>> c.pop() >>> c.pop()
{'foo': 'updated'} {'foo': 'updated'}
>>> c['foo'] >>> c["foo"]
'first level' 'first level'
Like ``push()``, you can use ``update()`` as a context manager to ensure a Like ``push()``, you can use ``update()`` as a context manager to ensure a
matching ``pop()`` is called. matching ``pop()`` is called.
.. code-block:: pycon
>>> c = Context() >>> c = Context()
>>> c['foo'] = 'first level' >>> c["foo"] = "first level"
>>> with c.update({'foo': 'second level'}): >>> with c.update({"foo": "second level"}):
... c['foo'] ... c["foo"]
...
'second level' 'second level'
>>> c['foo'] >>> c["foo"]
'first level' 'first level'
Using a ``Context`` as a stack comes in handy in :ref:`some custom template Using a ``Context`` as a stack comes in handy in :ref:`some custom template
@ -555,20 +566,24 @@ tags <howto-writing-custom-template-tags>`.
Using ``flatten()`` method you can get whole ``Context`` stack as one dictionary Using ``flatten()`` method you can get whole ``Context`` stack as one dictionary
including builtin variables. including builtin variables.
.. code-block:: pycon
>>> c = Context() >>> c = Context()
>>> c['foo'] = 'first level' >>> c["foo"] = "first level"
>>> c.update({'bar': 'second level'}) >>> c.update({"bar": "second level"})
{'bar': 'second level'} {'bar': 'second level'}
>>> c.flatten() >>> c.flatten()
{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'} {'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}
A ``flatten()`` method is also internally used to make ``Context`` objects comparable. A ``flatten()`` method is also internally used to make ``Context`` objects comparable.
.. code-block:: pycon
>>> c1 = Context() >>> c1 = Context()
>>> c1['foo'] = 'first level' >>> c1["foo"] = "first level"
>>> c1['bar'] = 'second level' >>> c1["bar"] = "second level"
>>> c2 = Context() >>> c2 = Context()
>>> c2.update({'bar': 'second level', 'foo': 'first level'}) >>> c2.update({"bar": "second level", "foo": "first level"})
{'foo': 'first level', 'bar': 'second level'} {'foo': 'first level', 'bar': 'second level'}
>>> c1 == c2 >>> c1 == c2
True True

16
docs/topics/cache.txt
View File

@ -872,9 +872,11 @@ Accessing the cache
requests for the same alias in the same thread will return the same requests for the same alias in the same thread will return the same
object. object.
.. code-block:: pycon
>>> from django.core.cache import caches >>> from django.core.cache import caches
>>> cache1 = caches['myalias'] >>> cache1 = caches["myalias"]
>>> cache2 = caches['myalias'] >>> cache2 = caches["myalias"]
>>> cache1 is cache2 >>> cache1 is cache2
True True
@ -906,11 +908,15 @@ The basic interface is:
.. method:: cache.set(key, value, timeout=DEFAULT_TIMEOUT, version=None) .. method:: cache.set(key, value, timeout=DEFAULT_TIMEOUT, version=None)
>>> cache.set('my_key', 'hello, world!', 30) .. code-block:: pycon
>>> cache.set("my_key", "hello, world!", 30)
.. method:: cache.get(key, default=None, version=None) .. method:: cache.get(key, default=None, version=None)
>>> cache.get('my_key') .. code-block:: pycon
>>> cache.get("my_key")
'hello, world!' 'hello, world!'
``key`` should be a ``str``, and ``value`` can be any picklable Python object. ``key`` should be a ``str``, and ``value`` can be any picklable Python object.
@ -1100,6 +1106,8 @@ nonexistent cache key:
You can close the connection to your cache with ``close()`` if implemented by You can close the connection to your cache with ``close()`` if implemented by
the cache backend. the cache backend.
.. code-block:: pycon
>>> cache.close() >>> cache.close()
.. note:: .. note::

14
docs/topics/db/aggregation.txt
View File

@ -222,12 +222,14 @@ Combining multiple aggregations
Combining multiple aggregations with ``annotate()`` will :ticket:`yield the Combining multiple aggregations with ``annotate()`` will :ticket:`yield the
wrong results <10060>` because joins are used instead of subqueries: wrong results <10060>` because joins are used instead of subqueries:
.. code-block:: pycon
>>> book = Book.objects.first() >>> book = Book.objects.first()
>>> book.authors.count() >>> book.authors.count()
2 2
>>> book.store_set.count() >>> book.store_set.count()
3 3
>>> q = Book.objects.annotate(Count('authors'), Count('store')) >>> q = Book.objects.annotate(Count("authors"), Count("store"))
>>> q[0].authors__count >>> q[0].authors__count
6 6
>>> q[0].store__count >>> q[0].store__count
@ -237,7 +239,11 @@ For most aggregates, there is no way to avoid this problem, however, the
:class:`~django.db.models.Count` aggregate has a ``distinct`` parameter that :class:`~django.db.models.Count` aggregate has a ``distinct`` parameter that
may help: may help:
>>> q = Book.objects.annotate(Count('authors', distinct=True), Count('store', distinct=True)) .. code-block:: pycon
>>> q = Book.objects.annotate(
... Count("authors", distinct=True), Count("store", distinct=True)
... )
>>> q[0].authors__count >>> q[0].authors__count
2 2
>>> q[0].store__count >>> q[0].store__count
@ -514,7 +520,9 @@ the annotation is computed over all members of the group.
For example, consider an author query that attempts to find out the average For example, consider an author query that attempts to find out the average
rating of books written by each author: rating of books written by each author:
>>> Author.objects.annotate(average_rating=Avg('book__rating')) .. code-block:: pycon
>>> Author.objects.annotate(average_rating=Avg("book__rating"))
This will return one result for each author in the database, annotated with This will return one result for each author in the database, annotated with
their average book rating. their average book rating.

20
docs/topics/db/queries.txt
View File

@ -448,6 +448,8 @@ can specify the field name suffixed with ``_id``. In this case, the value
parameter is expected to contain the raw value of the foreign model's primary parameter is expected to contain the raw value of the foreign model's primary
key. For example: key. For example:
.. code-block:: pycon
>>> Entry.objects.filter(blog_id=4) >>> Entry.objects.filter(blog_id=4)
If you pass an invalid keyword argument, a lookup function will raise If you pass an invalid keyword argument, a lookup function will raise
@ -610,40 +612,42 @@ contained in a single :meth:`~django.db.models.query.QuerySet.filter` call.
As the second (more permissive) query chains multiple filters, it performs As the second (more permissive) query chains multiple filters, it performs
multiple joins to the primary model, potentially yielding duplicates. multiple joins to the primary model, potentially yielding duplicates.
.. code-block:: pycon
>>> from datetime import date >>> from datetime import date
>>> beatles = Blog.objects.create(name='Beatles Blog') >>> beatles = Blog.objects.create(name="Beatles Blog")
>>> pop = Blog.objects.create(name='Pop Music Blog') >>> pop = Blog.objects.create(name="Pop Music Blog")
>>> Entry.objects.create( >>> Entry.objects.create(
... blog=beatles, ... blog=beatles,
... headline='New Lennon Biography', ... headline="New Lennon Biography",
... pub_date=date(2008, 6, 1), ... pub_date=date(2008, 6, 1),
... ) ... )
<Entry: New Lennon Biography> <Entry: New Lennon Biography>
>>> Entry.objects.create( >>> Entry.objects.create(
... blog=beatles, ... blog=beatles,
... headline='New Lennon Biography in Paperback', ... headline="New Lennon Biography in Paperback",
... pub_date=date(2009, 6, 1), ... pub_date=date(2009, 6, 1),
... ) ... )
<Entry: New Lennon Biography in Paperback> <Entry: New Lennon Biography in Paperback>
>>> Entry.objects.create( >>> Entry.objects.create(
... blog=pop, ... blog=pop,
... headline='Best Albums of 2008', ... headline="Best Albums of 2008",
... pub_date=date(2008, 12, 15), ... pub_date=date(2008, 12, 15),
... ) ... )
<Entry: Best Albums of 2008> <Entry: Best Albums of 2008>
>>> Entry.objects.create( >>> Entry.objects.create(
... blog=pop, ... blog=pop,
... headline='Lennon Would Have Loved Hip Hop', ... headline="Lennon Would Have Loved Hip Hop",
... pub_date=date(2020, 4, 1), ... pub_date=date(2020, 4, 1),
... ) ... )
<Entry: Lennon Would Have Loved Hip Hop> <Entry: Lennon Would Have Loved Hip Hop>
>>> Blog.objects.filter( >>> Blog.objects.filter(
... entry__headline__contains='Lennon', ... entry__headline__contains="Lennon",
... entry__pub_date__year=2008, ... entry__pub_date__year=2008,
... ) ... )
<QuerySet [<Blog: Beatles Blog>]> <QuerySet [<Blog: Beatles Blog>]>
>>> Blog.objects.filter( >>> Blog.objects.filter(
... entry__headline__contains='Lennon', ... entry__headline__contains="Lennon",
... ).filter( ... ).filter(
... entry__pub_date__year=2008, ... entry__pub_date__year=2008,
... ) ... )