Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added missing pycon directives in various docs. #17409

Merged
merged 1 commit into from
Oct 25, 2023
Merged

Added missing pycon directives in various docs. #17409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 112 additions & 48 deletions docs/ref/contrib/gis/gdal.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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]

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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()
Expand Down Expand Up @@ -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.],
Expand Down Expand Up @@ -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
Expand All @@ -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'}}

Expand Down Expand Up @@ -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()
Expand All @@ -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],
Expand Down
16 changes: 10 additions & 6 deletions docs/ref/contrib/postgres/search.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
21 changes: 17 additions & 4 deletions docs/ref/forms/api.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.'])]}
Expand All @@ -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"}]}
Expand Down Expand Up @@ -325,17 +329,23 @@ 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

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()

Expand All @@ -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']

Expand Down
Loading
Loading