Skip to content

Commit

Permalink
Added missing pycon directives in various docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@felixxm
felixxm authored Oct 25, 2023
1 parent ee10425 commit 718b32c
Show file tree
Hide file tree
Showing 11 changed files with 295 additions and 130 deletions.
160 changes: 112 additions & 48 deletions docs/ref/contrib/gis/gdal.txt
View file
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
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
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

0 comments on commit 718b32c

Please sign in to comment.