From 718b32c6918037cfc746d7867333d79a3c887a8c Mon Sep 17 00:00:00 2001 From: Mariusz Felisiak Date: Wed, 25 Oct 2023 12:27:27 +0200 Subject: [PATCH] Added missing pycon directives in various docs. --- docs/ref/contrib/gis/gdal.txt | 160 +++++++++++++++++-------- docs/ref/contrib/postgres/search.txt | 16 ++- docs/ref/forms/api.txt | 21 +++- docs/ref/forms/fields.txt | 6 +- docs/ref/models/database-functions.txt | 12 +- docs/ref/models/querysets.txt | 83 +++++++++---- docs/ref/request-response.txt | 20 ++-- docs/ref/templates/api.txt | 57 +++++---- docs/topics/cache.txt | 16 ++- docs/topics/db/aggregation.txt | 14 ++- docs/topics/db/queries.txt | 20 ++-- 11 files changed, 295 insertions(+), 130 deletions(-) diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index 3692c51c34..2b8f6d29da 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/docs/ref/contrib/gis/gdal.txt @@ -1246,25 +1246,31 @@ blue. sources (using the sample data from the GeoDjango tests; see also the :ref:`gdal_sample_data` section). + .. code-block:: pycon + >>> 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 '/path/to/your/raster.tif' >>> rst.width, rst.height # This file has 163 x 174 pixels (163, 174) - >>> rst = GDALRaster({ # Creates an in-memory raster - ... 'srid': 4326, - ... 'width': 4, - ... 'height': 4, - ... 'datatype': 1, - ... 'bands': [{ - ... 'data': (2, 3), - ... 'offset': (1, 1), - ... 'size': (2, 2), - ... 'shape': (2, 1), - ... 'nodata_value': 5, - ... }] - ... }) + >>> rst = GDALRaster( + ... { # Creates an in-memory raster + ... "srid": 4326, + ... "width": 4, + ... "height": 4, + ... "datatype": 1, + ... "bands": [ + ... { + ... "data": (2, 3), + ... "offset": (1, 1), + ... "size": (2, 2), + ... "shape": (2, 1), + ... "nodata_value": 5, + ... } + ... ], + ... } + ... ) >>> rst.srs.srid 4326 >>> rst.width, rst.height @@ -1274,7 +1280,7 @@ blue. [5, 2, 3, 5], [5, 2, 3, 5], [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 = GDALRaster(rst_bytes) >>> 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 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' .. attribute:: driver @@ -1302,15 +1310,27 @@ blue. 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' A file based GeoTiff raster is created through the following example: + .. code-block:: pycon + >>> import tempfile - >>> rstfile = tempfile.NamedTemporaryFile(suffix='.tif') - >>> rst = GDALRaster({'driver': 'GTiff', 'name': rstfile.name, 'srid': 4326, - ... 'width': 255, 'height': 255, 'nr_of_bands': 1}) + >>> rstfile = tempfile.NamedTemporaryFile(suffix=".tif") + >>> rst = GDALRaster( + ... { + ... "driver": "GTiff", + ... "name": rstfile.name, + ... "srid": 4326, + ... "width": 255, + ... "height": 255, + ... "nr_of_bands": 1, + ... } + ... ) >>> rst.name '/tmp/tmp7x9H4J.tif' # The exact filename will be different on your computer >>> rst.driver.name @@ -1320,14 +1340,18 @@ blue. 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 .. attribute:: height 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 .. attribute:: srs @@ -1337,7 +1361,9 @@ blue. setting it to an other :class:`SpatialReference` or providing any input 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 4326 >>> rst.srs = 3086 @@ -1350,7 +1376,9 @@ blue. property is a shortcut to getting or setting the SRID through the :attr:`srs` attribute. - >>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) + .. code-block:: pycon + + >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.srid 4326 >>> rst.srid = 3086 @@ -1374,7 +1402,9 @@ blue. 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 [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`` members. - >>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) + .. code-block:: pycon + + >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.origin [0.0, 0.0] >>> rst.origin.x = 1 @@ -1397,7 +1429,9 @@ blue. object with ``x`` and ``y`` members. See :attr:`geotransform` for more information. - >>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) + .. code-block:: pycon + + >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.scale [1.0, -1.0] >>> rst.scale.x = 2 @@ -1410,7 +1444,9 @@ blue. with ``x`` and ``y`` members. In case of north up images, these 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 [0.0, 0.0] >>> rst.skew.x = 3 @@ -1423,7 +1459,9 @@ blue. ``(xmin, ymin, xmax, ymax)`` in the spatial reference system of the source. - >>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) + .. code-block:: pycon + + >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.extent (0.0, -20.0, 10.0, 0.0) >>> rst.origin.x = 100 @@ -1434,8 +1472,16 @@ blue. List of all bands of the source, as :class:`GDALBand` instances. - >>> rst = GDALRaster({"width": 1, "height": 2, 'srid': 4326, - ... "bands": [{"data": [0, 1]}, {"data": [2, 3]}]}) + .. code-block:: pycon + + >>> rst = GDALRaster( + ... { + ... "width": 1, + ... "height": 2, + ... "srid": 4326, + ... "bands": [{"data": [0, 1]}, {"data": [2, 3]}], + ... } + ... ) >>> len(rst.bands) 2 >>> rst.bands[1].data() @@ -1478,12 +1524,18 @@ blue. For example, the warp function can be used for aggregating a raster to the double of its original pixel scale: - >>> rst = GDALRaster({ - ... "width": 6, "height": 6, "srid": 3086, - ... "origin": [500000, 400000], - ... "scale": [100, -100], - ... "bands": [{"data": range(36), "nodata_value": 99}] - ... }) + .. code-block:: pycon + + >>> rst = GDALRaster( + ... { + ... "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.bands[0].data() array([[ 7., 9., 11.], @@ -1512,12 +1564,18 @@ blue. argument. Consult the :attr:`~GDALRaster.warp` documentation for detail on those arguments. - >>> rst = GDALRaster({ - ... "width": 6, "height": 6, "srid": 3086, - ... "origin": [500000, 400000], - ... "scale": [100, -100], - ... "bands": [{"data": range(36), "nodata_value": 99}] - ... }) + .. code-block:: pycon + + >>> rst = GDALRaster( + ... { + ... "width": 6, + ... "height": 6, + ... "srid": 3086, + ... "origin": [500000, 400000], + ... "scale": [100, -100], + ... "bands": [{"data": range(36), "nodata_value": 99}], + ... } + ... ) >>> target_srs = SpatialReference(4326) >>> target = rst.transform(target_srs) >>> target.origin @@ -1543,13 +1601,15 @@ blue. 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 = {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}} + >>> rst.metadata = {"DEFAULT": {"OWNER": "Django", "VERSION": "1.0"}} >>> rst.metadata {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}} - >>> rst.metadata = {'DEFAULT': {'OWNER': None, 'VERSION': '2.0'}} + >>> rst.metadata = {"DEFAULT": {"OWNER": None, "VERSION": "2.0"}} >>> rst.metadata {'DEFAULT': {'VERSION': '2.0'}} @@ -1687,7 +1747,11 @@ blue. 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.data(range(16)) >>> bnd.data() @@ -1704,7 +1768,7 @@ blue. [ 4, -1, -2, 7], [ 8, -3, -4, 11], [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() array([[ 0, 1, 2, 3], [ 4, -99, -88, 7], diff --git a/docs/ref/contrib/postgres/search.txt b/docs/ref/contrib/postgres/search.txt index 8b1313709e..220ab4c591 100644 --- a/docs/ref/contrib/postgres/search.txt +++ b/docs/ref/contrib/postgres/search.txt @@ -94,13 +94,17 @@ Examples: .. _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 - >>> SearchQuery('red tomato') # two keywords - >>> SearchQuery('tomato red') # same results as above - >>> SearchQuery('red tomato', search_type='phrase') # a phrase - >>> SearchQuery('tomato red', search_type='phrase') # a different phrase - >>> SearchQuery("'tomato' & ('red' | 'green')", search_type='raw') # boolean operators - >>> SearchQuery("'tomato' ('red' OR 'green')", search_type='websearch') # websearch operators + >>> SearchQuery("red tomato") # two keywords + >>> SearchQuery("tomato red") # same results as above + >>> SearchQuery("red tomato", search_type="phrase") # a phrase + >>> SearchQuery("tomato red", search_type="phrase") # a different phrase + >>> 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: diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index c4df99af7f..7bec9b120b 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -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`` instances. +.. code-block:: pycon + >>> f.errors.as_data() {'sender': [ValidationError(['Enter a valid email address.'])], 'subject': [ValidationError(['This field is required.'])]} @@ -170,6 +172,8 @@ messages in ``Form.errors``. Returns the errors serialized as JSON. +.. code-block:: pycon + >>> f.errors.as_json() {"sender": [{"message": "Enter a valid email address.", "code": "invalid"}], "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 form data has been changed from the initial data. - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True} +.. code-block:: pycon + + >>> data = { + ... "subject": "hello", + ... "message": "Hi there", + ... "sender": "foo@example.com", + ... "cc_myself": True, + ... } >>> f = ContactForm(data, initial=data) >>> f.has_changed() 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 so that the comparison can be done: +.. code-block:: pycon + >>> f = ContactForm(request.POST, initial=data) >>> 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 provided in :attr:`~Form.initial`. It returns an empty list if no data differs. +.. code-block:: pycon + >>> f = ContactForm(request.POST, initial=data) >>> if f.has_changed(): ... print("The following fields changed: %s" % ", ".join(f.changed_data)) + ... >>> f.changed_data ['subject', 'message'] diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 35fc4b4b27..df9732f1af 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -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 order in which they are provided). + .. code-block:: pycon + >>> from django.forms import ComboField >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) - >>> f.clean('test@example.com') + >>> f.clean("test@example.com") 'test@example.com' - >>> f.clean('longemailaddress@example.com') + >>> f.clean("longemailaddress@example.com") Traceback (most recent call last): ... ValidationError: ['Ensure this value has at most 20 characters (it has 28).'] diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index 42ae8c34e7..ca4016e2b6 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -89,11 +89,13 @@ Usage examples: A Python value passed to ``Coalesce`` on MySQL may be converted to an incorrect type unless explicitly cast to the correct database type: - >>> from django.db.models import DateTimeField - >>> from django.db.models.functions import Cast, Coalesce - >>> from django.utils import timezone - >>> now = timezone.now() - >>> Coalesce('updated', Cast(now, DateTimeField())) + .. code-block:: pycon + + >>> from django.db.models import DateTimeField + >>> from django.db.models.functions import Cast, Coalesce + >>> from django.utils import timezone + >>> now = timezone.now() + >>> Coalesce("updated", Cast(now, DateTimeField())) ``Collate`` ----------- diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 67769700ad..9f2a417881 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -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 ``QuerySet``\s. For example: +.. code-block:: pycon + >>> qs1.intersection(qs2, qs3) 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``: - >>> 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 ``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 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] ...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 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 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 lookups: +.. code-block:: pycon + >>> 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. This can be used to change the default ordering of the queryset: +.. code-block:: pycon + >>> 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 applicable to reduce the number of queries even further: +.. code-block:: pycon + >>> 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 ``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 ``QuerySet``; for instance: +.. code-block:: pycon + >>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True) >>> Restaurant.objects.prefetch_related( - ... Prefetch('pizzas', to_attr='menu'), - ... Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu')) + ... Prefetch("pizzas", to_attr="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: +.. code-block:: pycon + >>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True) >>> Restaurant.objects.prefetch_related( - ... Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu'), - ... 'vegetarian_menu__toppings') + ... Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"), + ... "vegetarian_menu__toppings", + ... ) 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: +.. code-block:: pycon + >>> queryset = Pizza.objects.filter(vegetarian=True) >>> >>> # Recommended: >>> 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 >>> >>> # Not recommended: >>> restaurants = Restaurant.objects.prefetch_related( - ... Prefetch('pizzas', queryset=queryset)) + ... Prefetch("pizzas", queryset=queryset), + ... ) >>> vegetarian_pizzas = restaurants[0].pizzas.all() 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 :meth:`deferred fields `: - >>> queryset = Pizza.objects.only('name') + .. code-block:: pycon + + >>> queryset = Pizza.objects.only("name") >>> >>> 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 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: - >>> prefetch_related('pizzas__toppings', 'pizzas') + .. code-block:: pycon + + >>> prefetch_related("pizzas__toppings", "pizzas") This works even though it's unordered because ``'pizzas__toppings'`` already contains all the needed information, therefore the second argument ``'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 queryset of a previously seen lookup. Note that an implicit queryset was created to traverse ``'pizzas'`` as part of the ``'pizzas__toppings'`` 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 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 :meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example: +.. code-block:: pycon + >>> 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() , , ]> # This will only execute two queries regardless of the number of Question # and Choice objects. - >>> Question.objects.prefetch_related(Prefetch('choice_set')) + >>> Question.objects.prefetch_related(Prefetch("choice_set")) ]> 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 relation, hence reducing the number of queries even further: +.. code-block:: pycon + >>> voted_choices = Choice.objects.filter(votes__gt=0) >>> voted_choices ]> - >>> prefetch = Prefetch('choice_set', queryset=voted_choices) + >>> prefetch = Prefetch("choice_set", queryset=voted_choices) >>> Question.objects.prefetch_related(prefetch).get().choice_set.all() ]> The ``to_attr`` argument sets the result of the prefetch operation to a custom 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().choice_set.all() diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 1837b4be27..0a73e644da 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -371,12 +371,14 @@ Methods Otherwise the absolute URI is built using the server variables available in this request. For example: - >>> request.build_absolute_uri() - 'https://example.com/music/bands/the_beatles/?print=true' - >>> request.build_absolute_uri('/bands/') - 'https://example.com/bands/' - >>> request.build_absolute_uri('https://example2.com/bands/') - 'https://example2.com/bands/' + .. code-block:: pycon + + >>> request.build_absolute_uri() + 'https://example.com/music/bands/the_beatles/?print=true' + >>> request.build_absolute_uri("/bands/") + 'https://example.com/bands/' + >>> request.build_absolute_uri("https://example2.com/bands/") + 'https://example2.com/bands/' .. note:: @@ -494,8 +496,10 @@ a subclass of dictionary. Exceptions are outlined here: Instantiates a ``QueryDict`` object based on ``query_string``. - >>> QueryDict('a=1&a=2&c=3') - + .. code-block:: pycon + + >>> QueryDict("a=1&a=2&c=3") + If ``query_string`` is not passed in, the resulting ``QueryDict`` will be empty (it will have no keys or values). diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index a095dd5953..26e4ff4c23 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -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()`` is called. +.. code-block:: pycon + >>> c = Context() - >>> c['foo'] = 'first level' + >>> c["foo"] = "first level" >>> with c.push(): - ... c['foo'] = 'second level' - ... c['foo'] + ... c["foo"] = "second level" + ... c["foo"] + ... 'second level' - >>> c['foo'] + >>> c["foo"] 'first level' All arguments passed to ``push()`` will be passed to the ``dict`` constructor used to build the new context level. +.. code-block:: pycon + >>> c = Context() - >>> c['foo'] = 'first level' - >>> with c.push(foo='second level'): - ... c['foo'] + >>> c["foo"] = "first level" + >>> with c.push(foo="second level"): + ... c["foo"] + ... 'second level' - >>> c['foo'] + >>> c["foo"] 'first level' .. 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 the stack instead of an empty one. +.. code-block:: pycon + >>> c = Context() - >>> c['foo'] = 'first level' - >>> c.update({'foo': 'updated'}) + >>> c["foo"] = "first level" + >>> c.update({"foo": "updated"}) {'foo': 'updated'} - >>> c['foo'] + >>> c["foo"] 'updated' >>> c.pop() {'foo': 'updated'} - >>> c['foo'] + >>> c["foo"] 'first level' Like ``push()``, you can use ``update()`` as a context manager to ensure a matching ``pop()`` is called. +.. code-block:: pycon + >>> c = Context() - >>> c['foo'] = 'first level' - >>> with c.update({'foo': 'second level'}): - ... c['foo'] + >>> c["foo"] = "first level" + >>> with c.update({"foo": "second level"}): + ... c["foo"] + ... 'second level' - >>> c['foo'] + >>> c["foo"] 'first level' Using a ``Context`` as a stack comes in handy in :ref:`some custom template @@ -555,20 +566,24 @@ tags `. Using ``flatten()`` method you can get whole ``Context`` stack as one dictionary including builtin variables. +.. code-block:: pycon + >>> c = Context() - >>> c['foo'] = 'first level' - >>> c.update({'bar': 'second level'}) + >>> c["foo"] = "first level" + >>> c.update({"bar": "second level"}) {'bar': 'second level'} >>> c.flatten() {'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'} A ``flatten()`` method is also internally used to make ``Context`` objects comparable. +.. code-block:: pycon + >>> c1 = Context() - >>> c1['foo'] = 'first level' - >>> c1['bar'] = 'second level' + >>> c1["foo"] = "first level" + >>> c1["bar"] = "second level" >>> c2 = Context() - >>> c2.update({'bar': 'second level', 'foo': 'first level'}) + >>> c2.update({"bar": "second level", "foo": "first level"}) {'foo': 'first level', 'bar': 'second level'} >>> c1 == c2 True diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt index abdbea0e0a..5935c3e27f 100644 --- a/docs/topics/cache.txt +++ b/docs/topics/cache.txt @@ -872,9 +872,11 @@ Accessing the cache requests for the same alias in the same thread will return the same object. + .. code-block:: pycon + >>> from django.core.cache import caches - >>> cache1 = caches['myalias'] - >>> cache2 = caches['myalias'] + >>> cache1 = caches["myalias"] + >>> cache2 = caches["myalias"] >>> cache1 is cache2 True @@ -906,11 +908,15 @@ The basic interface is: .. 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) - >>> cache.get('my_key') +.. code-block:: pycon + + >>> cache.get("my_key") 'hello, world!' ``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 the cache backend. +.. code-block:: pycon + >>> cache.close() .. note:: diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 9f98504c0c..cd53f73c74 100644 --- a/docs/topics/db/aggregation.txt +++ b/docs/topics/db/aggregation.txt @@ -222,12 +222,14 @@ Combining multiple aggregations Combining multiple aggregations with ``annotate()`` will :ticket:`yield the wrong results <10060>` because joins are used instead of subqueries: +.. code-block:: pycon + >>> book = Book.objects.first() >>> book.authors.count() 2 >>> book.store_set.count() 3 - >>> q = Book.objects.annotate(Count('authors'), Count('store')) + >>> q = Book.objects.annotate(Count("authors"), Count("store")) >>> q[0].authors__count 6 >>> 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 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 2 >>> 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 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 their average book rating. diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 3f7031c2ab..45c6183103 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -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 key. For example: +.. code-block:: pycon + >>> Entry.objects.filter(blog_id=4) 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 multiple joins to the primary model, potentially yielding duplicates. + .. code-block:: pycon + >>> from datetime import date - >>> beatles = Blog.objects.create(name='Beatles Blog') - >>> pop = Blog.objects.create(name='Pop Music Blog') + >>> beatles = Blog.objects.create(name="Beatles Blog") + >>> pop = Blog.objects.create(name="Pop Music Blog") >>> Entry.objects.create( ... blog=beatles, - ... headline='New Lennon Biography', + ... headline="New Lennon Biography", ... pub_date=date(2008, 6, 1), ... ) >>> Entry.objects.create( ... blog=beatles, - ... headline='New Lennon Biography in Paperback', + ... headline="New Lennon Biography in Paperback", ... pub_date=date(2009, 6, 1), ... ) >>> Entry.objects.create( ... blog=pop, - ... headline='Best Albums of 2008', + ... headline="Best Albums of 2008", ... pub_date=date(2008, 12, 15), ... ) >>> Entry.objects.create( ... blog=pop, - ... headline='Lennon Would Have Loved Hip Hop', + ... headline="Lennon Would Have Loved Hip Hop", ... pub_date=date(2020, 4, 1), ... ) >>> Blog.objects.filter( - ... entry__headline__contains='Lennon', + ... entry__headline__contains="Lennon", ... entry__pub_date__year=2008, ... ) ]> >>> Blog.objects.filter( - ... entry__headline__contains='Lennon', + ... entry__headline__contains="Lennon", ... ).filter( ... entry__pub_date__year=2008, ... )