From 23e1ad537a5ce4b765f88ab5d2bfee06f773f8c9 Mon Sep 17 00:00:00 2001 From: Sergey Fedoseev Date: Fri, 19 Feb 2016 12:31:25 +0500 Subject: [PATCH] Fixed #25974 -- Switched GIS docs to 4 spaces indentation. --- docs/ref/contrib/gis/admin.txt | 64 +- docs/ref/contrib/gis/commands.txt | 58 +- docs/ref/contrib/gis/db-api.txt | 14 +- docs/ref/contrib/gis/feeds.txt | 34 +- docs/ref/contrib/gis/forms-api.txt | 4 +- docs/ref/contrib/gis/gdal.txt | 1212 +++++++++++----------- docs/ref/contrib/gis/geoip.txt | 44 +- docs/ref/contrib/gis/geoip2.txt | 40 +- docs/ref/contrib/gis/geoquerysets.txt | 6 +- docs/ref/contrib/gis/geos.txt | 232 ++--- docs/ref/contrib/gis/index.txt | 42 +- docs/ref/contrib/gis/install/geolibs.txt | 17 +- docs/ref/contrib/gis/install/index.txt | 26 +- docs/ref/contrib/gis/layermapping.txt | 2 +- docs/ref/contrib/gis/measure.txt | 62 +- docs/ref/contrib/gis/model-api.txt | 2 +- docs/ref/contrib/gis/ogrinspect.txt | 2 +- docs/ref/contrib/gis/serializers.txt | 2 +- docs/ref/contrib/gis/utils.txt | 10 +- 19 files changed, 929 insertions(+), 944 deletions(-) diff --git a/docs/ref/contrib/gis/admin.txt b/docs/ref/contrib/gis/admin.txt index 732b963fd4..834a072026 100644 --- a/docs/ref/contrib/gis/admin.txt +++ b/docs/ref/contrib/gis/admin.txt @@ -3,67 +3,67 @@ GeoDjango's admin site ====================== .. module:: django.contrib.gis.admin - :synopsis: GeoDjango's extensions to the admin site. + :synopsis: GeoDjango's extensions to the admin site. ``GeoModelAdmin`` ================= .. class:: GeoModelAdmin - .. attribute:: default_lon + .. attribute:: default_lon - The default center longitude. + The default center longitude. - .. attribute:: default_lat + .. attribute:: default_lat - The default center latitude. + The default center latitude. - .. attribute:: default_zoom + .. attribute:: default_zoom - The default zoom level to use. Defaults to 18. + The default zoom level to use. Defaults to 18. - .. attribute:: extra_js + .. attribute:: extra_js - Sequence of URLs to any extra JavaScript to include. + Sequence of URLs to any extra JavaScript to include. - .. attribute:: map_template + .. attribute:: map_template - Override the template used to generate the JavaScript slippy map. - Default is ``'gis/admin/openlayers.html'``. + Override the template used to generate the JavaScript slippy map. + Default is ``'gis/admin/openlayers.html'``. - .. attribute:: map_width + .. attribute:: map_width - Width of the map, in pixels. Defaults to 600. + Width of the map, in pixels. Defaults to 600. - .. attribute:: map_height + .. attribute:: map_height - Height of the map, in pixels. Defaults to 400. + Height of the map, in pixels. Defaults to 400. - .. attribute:: openlayers_url + .. attribute:: openlayers_url - Link to the URL of the OpenLayers JavaScript. Defaults to - ``'http://openlayers.org/api/2.13.1/OpenLayers.js'``. + Link to the URL of the OpenLayers JavaScript. Defaults to + ``'http://openlayers.org/api/2.13.1/OpenLayers.js'``. - .. attribute:: modifiable + .. attribute:: modifiable - Defaults to ``True``. When set to ``False``, disables editing of - existing geometry fields in the admin. + Defaults to ``True``. When set to ``False``, disables editing of + existing geometry fields in the admin. - .. note:: + .. note:: - This is different from adding the geometry field to - :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`, - which will only display the WKT of the geometry. Setting - ``modifiable=False``, actually displays the geometry in a map, - but disables the ability to edit its vertices. + This is different from adding the geometry field to + :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`, + which will only display the WKT of the geometry. Setting + ``modifiable=False``, actually displays the geometry in a map, + but disables the ability to edit its vertices. ``OSMGeoAdmin`` =============== .. class:: OSMGeoAdmin - A subclass of :class:`GeoModelAdmin` that uses a spherical mercator projection - with `OpenStreetMap `_ street data tiles. - See the :ref:`OSMGeoAdmin introduction ` - in the tutorial for a usage example. + A subclass of :class:`GeoModelAdmin` that uses a spherical mercator projection + with `OpenStreetMap `_ street data tiles. + See the :ref:`OSMGeoAdmin introduction ` + in the tutorial for a usage example. diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index 719edac03e..77fa915396 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -24,59 +24,59 @@ of using ``ogrinspect`` :ref:`in the tutorial `. .. django-admin-option:: --blank BLANK - Use a comma separated list of OGR field names to add the ``blank=True`` - keyword option to the field definition. Set with ``true`` to apply - to all applicable fields. + Use a comma separated list of OGR field names to add the ``blank=True`` + keyword option to the field definition. Set with ``true`` to apply + to all applicable fields. .. django-admin-option:: --decimal DECIMAL - Use a comma separated list of OGR float fields to generate - :class:`~django.db.models.DecimalField` instead of the default - :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all - OGR float fields. + Use a comma separated list of OGR float fields to generate + :class:`~django.db.models.DecimalField` instead of the default + :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all + OGR float fields. .. django-admin-option:: --geom-name GEOM_NAME - Specifies the model attribute name to use for the geometry field. - Defaults to ``'geom'``. + Specifies the model attribute name to use for the geometry field. + Defaults to ``'geom'``. .. django-admin-option:: --layer LAYER_KEY - The key for specifying which layer in the OGR - :class:`~django.contrib.gis.gdal.DataSource` source to use. - Defaults to 0 (the first layer). May be an integer or a string identifier - for the :class:`~django.contrib.gis.gdal.Layer`. When inspecting databases, - ``layer`` is generally the table name you want to inspect. + The key for specifying which layer in the OGR + :class:`~django.contrib.gis.gdal.DataSource` source to use. + Defaults to 0 (the first layer). May be an integer or a string identifier + for the :class:`~django.contrib.gis.gdal.Layer`. When inspecting databases, + ``layer`` is generally the table name you want to inspect. .. django-admin-option:: --mapping - Automatically generate a mapping dictionary for use with - :class:`~django.contrib.gis.utils.LayerMapping`. + Automatically generate a mapping dictionary for use with + :class:`~django.contrib.gis.utils.LayerMapping`. .. django-admin-option:: --multi-geom - When generating the geometry field, treat it as a geometry collection. - For example, if this setting is enabled then a - :class:`~django.contrib.gis.db.models.MultiPolygonField` will be placed - in the generated model rather than - :class:`~django.contrib.gis.db.models.PolygonField`. + When generating the geometry field, treat it as a geometry collection. + For example, if this setting is enabled then a + :class:`~django.contrib.gis.db.models.MultiPolygonField` will be placed + in the generated model rather than + :class:`~django.contrib.gis.db.models.PolygonField`. .. django-admin-option:: --name-field NAME_FIELD - Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model - that will return the given field name. + Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model + that will return the given field name. .. django-admin-option:: --no-imports - Suppresses the ``from django.contrib.gis.db import models`` import statement. + Suppresses the ``from django.contrib.gis.db import models`` import statement. .. django-admin-option:: --null NULL - Use a comma separated list of OGR field names to add the ``null=True`` - keyword option to the field definition. Set with ``true`` to apply to - all applicable fields. + Use a comma separated list of OGR field names to add the ``null=True`` + keyword option to the field definition. Set with ``true`` to apply to + all applicable fields. .. django-admin-option:: --srid SRID - The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts - to automatically determine of the SRID of the data source. + The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts + to automatically determine of the SRID of the data source. diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index 3eebe4e1f8..49a5cb7a85 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -8,7 +8,7 @@ Spatial Backends ================ .. module:: django.contrib.gis.db.backends - :synopsis: GeoDjango's spatial database backends. + :synopsis: GeoDjango's spatial database backends. GeoDjango currently provides the following spatial database backends: @@ -18,7 +18,7 @@ GeoDjango currently provides the following spatial database backends: * ``django.contrib.gis.db.backends.spatialite`` .. module:: django.contrib.gis.db.models - :synopsis: GeoDjango's database API. + :synopsis: GeoDjango's database API. .. _mysql-spatial-limitations: @@ -297,7 +297,7 @@ Database functions ------------------ .. module:: django.contrib.gis.db.models.functions - :synopsis: GeoDjango's database functions. + :synopsis: GeoDjango's database functions. The following table provides a summary of what geography-specific database functions are available on each spatial backend. @@ -360,9 +360,9 @@ Aggregate PostGIS Oracle SpatiaLite .. [#fnmysqlidx] *See* `Creating Spatial Indexes `_ in the MySQL Reference Manual: - For MyISAM tables, ``SPATIAL INDEX`` creates an R-tree index. For storage - engines that support nonspatial indexing of spatial columns, the engine - creates a B-tree index. A B-tree index on spatial values will be useful - for exact-value lookups, but not for range scans. + For MyISAM tables, ``SPATIAL INDEX`` creates an R-tree index. For storage + engines that support nonspatial indexing of spatial columns, the engine + creates a B-tree index. A B-tree index on spatial values will be useful + for exact-value lookups, but not for range scans. .. [#] Refer :ref:`mysql-spatial-limitations` section for more details. diff --git a/docs/ref/contrib/gis/feeds.txt b/docs/ref/contrib/gis/feeds.txt index 49c8f97c1f..4f9b5894b0 100644 --- a/docs/ref/contrib/gis/feeds.txt +++ b/docs/ref/contrib/gis/feeds.txt @@ -3,7 +3,7 @@ Geographic Feeds ================ .. module:: django.contrib.gis.feeds - :synopsis: GeoDjango's framework for generating spatial feeds. + :synopsis: GeoDjango's framework for generating spatial feeds. GeoDjango has its own :class:`Feed` subclass that may embed location information in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or @@ -26,10 +26,10 @@ API Reference .. class:: Feed - In addition to methods provided by - the :class:`django.contrib.syndication.views.Feed` - base class, GeoDjango's ``Feed`` class provides - the following overrides. Note that these overrides may be done in multiple ways:: + In addition to methods provided by the + :class:`django.contrib.syndication.views.Feed` base class, GeoDjango's + ``Feed`` class provides the following overrides. Note that these overrides + may be done in multiple ways:: from django.contrib.gis.feeds import Feed @@ -53,23 +53,23 @@ API Reference def item_geometry(self, item): ... - .. method:: geometry(obj) + .. method:: geometry(obj) - Takes the object returned by ``get_object()`` and returns the *feed's* - geometry. Typically this is a ``GEOSGeometry`` instance, or can be a - tuple to represent a point or a box. For example:: + Takes the object returned by ``get_object()`` and returns the *feed's* + geometry. Typically this is a ``GEOSGeometry`` instance, or can be a tuple + to represent a point or a box. For example:: - class ZipcodeFeed(Feed): + class ZipcodeFeed(Feed): - def geometry(self, obj): - # Can also return: `obj.poly`, and `obj.poly.centroid`. - return obj.poly.extent # tuple like: (X0, Y0, X1, Y1). + def geometry(self, obj): + # Can also return: `obj.poly`, and `obj.poly.centroid`. + return obj.poly.extent # tuple like: (X0, Y0, X1, Y1). - .. method:: item_geometry(item) + .. method:: item_geometry(item) - Set this to return the geometry for each *item* in the feed. This - can be a ``GEOSGeometry`` instance, or a tuple that represents a - point coordinate or bounding box. For example:: + Set this to return the geometry for each *item* in the feed. This can be a + ``GEOSGeometry`` instance, or a tuple that represents a point coordinate or + bounding box. For example:: class ZipcodeFeed(Feed): diff --git a/docs/ref/contrib/gis/forms-api.txt b/docs/ref/contrib/gis/forms-api.txt index c2593acba6..7580fac86a 100644 --- a/docs/ref/contrib/gis/forms-api.txt +++ b/docs/ref/contrib/gis/forms-api.txt @@ -3,7 +3,7 @@ GeoDjango Forms API =================== .. module:: django.contrib.gis.forms - :synopsis: GeoDjango forms API. + :synopsis: GeoDjango forms API. GeoDjango provides some specialized form fields and widgets in order to visually display and edit geolocalized data on a map. By default, they use @@ -83,7 +83,7 @@ Form widgets ============ .. module:: django.contrib.gis.widgets - :synopsis: GeoDjango widgets API. + :synopsis: GeoDjango widgets API. GeoDjango form widgets allow you to display and edit geographic data on a visual map. diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index 0d5af4aaca..b15bd17d54 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/docs/ref/contrib/gis/gdal.txt @@ -3,7 +3,7 @@ GDAL API ======== .. module:: django.contrib.gis.gdal - :synopsis: GeoDjango's high-level interface to the GDAL library. + :synopsis: GeoDjango's high-level interface to the GDAL library. `GDAL`__ stands for **Geospatial Data Abstraction Library**, and is a veritable "Swiss army knife" of GIS data functionality. A subset @@ -18,8 +18,8 @@ to raster (image) data. .. note:: - Although the module is named ``gdal``, GeoDjango only supports - some of the capabilities of OGR and GDAL's raster features at this time. + Although the module is named ``gdal``, GeoDjango only supports some of the + capabilities of OGR and GDAL's raster features at this time. __ http://www.gdal.org/ __ http://www.gdal.org/ogr_arch.html @@ -60,39 +60,37 @@ each feature in that layer. .. class:: DataSource(ds_input, encoding='utf-8') - The constructor for ``DataSource`` only requires one parameter: the path of - the file you want to read. However, OGR - also supports a variety of more complex data sources, including - databases, that may be accessed by passing a special name string instead - of a path. For more information, see the `OGR Vector Formats`__ - documentation. The :attr:`name` property of a ``DataSource`` - instance gives the OGR name of the underlying data source that it is - using. + The constructor for ``DataSource`` only requires one parameter: the path of + the file you want to read. However, OGR also supports a variety of more + complex data sources, including databases, that may be accessed by passing + a special name string instead of a path. For more information, see the + `OGR Vector Formats`__ documentation. The :attr:`name` property of a + ``DataSource`` instance gives the OGR name of the underlying data source + that it is using. - The optional ``encoding`` parameter allows you to - specify a non-standard encoding of the strings in the source. This is - typically useful when you obtain ``DjangoUnicodeDecodeError`` exceptions - while reading field values. + The optional ``encoding`` parameter allows you to specify a non-standard + encoding of the strings in the source. This is typically useful when you + obtain ``DjangoUnicodeDecodeError`` exceptions while reading field values. - Once you've created your ``DataSource``, you can find out how many - layers of data it contains by accessing the :attr:`layer_count` property, - or (equivalently) by using the ``len()`` function. For information on - accessing the layers of data themselves, see the next section:: + Once you've created your ``DataSource``, you can find out how many layers + of data it contains by accessing the :attr:`layer_count` property, or + (equivalently) by using the ``len()`` function. For information on + accessing the layers of data themselves, see the next section:: - >>> from django.contrib.gis.gdal import DataSource - >>> ds = DataSource('/path/to/your/cities.shp') - >>> ds.name - '/path/to/your/cities.shp' - >>> ds.layer_count # This file only contains one layer - 1 + >>> from django.contrib.gis.gdal import DataSource + >>> ds = DataSource('/path/to/your/cities.shp') + >>> ds.name + '/path/to/your/cities.shp' + >>> ds.layer_count # This file only contains one layer + 1 - .. attribute:: layer_count + .. attribute:: layer_count - Returns the number of layers in the data source. + Returns the number of layers in the data source. - .. attribute:: name + .. attribute:: name - Returns the name of the data source. + Returns the name of the data source. __ http://www.gdal.org/ogr_formats.html @@ -101,333 +99,327 @@ __ http://www.gdal.org/ogr_formats.html .. class:: Layer - ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object. - You never create a ``Layer`` object directly. Instead, you retrieve - them from a :class:`DataSource` object, which is essentially a standard - Python container of ``Layer`` objects. For example, you can access a - specific layer by its index (e.g. ``ds[0]`` to access the first - layer), or you can iterate over all the layers in the container in a - ``for`` loop. The ``Layer`` itself acts as a container for geometric - features. + ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object. You + never create a ``Layer`` object directly. Instead, you retrieve them from + a :class:`DataSource` object, which is essentially a standard Python + container of ``Layer`` objects. For example, you can access a specific + layer by its index (e.g. ``ds[0]`` to access the first layer), or you can + iterate over all the layers in the container in a ``for`` loop. The + ``Layer`` itself acts as a container for geometric features. - Typically, all the features in a given layer have the same geometry type. - The :attr:`geom_type` property of a layer is an :class:`OGRGeomType` - that identifies the feature type. We can use it to print out some basic - information about each layer in a :class:`DataSource`:: + Typically, all the features in a given layer have the same geometry type. + The :attr:`geom_type` property of a layer is an :class:`OGRGeomType` that + identifies the feature type. We can use it to print out some basic + information about each layer in a :class:`DataSource`:: - >>> for layer in ds: - ... print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)) - ... - Layer "cities": 3 Points + >>> for layer in ds: + ... print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)) + ... + Layer "cities": 3 Points - The example output is from the cities data source, loaded above, which - evidently contains one layer, called ``"cities"``, which contains three - point features. For simplicity, the examples below assume that you've - stored that layer in the variable ``layer``:: + The example output is from the cities data source, loaded above, which + evidently contains one layer, called ``"cities"``, which contains three + point features. For simplicity, the examples below assume that you've + stored that layer in the variable ``layer``:: - >>> layer = ds[0] + >>> layer = ds[0] - .. attribute:: name + .. attribute:: name - Returns the name of this layer in the data source. + Returns the name of this layer in the data source. - >>> layer.name - 'cities' + >>> layer.name + 'cities' - .. attribute:: num_feat + .. attribute:: num_feat - Returns the number of features in the layer. Same as ``len(layer)``:: + Returns the number of features in the layer. Same as ``len(layer)``:: - >>> layer.num_feat - 3 + >>> layer.num_feat + 3 - .. attribute:: geom_type + .. attribute:: geom_type - Returns the geometry type of the layer, as an :class:`OGRGeomType` - object:: + Returns the geometry type of the layer, as an :class:`OGRGeomType` object:: - >>> layer.geom_type.name - 'Point' + >>> layer.geom_type.name + 'Point' - .. attribute:: num_fields + .. attribute:: num_fields - Returns the number of fields in the layer, i.e the number of fields of - data associated with each feature in the layer:: + Returns the number of fields in the layer, i.e the number of fields of + data associated with each feature in the layer:: - >>> layer.num_fields - 4 + >>> layer.num_fields + 4 - .. attribute:: fields + .. attribute:: fields - Returns a list of the names of each of the fields in this layer:: + Returns a list of the names of each of the fields in this layer:: - >>> layer.fields - ['Name', 'Population', 'Density', 'Created'] + >>> layer.fields + ['Name', 'Population', 'Density', 'Created'] - .. attribute field_types + .. attribute field_types - Returns a list of the data types of each of the fields in this layer. - These are subclasses of ``Field``, discussed below:: + Returns a list of the data types of each of the fields in this layer. These + are subclasses of ``Field``, discussed below:: - >>> [ft.__name__ for ft in layer.field_types] - ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] + >>> [ft.__name__ for ft in layer.field_types] + ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] - .. attribute:: field_widths + .. attribute:: field_widths - Returns a list of the maximum field widths for each of the fields in - this layer:: + Returns a list of the maximum field widths for each of the fields in this + layer:: - >>> layer.field_widths - [80, 11, 24, 10] + >>> layer.field_widths + [80, 11, 24, 10] - .. attribute:: field_precisions + .. attribute:: field_precisions - Returns a list of the numeric precisions for each of the fields in - this layer. This is meaningless (and set to zero) for non-numeric - fields:: + Returns a list of the numeric precisions for each of the fields in this + layer. This is meaningless (and set to zero) for non-numeric fields:: - >>> layer.field_precisions - [0, 0, 15, 0] + >>> layer.field_precisions + [0, 0, 15, 0] - .. attribute:: extent + .. attribute:: extent - Returns the spatial extent of this layer, as an :class:`Envelope` - object:: + Returns the spatial extent of this layer, as an :class:`Envelope` object:: - >>> layer.extent.tuple - (-104.609252, 29.763374, -95.23506, 38.971823) + >>> layer.extent.tuple + (-104.609252, 29.763374, -95.23506, 38.971823) - .. attribute:: srs + .. attribute:: srs - Property that returns the :class:`SpatialReference` associated - with this layer:: + Property that returns the :class:`SpatialReference` associated with this + layer:: - >>> print(layer.srs) - GEOGCS["GCS_WGS_1984", - DATUM["WGS_1984", - SPHEROID["WGS_1984",6378137,298.257223563]], - PRIMEM["Greenwich",0], - UNIT["Degree",0.017453292519943295]] + >>> print(layer.srs) + GEOGCS["GCS_WGS_1984", + DATUM["WGS_1984", + SPHEROID["WGS_1984",6378137,298.257223563]], + PRIMEM["Greenwich",0], + UNIT["Degree",0.017453292519943295]] - If the :class:`Layer` has no spatial reference information associated - with it, ``None`` is returned. + If the :class:`Layer` has no spatial reference information associated + with it, ``None`` is returned. - .. attribute:: spatial_filter + .. attribute:: spatial_filter - Property that may be used to retrieve or set a spatial filter for this - layer. A spatial filter can only be set with an :class:`OGRGeometry` - instance, a 4-tuple extent, or ``None``. When set with something - other than ``None``, only features that intersect the filter will be - returned when iterating over the layer:: + Property that may be used to retrieve or set a spatial filter for this + layer. A spatial filter can only be set with an :class:`OGRGeometry` + instance, a 4-tuple extent, or ``None``. When set with something other than + ``None``, only features that intersect the filter will be returned when + iterating over the layer:: - >>> print(layer.spatial_filter) - None - >>> print(len(layer)) - 3 - >>> [feat.get('Name') for feat in layer] - ['Pueblo', 'Lawrence', 'Houston'] - >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas - >>> layer.spatial_filter = ks_extent - >>> len(layer) - 1 - >>> [feat.get('Name') for feat in layer] - ['Lawrence'] - >>> layer.spatial_filter = None - >>> len(layer) - 3 + >>> print(layer.spatial_filter) + None + >>> print(len(layer)) + 3 + >>> [feat.get('Name') for feat in layer] + ['Pueblo', 'Lawrence', 'Houston'] + >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas + >>> layer.spatial_filter = ks_extent + >>> len(layer) + 1 + >>> [feat.get('Name') for feat in layer] + ['Lawrence'] + >>> layer.spatial_filter = None + >>> len(layer) + 3 - .. method:: get_fields() + .. method:: get_fields() - A method that returns a list of the values of a given field for each - feature in the layer:: + A method that returns a list of the values of a given field for each + feature in the layer:: - >>> layer.get_fields('Name') - ['Pueblo', 'Lawrence', 'Houston'] + >>> layer.get_fields('Name') + ['Pueblo', 'Lawrence', 'Houston'] - .. method:: get_geoms(geos=False) + .. method:: get_geoms(geos=False) - A method that returns a list containing the geometry of each feature - in the layer. If the optional argument ``geos`` is set to ``True`` - then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry` - objects. Otherwise, they are returned as :class:`OGRGeometry` objects:: + A method that returns a list containing the geometry of each feature in the + layer. If the optional argument ``geos`` is set to ``True`` then the + geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry` + objects. Otherwise, they are returned as :class:`OGRGeometry` objects:: - >>> [pt.tuple for pt in layer.get_geoms()] - [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)] + >>> [pt.tuple for pt in layer.get_geoms()] + [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)] - .. method:: test_capability(capability) + .. method:: test_capability(capability) - Returns a boolean indicating whether this layer supports the - given capability (a string). Examples of valid capability strings - include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``, - ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``, - ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and - ``'FastSetNextByIndex'``. + Returns a boolean indicating whether this layer supports the given + capability (a string). Examples of valid capability strings include: + ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``, + ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``, + ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and + ``'FastSetNextByIndex'``. ``Feature`` ----------- .. class:: Feature + ``Feature`` wraps an OGR feature. You never create a ``Feature`` object + directly. Instead, you retrieve them from a :class:`Layer` object. Each + feature consists of a geometry and a set of fields containing additional + properties. The geometry of a field is accessible via its ``geom`` property, + which returns an :class:`OGRGeometry` object. A ``Feature`` behaves like a + standard Python container for its fields, which it returns as :class:`Field` + objects: you can access a field directly by its index or name, or you can + iterate over a feature's fields, e.g. in a ``for`` loop. - ``Feature`` wraps an OGR feature. You never create a ``Feature`` - object directly. Instead, you retrieve them from a :class:`Layer` object. - Each feature consists of a geometry and a set of fields containing - additional properties. The geometry of a field is accessible via its - ``geom`` property, which returns an :class:`OGRGeometry` object. A ``Feature`` - behaves like a standard Python container for its fields, which it returns as - :class:`Field` objects: you can access a field directly by its index or name, - or you can iterate over a feature's fields, e.g. in a ``for`` loop. + .. attribute:: geom - .. attribute:: geom + Returns the geometry for this feature, as an ``OGRGeometry`` object:: - Returns the geometry for this feature, as an ``OGRGeometry`` object:: + >>> city.geom.tuple + (-104.609252, 38.255001) - >>> city.geom.tuple - (-104.609252, 38.255001) + .. attribute:: get - .. attribute:: get + A method that returns the value of the given field (specified by name) + for this feature, **not** a ``Field`` wrapper object:: - A method that returns the value of the given field (specified by name) - for this feature, **not** a ``Field`` wrapper object:: + >>> city.get('Population') + 102121 - >>> city.get('Population') - 102121 + .. attribute:: geom_type - .. attribute:: geom_type + Returns the type of geometry for this feature, as an :class:`OGRGeomType` + object. This will be the same for all features in a given layer and is + equivalent to the :attr:`Layer.geom_type` property of the :class:`Layer` + object the feature came from. - Returns the type of geometry for this feature, as an :class:`OGRGeomType` - object. This will be the same for all features in a given layer, and - is equivalent to the :attr:`Layer.geom_type` property of the - :class:`Layer` object the feature came from. + .. attribute:: num_fields - .. attribute:: num_fields + Returns the number of fields of data associated with the feature. This will + be the same for all features in a given layer and is equivalent to the + :attr:`Layer.num_fields` property of the :class:`Layer` object the feature + came from. - Returns the number of fields of data associated with the feature. - This will be the same for all features in a given layer, and is - equivalent to the :attr:`Layer.num_fields` property of the - :class:`Layer` object the feature came from. + .. attribute:: fields - .. attribute:: fields + Returns a list of the names of the fields of data associated with the + feature. This will be the same for all features in a given layer and is + equivalent to the :attr:`Layer.fields` property of the :class:`Layer` + object the feature came from. - Returns a list of the names of the fields of data associated with the - feature. This will be the same for all features in a given layer, and - is equivalent to the :attr:`Layer.fields` property of the :class:`Layer` - object the feature came from. + .. attribute:: fid - .. attribute:: fid + Returns the feature identifier within the layer:: - Returns the feature identifier within the layer:: + >>> city.fid + 0 - >>> city.fid - 0 + .. attribute:: layer_name - .. attribute:: layer_name + Returns the name of the :class:`Layer` that the feature came from. This + will be the same for all features in a given layer:: - Returns the name of the :class:`Layer` that the feature came from. - This will be the same for all features in a given layer:: + >>> city.layer_name + 'cities' - >>> city.layer_name - 'cities' + .. attribute:: index - .. attribute:: index + A method that returns the index of the given field name. This will be the + same for all features in a given layer:: - A method that returns the index of the given field name. This will be - the same for all features in a given layer:: - - >>> city.index('Population') - 1 + >>> city.index('Population') + 1 ``Field`` --------- .. class:: Field - .. attribute:: name + .. attribute:: name - Returns the name of this field:: + Returns the name of this field:: - >>> city['Name'].name - 'Name' + >>> city['Name'].name + 'Name' - .. attribute:: type + .. attribute:: type - Returns the OGR type of this field, as an integer. The - ``FIELD_CLASSES`` dictionary maps these values onto - subclasses of ``Field``:: + Returns the OGR type of this field, as an integer. The ``FIELD_CLASSES`` + dictionary maps these values onto subclasses of ``Field``:: - >>> city['Density'].type - 2 + >>> city['Density'].type + 2 - .. attribute:: type_name + .. attribute:: type_name - Returns a string with the name of the data type of this field:: + Returns a string with the name of the data type of this field:: - >>> city['Name'].type_name - 'String' + >>> city['Name'].type_name + 'String' - .. attribute:: value + .. attribute:: value - Returns the value of this field. The ``Field`` class itself - returns the value as a string, but each subclass returns the - value in the most appropriate form:: + Returns the value of this field. The ``Field`` class itself returns the + value as a string, but each subclass returns the value in the most + appropriate form:: - >>> city['Population'].value - 102121 + >>> city['Population'].value + 102121 - .. attribute:: width + .. attribute:: width - Returns the width of this field:: + Returns the width of this field:: - >>> city['Name'].width - 80 + >>> city['Name'].width + 80 - .. attribute:: precision + .. attribute:: precision - Returns the numeric precision of this field. This is meaningless (and - set to zero) for non-numeric fields:: + Returns the numeric precision of this field. This is meaningless (and set + to zero) for non-numeric fields:: - >>> city['Density'].precision - 15 + >>> city['Density'].precision + 15 - .. method:: as_double() + .. method:: as_double() - Returns the value of the field as a double (float):: + Returns the value of the field as a double (float):: - >>> city['Density'].as_double() - 874.7 + >>> city['Density'].as_double() + 874.7 - .. method:: as_int() + .. method:: as_int() - Returns the value of the field as an integer:: + Returns the value of the field as an integer:: - >>> city['Population'].as_int() - 102121 + >>> city['Population'].as_int() + 102121 - .. method:: as_string() + .. method:: as_string() - Returns the value of the field as a string:: + Returns the value of the field as a string:: - >>> city['Name'].as_string() - 'Pueblo' + >>> city['Name'].as_string() + 'Pueblo' - .. method:: as_datetime() + .. method:: as_datetime() - Returns the value of the field as a tuple of date and time components:: + Returns the value of the field as a tuple of date and time components:: - >>> city['Created'].as_datetime() - (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0)) + >>> city['Created'].as_datetime() + (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0)) ``Driver`` ---------- .. class:: Driver(dr_input) - The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver. + The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` + driver. - .. attribute:: driver_count - - Returns the number of OGR vector drivers currently registered. + .. attribute:: driver_count + Returns the number of OGR vector drivers currently registered. OGR Geometries ============== @@ -436,446 +428,441 @@ OGR Geometries --------------- :class:`OGRGeometry` objects share similar functionality with -:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin -wrappers around OGR's internal geometry representation. Thus, -they allow for more efficient access to data when using :class:`DataSource`. -Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference -systems and coordinate transformation:: +:class:`~django.contrib.gis.geos.GEOSGeometry` objects and are thin wrappers +around OGR's internal geometry representation. Thus, they allow for more +efficient access to data when using :class:`DataSource`. Unlike its GEOS +counterpart, :class:`OGRGeometry` supports spatial reference systems and +coordinate transformation:: >>> from django.contrib.gis.gdal import OGRGeometry >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))') .. class:: OGRGeometry(geom_input, srs=None) - This object is a wrapper for the `OGR Geometry`__ class. - These objects are instantiated directly from the given ``geom_input`` - parameter, which may be a string containing WKT, HEX, GeoJSON, a ``buffer`` - containing WKB data, or an :class:`OGRGeomType` object. These objects - are also returned from the :class:`Feature.geom` attribute, when - reading vector data from :class:`Layer` (which is in turn a part of - a :class:`DataSource`). + This object is a wrapper for the `OGR Geometry`__ class. These objects are + instantiated directly from the given ``geom_input`` parameter, which may be + a string containing WKT, HEX, GeoJSON, a ``buffer`` containing WKB data, or + an :class:`OGRGeomType` object. These objects are also returned from the + :class:`Feature.geom` attribute, when reading vector data from + :class:`Layer` (which is in turn a part of a :class:`DataSource`). - __ http://www.gdal.org/classOGRGeometry.html + __ http://www.gdal.org/classOGRGeometry.html - .. classmethod:: from_bbox(bbox) + .. classmethod:: from_bbox(bbox) - Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple). + Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple). - .. method:: __len__() + .. method:: __len__() - Returns the number of points in a :class:`LineString`, the - number of rings in a :class:`Polygon`, or the number of geometries in a - :class:`GeometryCollection`. Not applicable to other geometry types. + Returns the number of points in a :class:`LineString`, the number of rings + in a :class:`Polygon`, or the number of geometries in a + :class:`GeometryCollection`. Not applicable to other geometry types. - .. method:: __iter__() + .. method:: __iter__() - Iterates over the points in a :class:`LineString`, the rings in a - :class:`Polygon`, or the geometries in a :class:`GeometryCollection`. - Not applicable to other geometry types. + Iterates over the points in a :class:`LineString`, the rings in a + :class:`Polygon`, or the geometries in a :class:`GeometryCollection`. + Not applicable to other geometry types. - .. method:: __getitem__() + .. method:: __getitem__() - Returns the point at the specified index for a :class:`LineString`, the - interior ring at the specified index for a :class:`Polygon`, or the geometry - at the specified index in a :class:`GeometryCollection`. Not applicable to - other geometry types. + Returns the point at the specified index for a :class:`LineString`, the + interior ring at the specified index for a :class:`Polygon`, or the geometry + at the specified index in a :class:`GeometryCollection`. Not applicable to + other geometry types. - .. attribute:: dimension + .. attribute:: dimension - Returns the number of coordinated dimensions of the geometry, i.e. 0 - for points, 1 for lines, and so forth:: + Returns the number of coordinated dimensions of the geometry, i.e. 0 + for points, 1 for lines, and so forth:: - >> polygon.dimension - 2 + >> polygon.dimension + 2 - .. attribute:: coord_dim + .. attribute:: coord_dim - Returns or sets the coordinate dimension of this geometry. For - example, the value would be 2 for two-dimensional geometries. + Returns or sets the coordinate dimension of this geometry. For example, the + value would be 2 for two-dimensional geometries. - .. attribute:: geom_count + .. attribute:: geom_count - Returns the number of elements in this geometry:: + Returns the number of elements in this geometry:: - >>> polygon.geom_count - 1 + >>> polygon.geom_count + 1 - .. attribute:: point_count + .. attribute:: point_count - Returns the number of points used to describe this geometry:: + Returns the number of points used to describe this geometry:: - >>> polygon.point_count - 4 + >>> polygon.point_count + 4 - .. attribute:: num_points + .. attribute:: num_points - Alias for :attr:`point_count`. + Alias for :attr:`point_count`. - .. attribute:: num_coords + .. attribute:: num_coords - Alias for :attr:`point_count`. + Alias for :attr:`point_count`. - .. attribute:: geom_type + .. attribute:: geom_type - Returns the type of this geometry, as an :class:`OGRGeomType` object. + Returns the type of this geometry, as an :class:`OGRGeomType` object. - .. attribute:: geom_name + .. attribute:: geom_name - Returns the name of the type of this geometry:: + Returns the name of the type of this geometry:: - >>> polygon.geom_name - 'POLYGON' + >>> polygon.geom_name + 'POLYGON' - .. attribute:: area + .. attribute:: area - Returns the area of this geometry, or 0 for geometries that do not - contain an area:: + Returns the area of this geometry, or 0 for geometries that do not contain + an area:: - >>> polygon.area - 25.0 + >>> polygon.area + 25.0 - .. attribute:: envelope + .. attribute:: envelope - Returns the envelope of this geometry, as an :class:`Envelope` object. + Returns the envelope of this geometry, as an :class:`Envelope` object. - .. attribute:: extent + .. attribute:: extent - Returns the envelope of this geometry as a 4-tuple, instead of as an - :class:`Envelope` object:: + Returns the envelope of this geometry as a 4-tuple, instead of as an + :class:`Envelope` object:: - >>> point.extent - (0.0, 0.0, 5.0, 5.0) + >>> point.extent + (0.0, 0.0, 5.0, 5.0) - .. attribute:: srs + .. attribute:: srs - This property controls the spatial reference for this geometry, or - ``None`` if no spatial reference system has been assigned to it. - If assigned, accessing this property returns a :class:`SpatialReference` - object. It may be set with another :class:`SpatialReference` object, - or any input that :class:`SpatialReference` accepts. Example:: + This property controls the spatial reference for this geometry, or + ``None`` if no spatial reference system has been assigned to it. + If assigned, accessing this property returns a :class:`SpatialReference` + object. It may be set with another :class:`SpatialReference` object, + or any input that :class:`SpatialReference` accepts. Example:: - >>> city.geom.srs.name - 'GCS_WGS_1984' + >>> city.geom.srs.name + 'GCS_WGS_1984' - .. attribute:: srid + .. attribute:: srid - Returns or sets the spatial reference identifier corresponding to - :class:`SpatialReference` of this geometry. Returns ``None`` if - there is no spatial reference information associated with this - geometry, or if an SRID cannot be determined. + Returns or sets the spatial reference identifier corresponding to + :class:`SpatialReference` of this geometry. Returns ``None`` if + there is no spatial reference information associated with this + geometry, or if an SRID cannot be determined. - .. attribute:: geos + .. attribute:: geos - Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object - corresponding to this geometry. + Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object + corresponding to this geometry. - .. attribute:: gml + .. attribute:: gml - Returns a string representation of this geometry in GML format:: + Returns a string representation of this geometry in GML format:: - >>> OGRGeometry('POINT(1 2)').gml - '1,2' + >>> OGRGeometry('POINT(1 2)').gml + '1,2' - .. attribute:: hex + .. attribute:: hex - Returns a string representation of this geometry in HEX WKB format:: + Returns a string representation of this geometry in HEX WKB format:: - >>> OGRGeometry('POINT(1 2)').hex - '0101000000000000000000F03F0000000000000040' + >>> OGRGeometry('POINT(1 2)').hex + '0101000000000000000000F03F0000000000000040' - .. attribute:: json + .. attribute:: json - Returns a string representation of this geometry in JSON format:: + Returns a string representation of this geometry in JSON format:: - >>> OGRGeometry('POINT(1 2)').json - '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }' + >>> OGRGeometry('POINT(1 2)').json + '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }' + .. attribute:: kml - .. attribute:: kml + Returns a string representation of this geometry in KML format. - Returns a string representation of this geometry in KML format. + .. attribute:: wkb_size - .. attribute:: wkb_size + Returns the size of the WKB buffer needed to hold a WKB representation + of this geometry:: - Returns the size of the WKB buffer needed to hold a WKB representation - of this geometry:: + >>> OGRGeometry('POINT(1 2)').wkb_size + 21 - >>> OGRGeometry('POINT(1 2)').wkb_size - 21 + .. attribute:: wkb - .. attribute:: wkb + Returns a ``buffer`` containing a WKB representation of this geometry. - Returns a ``buffer`` containing a WKB representation of this geometry. + .. attribute:: wkt - .. attribute:: wkt + Returns a string representation of this geometry in WKT format. - Returns a string representation of this geometry in WKT format. + .. attribute:: ewkt - .. attribute:: ewkt + Returns the EWKT representation of this geometry. - Returns the EWKT representation of this geometry. + .. method:: clone() - .. method:: clone() + Returns a new :class:`OGRGeometry` clone of this geometry object. - Returns a new :class:`OGRGeometry` clone of this geometry object. + .. method:: close_rings() - .. method:: close_rings() + If there are any rings within this geometry that have not been closed, + this routine will do so by adding the starting point to the end:: - If there are any rings within this geometry that have not been closed, - this routine will do so by adding the starting point to the end:: + >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)') + >>> triangle.close_rings() + >>> triangle.wkt + 'LINEARRING (0 0,0 1,1 0,0 0)' - >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)') - >>> triangle.close_rings() - >>> triangle.wkt - 'LINEARRING (0 0,0 1,1 0,0 0)' + .. method:: transform(coord_trans, clone=False) - .. method:: transform(coord_trans, clone=False) + Transforms this geometry to a different spatial reference system. May take + a :class:`CoordTransform` object, a :class:`SpatialReference` object, or + any other input accepted by :class:`SpatialReference` (including spatial + reference WKT and PROJ.4 strings, or an integer SRID). - Transforms this geometry to a different spatial reference system. May - take a :class:`CoordTransform` object, a :class:`SpatialReference` object, - or any other input accepted by :class:`SpatialReference` (including - spatial reference WKT and PROJ.4 strings, or an integer SRID). - By default nothing is returned and the geometry is transformed in-place. - However, if the ``clone`` keyword is set to ``True`` then a transformed - clone of this geometry is returned instead. + By default nothing is returned and the geometry is transformed in-place. + However, if the ``clone`` keyword is set to ``True`` then a transformed + clone of this geometry is returned instead. - .. method:: intersects(other) + .. method:: intersects(other) - Returns ``True`` if this geometry intersects the other, otherwise returns - ``False``. + Returns ``True`` if this geometry intersects the other, otherwise returns + ``False``. - .. method:: equals(other) + .. method:: equals(other) - Returns ``True`` if this geometry is equivalent to the other, otherwise returns - ``False``. + Returns ``True`` if this geometry is equivalent to the other, otherwise + returns ``False``. - .. method:: disjoint(other) + .. method:: disjoint(other) - Returns ``True`` if this geometry is spatially disjoint to (i.e. does - not intersect) the other, otherwise returns ``False``. + Returns ``True`` if this geometry is spatially disjoint to (i.e. does + not intersect) the other, otherwise returns ``False``. - .. method:: touches(other) + .. method:: touches(other) - Returns ``True`` if this geometry touches the other, otherwise returns - ``False``. + Returns ``True`` if this geometry touches the other, otherwise returns + ``False``. - .. method:: crosses(other) + .. method:: crosses(other) - Returns ``True`` if this geometry crosses the other, otherwise returns - ``False``. + Returns ``True`` if this geometry crosses the other, otherwise returns + ``False``. - .. method:: within(other) + .. method:: within(other) - Returns ``True`` if this geometry is contained within the other, otherwise returns - ``False``. + Returns ``True`` if this geometry is contained within the other, otherwise + returns ``False``. - .. method:: contains(other) + .. method:: contains(other) - Returns ``True`` if this geometry contains the other, otherwise returns - ``False``. + Returns ``True`` if this geometry contains the other, otherwise returns + ``False``. - .. method:: overlaps(other) + .. method:: overlaps(other) - Returns ``True`` if this geometry overlaps the other, otherwise returns - ``False``. + Returns ``True`` if this geometry overlaps the other, otherwise returns + ``False``. - .. method:: boundary() + .. method:: boundary() - The boundary of this geometry, as a new :class:`OGRGeometry` object. + The boundary of this geometry, as a new :class:`OGRGeometry` object. - .. attribute:: convex_hull + .. attribute:: convex_hull - The smallest convex polygon that contains this geometry, as a new - :class:`OGRGeometry` object. + The smallest convex polygon that contains this geometry, as a new + :class:`OGRGeometry` object. - .. method:: difference() + .. method:: difference() - Returns the region consisting of the difference of this geometry and - the other, as a new :class:`OGRGeometry` object. + Returns the region consisting of the difference of this geometry and + the other, as a new :class:`OGRGeometry` object. - .. method:: intersection() + .. method:: intersection() - Returns the region consisting of the intersection of this geometry and - the other, as a new :class:`OGRGeometry` object. + Returns the region consisting of the intersection of this geometry and + the other, as a new :class:`OGRGeometry` object. - .. method:: sym_difference() + .. method:: sym_difference() - Returns the region consisting of the symmetric difference of this - geometry and the other, as a new :class:`OGRGeometry` object. + Returns the region consisting of the symmetric difference of this + geometry and the other, as a new :class:`OGRGeometry` object. - .. method:: union() + .. method:: union() - Returns the region consisting of the union of this geometry and - the other, as a new :class:`OGRGeometry` object. + Returns the region consisting of the union of this geometry and + the other, as a new :class:`OGRGeometry` object. - .. attribute:: tuple + .. attribute:: tuple - Returns the coordinates of a point geometry as a tuple, the - coordinates of a line geometry as a tuple of tuples, and so forth:: + Returns the coordinates of a point geometry as a tuple, the + coordinates of a line geometry as a tuple of tuples, and so forth:: - >>> OGRGeometry('POINT (1 2)').tuple - (1.0, 2.0) - >>> OGRGeometry('LINESTRING (1 2,3 4)').tuple - ((1.0, 2.0), (3.0, 4.0)) + >>> OGRGeometry('POINT (1 2)').tuple + (1.0, 2.0) + >>> OGRGeometry('LINESTRING (1 2,3 4)').tuple + ((1.0, 2.0), (3.0, 4.0)) - .. attribute:: coords + .. attribute:: coords - An alias for :attr:`tuple`. + An alias for :attr:`tuple`. .. class:: Point - .. attribute:: x + .. attribute:: x - Returns the X coordinate of this point:: + Returns the X coordinate of this point:: - >>> OGRGeometry('POINT (1 2)').x - 1.0 + >>> OGRGeometry('POINT (1 2)').x + 1.0 - .. attribute:: y + .. attribute:: y - Returns the Y coordinate of this point:: + Returns the Y coordinate of this point:: - >>> OGRGeometry('POINT (1 2)').y - 2.0 + >>> OGRGeometry('POINT (1 2)').y + 2.0 - .. attribute:: z + .. attribute:: z - Returns the Z coordinate of this point, or ``None`` if the - point does not have a Z coordinate:: + Returns the Z coordinate of this point, or ``None`` if the point does not + have a Z coordinate:: - >>> OGRGeometry('POINT (1 2 3)').z - 3.0 + >>> OGRGeometry('POINT (1 2 3)').z + 3.0 .. class:: LineString - .. attribute:: x + .. attribute:: x - Returns a list of X coordinates in this line:: + Returns a list of X coordinates in this line:: - >>> OGRGeometry('LINESTRING (1 2,3 4)').x - [1.0, 3.0] + >>> OGRGeometry('LINESTRING (1 2,3 4)').x + [1.0, 3.0] - .. attribute:: y + .. attribute:: y - Returns a list of Y coordinates in this line:: + Returns a list of Y coordinates in this line:: - >>> OGRGeometry('LINESTRING (1 2,3 4)').y - [2.0, 4.0] + >>> OGRGeometry('LINESTRING (1 2,3 4)').y + [2.0, 4.0] - .. attribute:: z + .. attribute:: z - Returns a list of Z coordinates in this line, or ``None`` if the - line does not have Z coordinates:: + Returns a list of Z coordinates in this line, or ``None`` if the line does + not have Z coordinates:: - >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z - [3.0, 6.0] + >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z + [3.0, 6.0] .. class:: Polygon - .. attribute:: shell + .. attribute:: shell - Returns the shell or exterior ring of this polygon, as a ``LinearRing`` - geometry. + Returns the shell or exterior ring of this polygon, as a ``LinearRing`` + geometry. - .. attribute:: exterior_ring + .. attribute:: exterior_ring - An alias for :attr:`shell`. + An alias for :attr:`shell`. - .. attribute:: centroid + .. attribute:: centroid - Returns a :class:`Point` representing the centroid of this polygon. + Returns a :class:`Point` representing the centroid of this polygon. .. class:: GeometryCollection - .. method:: add(geom) - - Adds a geometry to this geometry collection. Not applicable to other - geometry types. + .. method:: add(geom) + Adds a geometry to this geometry collection. Not applicable to other + geometry types. ``OGRGeomType`` --------------- .. class:: OGRGeomType(type_input) - This class allows for the representation of an OGR geometry type - in any of several ways:: + This class allows for the representation of an OGR geometry type + in any of several ways:: - >>> from django.contrib.gis.gdal import OGRGeomType - >>> gt1 = OGRGeomType(3) # Using an integer for the type - >>> gt2 = OGRGeomType('Polygon') # Using a string - >>> gt3 = OGRGeomType('POLYGON') # It's case-insensitive - >>> print(gt1 == 3, gt1 == 'Polygon') # Equivalence works w/non-OGRGeomType objects - True True + >>> from django.contrib.gis.gdal import OGRGeomType + >>> gt1 = OGRGeomType(3) # Using an integer for the type + >>> gt2 = OGRGeomType('Polygon') # Using a string + >>> gt3 = OGRGeomType('POLYGON') # It's case-insensitive + >>> print(gt1 == 3, gt1 == 'Polygon') # Equivalence works w/non-OGRGeomType objects + True True - .. attribute:: name + .. attribute:: name - Returns a short-hand string form of the OGR Geometry type:: + Returns a short-hand string form of the OGR Geometry type:: - >>> gt1.name - 'Polygon' + >>> gt1.name + 'Polygon' - .. attribute:: num + .. attribute:: num - Returns the number corresponding to the OGR geometry type:: + Returns the number corresponding to the OGR geometry type:: - >>> gt1.num - 3 + >>> gt1.num + 3 - .. attribute:: django + .. attribute:: django - Returns the Django field type (a subclass of GeometryField) to use for - storing this OGR type, or ``None`` if there is no appropriate Django - type:: + Returns the Django field type (a subclass of GeometryField) to use for + storing this OGR type, or ``None`` if there is no appropriate Django type:: - >>> gt1.django - 'PolygonField' + >>> gt1.django + 'PolygonField' ``Envelope`` ------------ .. class:: Envelope(*args) - Represents an OGR Envelope structure that contains the - minimum and maximum X, Y coordinates for a rectangle bounding box. - The naming of the variables is compatible with the OGR Envelope - C structure. + Represents an OGR Envelope structure that contains the minimum and maximum + X, Y coordinates for a rectangle bounding box. The naming of the variables + is compatible with the OGR Envelope C structure. - .. attribute:: min_x + .. attribute:: min_x - The value of the minimum X coordinate. + The value of the minimum X coordinate. - .. attribute:: min_y + .. attribute:: min_y - The value of the maximum X coordinate. + The value of the maximum X coordinate. - .. attribute:: max_x + .. attribute:: max_x - The value of the minimum Y coordinate. + The value of the minimum Y coordinate. - .. attribute:: max_y + .. attribute:: max_y - The value of the maximum Y coordinate. + The value of the maximum Y coordinate. - .. attribute:: ur + .. attribute:: ur - The upper-right coordinate, as a tuple. + The upper-right coordinate, as a tuple. - .. attribute:: ll + .. attribute:: ll - The lower-left coordinate, as a tuple. + The lower-left coordinate, as a tuple. - .. attribute:: tuple + .. attribute:: tuple - A tuple representing the envelope. + A tuple representing the envelope. - .. attribute:: wkt + .. attribute:: wkt - A string representing this envelope as a polygon in WKT format. + A string representing this envelope as a polygon in WKT format. - - .. method:: expand_to_include(*args) + .. method:: expand_to_include(*args) Coordinate System Objects ========================= @@ -885,200 +872,199 @@ Coordinate System Objects .. class:: SpatialReference(srs_input) - Spatial reference objects are initialized on the given ``srs_input``, - which may be one of the following: + Spatial reference objects are initialized on the given ``srs_input``, + which may be one of the following: - * OGC Well Known Text (WKT) (a string) - * EPSG code (integer or string) - * PROJ.4 string - * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, ``'NAD27'``, ``'NAD83'``) + * OGC Well Known Text (WKT) (a string) + * EPSG code (integer or string) + * PROJ.4 string + * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, + ``'NAD27'``, ``'NAD83'``) - Example:: + Example:: - >>> wgs84 = SpatialReference('WGS84') # shorthand string - >>> wgs84 = SpatialReference(4326) # EPSG code - >>> wgs84 = SpatialReference('EPSG:4326') # EPSG string - >>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ' - >>> wgs84 = SpatialReference(proj4) # PROJ.4 string - >>> wgs84 = SpatialReference("""GEOGCS["WGS 84", - DATUM["WGS_1984", - SPHEROID["WGS 84",6378137,298.257223563, - AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich",0, - AUTHORITY["EPSG","8901"]], - UNIT["degree",0.01745329251994328, - AUTHORITY["EPSG","9122"]], - AUTHORITY["EPSG","4326"]]""") # OGC WKT + >>> wgs84 = SpatialReference('WGS84') # shorthand string + >>> wgs84 = SpatialReference(4326) # EPSG code + >>> wgs84 = SpatialReference('EPSG:4326') # EPSG string + >>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ' + >>> wgs84 = SpatialReference(proj4) # PROJ.4 string + >>> wgs84 = SpatialReference("""GEOGCS["WGS 84", + DATUM["WGS_1984", + SPHEROID["WGS 84",6378137,298.257223563, + AUTHORITY["EPSG","7030"]], + AUTHORITY["EPSG","6326"]], + PRIMEM["Greenwich",0, + AUTHORITY["EPSG","8901"]], + UNIT["degree",0.01745329251994328, + AUTHORITY["EPSG","9122"]], + AUTHORITY["EPSG","4326"]]""") # OGC WKT - .. method:: __getitem__(target) + .. method:: __getitem__(target) - Returns the value of the given string attribute node, ``None`` if the node - doesn't exist. Can also take a tuple as a parameter, (target, child), - where child is the index of the attribute in the WKT. For example:: + Returns the value of the given string attribute node, ``None`` if the node + doesn't exist. Can also take a tuple as a parameter, (target, child), where + child is the index of the attribute in the WKT. For example:: - >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]') - >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326 - >>> print(srs['GEOGCS']) - WGS 84 - >>> print(srs['DATUM']) - WGS_1984 - >>> print(srs['AUTHORITY']) - EPSG - >>> print(srs['AUTHORITY', 1]) # The authority value - 4326 - >>> print(srs['TOWGS84', 4]) # the fourth value in this wkt - 0 - >>> print(srs['UNIT|AUTHORITY']) # For the units authority, have to use the pipe symbol. - EPSG - >>> print(srs['UNIT|AUTHORITY', 1]) # The authority value for the units - 9122 + >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]') + >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326 + >>> print(srs['GEOGCS']) + WGS 84 + >>> print(srs['DATUM']) + WGS_1984 + >>> print(srs['AUTHORITY']) + EPSG + >>> print(srs['AUTHORITY', 1]) # The authority value + 4326 + >>> print(srs['TOWGS84', 4]) # the fourth value in this wkt + 0 + >>> print(srs['UNIT|AUTHORITY']) # For the units authority, have to use the pipe symbol. + EPSG + >>> print(srs['UNIT|AUTHORITY', 1]) # The authority value for the units + 9122 - .. method:: attr_value(target, index=0) + .. method:: attr_value(target, index=0) - The attribute value for the given target node (e.g. ``'PROJCS'``). - The index keyword specifies an index of the child node to return. + The attribute value for the given target node (e.g. ``'PROJCS'``). + The index keyword specifies an index of the child node to return. - .. method:: auth_name(target) + .. method:: auth_name(target) - Returns the authority name for the given string target node. + Returns the authority name for the given string target node. - .. method:: auth_code(target) + .. method:: auth_code(target) - Returns the authority code for the given string target node. + Returns the authority code for the given string target node. - .. method:: clone() + .. method:: clone() - Returns a clone of this spatial reference object. + Returns a clone of this spatial reference object. - .. method:: identify_epsg() + .. method:: identify_epsg() - This method inspects the WKT of this SpatialReference, and will - add EPSG authority nodes where an EPSG identifier is applicable. + This method inspects the WKT of this ``SpatialReference`` and will add EPSG + authority nodes where an EPSG identifier is applicable. - .. method:: from_esri() + .. method:: from_esri() - Morphs this SpatialReference from ESRI's format to EPSG + Morphs this SpatialReference from ESRI's format to EPSG - .. method:: to_esri() + .. method:: to_esri() - Morphs this SpatialReference to ESRI's format. + Morphs this SpatialReference to ESRI's format. - .. method:: validate() + .. method:: validate() - Checks to see if the given spatial reference is valid, if not - an exception will be raised. + Checks to see if the given spatial reference is valid, if not + an exception will be raised. - .. method:: import_epsg(epsg) + .. method:: import_epsg(epsg) - Import spatial reference from EPSG code. + Import spatial reference from EPSG code. - .. method:: import_proj(proj) + .. method:: import_proj(proj) - Import spatial reference from PROJ.4 string. + Import spatial reference from PROJ.4 string. - .. method:: import_user_input(user_input) + .. method:: import_user_input(user_input) - .. method:: import_wkt(wkt) + .. method:: import_wkt(wkt) - Import spatial reference from WKT. + Import spatial reference from WKT. - .. method:: import_xml(xml) + .. method:: import_xml(xml) - Import spatial reference from XML. + Import spatial reference from XML. - .. attribute:: name + .. attribute:: name - Returns the name of this Spatial Reference. + Returns the name of this Spatial Reference. - .. attribute:: srid + .. attribute:: srid - Returns the SRID of top-level authority, or ``None`` if undefined. + Returns the SRID of top-level authority, or ``None`` if undefined. - .. attribute:: linear_name + .. attribute:: linear_name - Returns the name of the linear units. + Returns the name of the linear units. - .. attribute:: linear_units + .. attribute:: linear_units - Returns the value of the linear units. + Returns the value of the linear units. - .. attribute:: angular_name + .. attribute:: angular_name - Returns the name of the angular units." + Returns the name of the angular units." - .. attribute:: angular_units + .. attribute:: angular_units - Returns the value of the angular units. + Returns the value of the angular units. - .. attribute:: units + .. attribute:: units - Returns a 2-tuple of the units value and the units name, - and will automatically determines whether to return the linear - or angular units. + Returns a 2-tuple of the units value and the units name and will + automatically determines whether to return the linear or angular units. - .. attribute:: ellipsoid + .. attribute:: ellipsoid - Returns a tuple of the ellipsoid parameters for this spatial - reference: (semimajor axis, semiminor axis, and inverse flattening) + Returns a tuple of the ellipsoid parameters for this spatial reference: + (semimajor axis, semiminor axis, and inverse flattening). - .. attribute:: semi_major + .. attribute:: semi_major - Returns the semi major axis of the ellipsoid for this spatial reference. + Returns the semi major axis of the ellipsoid for this spatial reference. - .. attribute:: semi_minor + .. attribute:: semi_minor - Returns the semi minor axis of the ellipsoid for this spatial reference. + Returns the semi minor axis of the ellipsoid for this spatial reference. - .. attribute:: inverse_flattening + .. attribute:: inverse_flattening - Returns the inverse flattening of the ellipsoid for this spatial reference. + Returns the inverse flattening of the ellipsoid for this spatial reference. - .. attribute:: geographic + .. attribute:: geographic - Returns ``True`` if this spatial reference is geographic - (root node is ``GEOGCS``). + Returns ``True`` if this spatial reference is geographic (root node is + ``GEOGCS``). - .. attribute:: local + .. attribute:: local - Returns ``True`` if this spatial reference is local - (root node is ``LOCAL_CS``). + Returns ``True`` if this spatial reference is local (root node is + ``LOCAL_CS``). - .. attribute:: projected + .. attribute:: projected - Returns ``True`` if this spatial reference is a projected coordinate - system (root node is ``PROJCS``). + Returns ``True`` if this spatial reference is a projected coordinate system + (root node is ``PROJCS``). - .. attribute:: wkt + .. attribute:: wkt - Returns the WKT representation of this spatial reference. + Returns the WKT representation of this spatial reference. - .. attribute:: pretty_wkt + .. attribute:: pretty_wkt - Returns the 'pretty' representation of the WKT. + Returns the 'pretty' representation of the WKT. - .. attribute:: proj + .. attribute:: proj - Returns the PROJ.4 representation for this spatial reference. + Returns the PROJ.4 representation for this spatial reference. - .. attribute:: proj4 + .. attribute:: proj4 - Alias for :attr:`SpatialReference.proj`. + Alias for :attr:`SpatialReference.proj`. - .. attribute:: xml - - Returns the XML representation of this spatial reference. + .. attribute:: xml + Returns the XML representation of this spatial reference. ``CoordTransform`` ------------------ .. class:: CoordTransform(source, target) -Represents a coordinate system transform. It is initialized with two +Represents a coordinate system transform. It is initialized with two :class:`SpatialReference`, representing the source and target coordinate -systems, respectively. These objects should be used when performing -the same coordinate transformation repeatedly on different geometries:: +systems, respectively. These objects should be used when performing the same +coordinate transformation repeatedly on different geometries:: >>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83')) >>> for feat in layer: diff --git a/docs/ref/contrib/gis/geoip.txt b/docs/ref/contrib/gis/geoip.txt index 58093dcdff..212aee12af 100644 --- a/docs/ref/contrib/gis/geoip.txt +++ b/docs/ref/contrib/gis/geoip.txt @@ -3,7 +3,7 @@ Geolocation with GeoIP ====================== .. module:: django.contrib.gis.geoip - :synopsis: High-level Python interface for MaxMind's GeoIP C library. + :synopsis: High-level Python interface for MaxMind's GeoIP C library. .. deprecated:: 1.9 @@ -33,27 +33,27 @@ Example Assuming you have the GeoIP C library installed, here is an example of its usage:: - >>> from django.contrib.gis.geoip import GeoIP - >>> g = GeoIP() - >>> g.country('google.com') - {'country_code': 'US', 'country_name': 'United States'} - >>> g.city('72.14.207.99') - {'area_code': 650, - 'city': 'Mountain View', - 'country_code': 'US', - 'country_code3': 'USA', - 'country_name': 'United States', - 'dma_code': 807, - 'latitude': 37.419200897216797, - 'longitude': -122.05740356445312, - 'postal_code': '94043', - 'region': 'CA'} - >>> g.lat_lon('salon.com') - (37.789798736572266, -122.39420318603516) - >>> g.lon_lat('uh.edu') - (-95.415199279785156, 29.77549934387207) - >>> g.geos('24.124.1.80').wkt - 'POINT (-95.2087020874023438 39.0392990112304688)' + >>> from django.contrib.gis.geoip import GeoIP + >>> g = GeoIP() + >>> g.country('google.com') + {'country_code': 'US', 'country_name': 'United States'} + >>> g.city('72.14.207.99') + {'area_code': 650, + 'city': 'Mountain View', + 'country_code': 'US', + 'country_code3': 'USA', + 'country_name': 'United States', + 'dma_code': 807, + 'latitude': 37.419200897216797, + 'longitude': -122.05740356445312, + 'postal_code': '94043', + 'region': 'CA'} + >>> g.lat_lon('salon.com') + (37.789798736572266, -122.39420318603516) + >>> g.lon_lat('uh.edu') + (-95.415199279785156, 29.77549934387207) + >>> g.geos('24.124.1.80').wkt + 'POINT (-95.2087020874023438 39.0392990112304688)' ``GeoIP`` Settings ================== diff --git a/docs/ref/contrib/gis/geoip2.txt b/docs/ref/contrib/gis/geoip2.txt index 8e51aa6fb5..cbcba9fac9 100644 --- a/docs/ref/contrib/gis/geoip2.txt +++ b/docs/ref/contrib/gis/geoip2.txt @@ -3,7 +3,7 @@ Geolocation with GeoIP2 ======================= .. module:: django.contrib.gis.geoip2 - :synopsis: Python interface for MaxMind's GeoIP2 databases. + :synopsis: Python interface for MaxMind's GeoIP2 databases. .. versionadded:: 1.9 @@ -29,25 +29,25 @@ Example Here is an example of its usage:: - >>> from django.contrib.gis.geoip2 import GeoIP2 - >>> g = GeoIP2() - >>> g.country('google.com') - {'country_code': 'US', 'country_name': 'United States'} - >>> g.city('72.14.207.99') - {'city': 'Mountain View', - 'country_code': 'US', - 'country_name': 'United States', - 'dma_code': 807, - 'latitude': 37.419200897216797, - 'longitude': -122.05740356445312, - 'postal_code': '94043', - 'region': 'CA'} - >>> g.lat_lon('salon.com') - (39.0437, -77.4875) - >>> g.lon_lat('uh.edu') - (-95.4342, 29.834) - >>> g.geos('24.124.1.80').wkt - 'POINT (-97.0000000000000000 38.0000000000000000)' + >>> from django.contrib.gis.geoip2 import GeoIP2 + >>> g = GeoIP2() + >>> g.country('google.com') + {'country_code': 'US', 'country_name': 'United States'} + >>> g.city('72.14.207.99') + {'city': 'Mountain View', + 'country_code': 'US', + 'country_name': 'United States', + 'dma_code': 807, + 'latitude': 37.419200897216797, + 'longitude': -122.05740356445312, + 'postal_code': '94043', + 'region': 'CA'} + >>> g.lat_lon('salon.com') + (39.0437, -77.4875) + >>> g.lon_lat('uh.edu') + (-95.4342, 29.834) + >>> g.geos('24.124.1.80').wkt + 'POINT (-97.0000000000000000 38.0000000000000000)' ``GeoIP`` Settings ================== diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index b694c6bdef..2221d09ede 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -1308,9 +1308,9 @@ Returns a ``LineString`` constructed from the point field geometries in the Example:: - >>> print(City.objects.filter(name__in=('Houston', 'Dallas') - ... ).aggregate(MakeLine('poly'))['poly__makeline'] - LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018) + >>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(MakeLine('poly')) + >>> print(qs['poly__makeline']) + LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018) ``Union`` ~~~~~~~~~ diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index bf8595811f..2806ca061a 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -3,7 +3,7 @@ GEOS API ======== .. module:: django.contrib.gis.geos - :synopsis: GeoDjango's high-level interface to the GEOS library. + :synopsis: GeoDjango's high-level interface to the GEOS library. Background ========== @@ -162,13 +162,13 @@ Geometries support set-like operators:: it requires the compared geometries to have the same coordinates in the same positions:: - >>> from django.contrib.gis.geos import LineString - >>> ls1 = LineString((0, 0), (1, 1)) - >>> ls2 = LineString((1, 1), (0, 0)) - >>> ls1.equals(ls2) - True - >>> ls1 == ls2 - False + >>> from django.contrib.gis.geos import LineString + >>> ls1 = LineString((0, 0), (1, 1)) + >>> ls2 = LineString((1, 1), (0, 0)) + >>> ls1.equals(ls2) + True + >>> ls1 == ls2 + False Geometry Objects ================ @@ -308,8 +308,8 @@ Essentially the SRID is prepended to the WKT representation, for example .. note:: - The output from this property does not include the 3dm, 3dz, and 4d - information that PostGIS supports in its EWKT representations. + The output from this property does not include the 3dm, 3dz, and 4d + information that PostGIS supports in its EWKT representations. .. attribute:: GEOSGeometry.hex @@ -645,99 +645,99 @@ is returned instead. .. class:: Point(x=None, y=None, z=None, srid=None) - ``Point`` objects are instantiated using arguments that represent - the component coordinates of the point or with a single sequence - coordinates. For example, the following are equivalent:: + ``Point`` objects are instantiated using arguments that represent the + component coordinates of the point or with a single sequence coordinates. + For example, the following are equivalent:: - >>> pnt = Point(5, 23) - >>> pnt = Point([5, 23]) + >>> pnt = Point(5, 23) + >>> pnt = Point([5, 23]) - Empty ``Point`` objects may be instantiated by passing no arguments or an - empty sequence. The following are equivalent:: + Empty ``Point`` objects may be instantiated by passing no arguments or an + empty sequence. The following are equivalent:: - >>> pnt = Point() - >>> pnt = Point([]) + >>> pnt = Point() + >>> pnt = Point([]) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``Point`` couldn't be instantiated. + In previous versions, an empty ``Point`` couldn't be instantiated. ``LineString`` -------------- .. class:: LineString(*args, **kwargs) - ``LineString`` objects are instantiated using arguments that are - either a sequence of coordinates or :class:`Point` objects. - For example, the following are equivalent:: + ``LineString`` objects are instantiated using arguments that are either a + sequence of coordinates or :class:`Point` objects. For example, the + following are equivalent:: - >>> ls = LineString((0, 0), (1, 1)) - >>> ls = LineString(Point(0, 0), Point(1, 1)) + >>> ls = LineString((0, 0), (1, 1)) + >>> ls = LineString(Point(0, 0), Point(1, 1)) - In addition, ``LineString`` objects may also be created by passing - in a single sequence of coordinate or :class:`Point` objects:: + In addition, ``LineString`` objects may also be created by passing in a + single sequence of coordinate or :class:`Point` objects:: - >>> ls = LineString( ((0, 0), (1, 1)) ) - >>> ls = LineString( [Point(0, 0), Point(1, 1)] ) + >>> ls = LineString( ((0, 0), (1, 1)) ) + >>> ls = LineString( [Point(0, 0), Point(1, 1)] ) - Empty ``LineString`` objects may be instantiated by passing no arguments - or an empty sequence. The following are equivalent:: + Empty ``LineString`` objects may be instantiated by passing no arguments + or an empty sequence. The following are equivalent:: - >>> ls = LineString() - >>> ls = LineString([]) + >>> ls = LineString() + >>> ls = LineString([]) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``LineString`` couldn't be instantiated. + In previous versions, an empty ``LineString`` couldn't be instantiated. - .. attribute:: closed + .. attribute:: closed - .. versionadded:: 1.10 + .. versionadded:: 1.10 - Returns whether or not this ``LineString`` is closed. + Returns whether or not this ``LineString`` is closed. ``LinearRing`` -------------- .. class:: LinearRing(*args, **kwargs) - ``LinearRing`` objects are constructed in the exact same way as - :class:`LineString` objects, however the coordinates must be - *closed*, in other words, the first coordinates must be the - same as the last coordinates. For example:: + ``LinearRing`` objects are constructed in the exact same way as + :class:`LineString` objects, however the coordinates must be *closed*, in + other words, the first coordinates must be the same as the last + coordinates. For example:: - >>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0)) + >>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0)) - Notice that ``(0, 0)`` is the first and last coordinate -- if - they were not equal, an error would be raised. + Notice that ``(0, 0)`` is the first and last coordinate -- if they were not + equal, an error would be raised. ``Polygon`` ----------- .. class:: Polygon(*args, **kwargs) - ``Polygon`` objects may be instantiated by passing in parameters that - represent the rings of the polygon. The parameters must either be - :class:`LinearRing` instances, or a sequence that may be used to construct a - :class:`LinearRing`:: + ``Polygon`` objects may be instantiated by passing in parameters that + represent the rings of the polygon. The parameters must either be + :class:`LinearRing` instances, or a sequence that may be used to construct a + :class:`LinearRing`:: - >>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) - >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) - >>> poly = Polygon(ext_coords, int_coords) - >>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords)) + >>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) + >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) + >>> poly = Polygon(ext_coords, int_coords) + >>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords)) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``Polygon`` couldn't be instantiated. + In previous versions, an empty ``Polygon`` couldn't be instantiated. - .. classmethod:: from_bbox(bbox) + .. classmethod:: from_bbox(bbox) - Returns a polygon object from the given bounding-box, a 4-tuple - comprising ``(xmin, ymin, xmax, ymax)``. + Returns a polygon object from the given bounding-box, a 4-tuple + comprising ``(xmin, ymin, xmax, ymax)``. - .. attribute:: num_interior_rings + .. attribute:: num_interior_rings - Returns the number of interior rings in this geometry. + Returns the number of interior rings in this geometry. .. admonition:: Comparing Polygons @@ -758,92 +758,92 @@ Geometry Collections .. class:: MultiPoint(*args, **kwargs) - ``MultiPoint`` objects may be instantiated by passing in :class:`Point` - objects as arguments, or a single sequence of :class:`Point` objects:: + ``MultiPoint`` objects may be instantiated by passing in :class:`Point` + objects as arguments, or a single sequence of :class:`Point` objects:: - >>> mp = MultiPoint(Point(0, 0), Point(1, 1)) - >>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) ) + >>> mp = MultiPoint(Point(0, 0), Point(1, 1)) + >>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) ) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``MultiPoint`` couldn't be instantiated. + In previous versions, an empty ``MultiPoint`` couldn't be instantiated. ``MultiLineString`` ------------------- .. class:: MultiLineString(*args, **kwargs) - ``MultiLineString`` objects may be instantiated by passing in - :class:`LineString` objects as arguments, or a single sequence of - :class:`LineString` objects:: + ``MultiLineString`` objects may be instantiated by passing in + :class:`LineString` objects as arguments, or a single sequence of + :class:`LineString` objects:: - >>> ls1 = LineString((0, 0), (1, 1)) - >>> ls2 = LineString((2, 2), (3, 3)) - >>> mls = MultiLineString(ls1, ls2) - >>> mls = MultiLineString([ls1, ls2]) + >>> ls1 = LineString((0, 0), (1, 1)) + >>> ls2 = LineString((2, 2), (3, 3)) + >>> mls = MultiLineString(ls1, ls2) + >>> mls = MultiLineString([ls1, ls2]) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``MultiLineString`` couldn't be - instantiated. + In previous versions, an empty ``MultiLineString`` couldn't be + instantiated. - .. attribute:: merged + .. attribute:: merged - Returns a :class:`LineString` representing the line merge of - all the components in this ``MultiLineString``. + Returns a :class:`LineString` representing the line merge of + all the components in this ``MultiLineString``. - .. attribute:: closed + .. attribute:: closed - .. versionadded:: 1.10 + .. versionadded:: 1.10 - Returns ``True`` if and only if all elements are closed. Requires GEOS 3.5. + Returns ``True`` if and only if all elements are closed. Requires GEOS 3.5. ``MultiPolygon`` ---------------- .. class:: MultiPolygon(*args, **kwargs) - ``MultiPolygon`` objects may be instantiated by passing :class:`Polygon` - objects as arguments, or a single sequence of :class:`Polygon` objects:: + ``MultiPolygon`` objects may be instantiated by passing :class:`Polygon` + objects as arguments, or a single sequence of :class:`Polygon` objects:: - >>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) - >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) ) - >>> mp = MultiPolygon(p1, p2) - >>> mp = MultiPolygon([p1, p2]) + >>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) + >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) ) + >>> mp = MultiPolygon(p1, p2) + >>> mp = MultiPolygon([p1, p2]) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``MultiPolygon`` couldn't be - instantiated. + In previous versions, an empty ``MultiPolygon`` couldn't be + instantiated. - .. attribute:: cascaded_union + .. attribute:: cascaded_union - .. deprecated:: 1.10 + .. deprecated:: 1.10 - Use the :attr:`GEOSGeometry.unary_union` property instead. + Use the :attr:`GEOSGeometry.unary_union` property instead. - Returns a :class:`Polygon` that is the union of all of the component - polygons in this collection. The algorithm employed is significantly - more efficient (faster) than trying to union the geometries together - individually. [#fncascadedunion]_ + Returns a :class:`Polygon` that is the union of all of the component + polygons in this collection. The algorithm employed is significantly + more efficient (faster) than trying to union the geometries together + individually. [#fncascadedunion]_ ``GeometryCollection`` ---------------------- .. class:: GeometryCollection(*args, **kwargs) - ``GeometryCollection`` objects may be instantiated by passing in other - :class:`GEOSGeometry` as arguments, or a single sequence of - :class:`GEOSGeometry` objects:: + ``GeometryCollection`` objects may be instantiated by passing in other + :class:`GEOSGeometry` as arguments, or a single sequence of + :class:`GEOSGeometry` objects:: - >>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) - >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) - >>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)) + >>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) + >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) + >>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)) - .. versionchanged:: 1.10 + .. versionchanged:: 1.10 - In previous versions, an empty ``GeometryCollection`` couldn't be - instantiated. + In previous versions, an empty ``GeometryCollection`` couldn't be + instantiated. .. _prepared-geometries: @@ -897,9 +897,9 @@ Geometry Factories .. function:: fromfile(file_h) - :param file_h: input file that contains spatial data - :type file_h: a Python ``file`` object or a string path to the file - :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file + :param file_h: input file that contains spatial data + :type file_h: a Python ``file`` object or a string path to the file + :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file Example:: @@ -908,11 +908,11 @@ Example:: .. function:: fromstr(string, srid=None) - :param string: string that contains spatial data - :type string: string - :param srid: spatial reference identifier - :type srid: int - :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string + :param string: string that contains spatial data + :type string: string + :param srid: spatial reference identifier + :type srid: int + :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string ``fromstr(string, srid)`` is equivalent to :class:`GEOSGeometry(string, srid) `. diff --git a/docs/ref/contrib/gis/index.txt b/docs/ref/contrib/gis/index.txt index 83b8b31b50..7345a51401 100644 --- a/docs/ref/contrib/gis/index.txt +++ b/docs/ref/contrib/gis/index.txt @@ -3,31 +3,31 @@ GeoDjango ========= .. module:: django.contrib.gis - :synopsis: Geographic Information System (GIS) extensions for Django + :synopsis: Geographic Information System (GIS) extensions for Django GeoDjango intends to be a world-class geographic Web framework. Its goal is to make it as easy as possible to build GIS Web applications and harness the power of spatially enabled data. .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - tutorial - install/index - model-api - db-api - forms-api - geoquerysets - functions - measure - geos - gdal - geoip - geoip2 - utils - commands - admin - feeds - sitemaps - testing - deployment + tutorial + install/index + model-api + db-api + forms-api + geoquerysets + functions + measure + geos + gdal + geoip + geoip2 + utils + commands + admin + feeds + sitemaps + testing + deployment diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index fed2114b0e..759a03fa03 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -82,11 +82,11 @@ is required. .. note:: - On Linux platforms, it may be necessary to run the ``ldconfig`` - command after installing each library. For example:: + On Linux platforms, it may be necessary to run the ``ldconfig`` command + after installing each library. For example:: - $ sudo make install - $ sudo ldconfig + $ sudo make install + $ sudo ldconfig .. note:: @@ -210,10 +210,10 @@ Configure, make and install:: .. note:: - Because GeoDjango has its own Python interface, the preceding instructions - do not build GDAL's own Python bindings. The bindings may be built by - adding the ``--with-python`` flag when running ``configure``. See - `GDAL/OGR In Python`__ for more information on GDAL's bindings. + Because GeoDjango has its own Python interface, the preceding instructions + do not build GDAL's own Python bindings. The bindings may be built by + adding the ``--with-python`` flag when running ``configure``. See + `GDAL/OGR In Python`__ for more information on GDAL's bindings. If you have any problems, please see the troubleshooting section below for suggestions and solutions. @@ -253,7 +253,6 @@ the GDAL library. For example:: GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so' - .. rubric:: Footnotes .. [#] The datum shifting files are needed for converting data to and from certain projections. diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index cf49ca7de1..fb751dc1a9 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -76,18 +76,18 @@ Geospatial libraries -------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - geolibs + geolibs Database installation --------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - postgis - spatialite + postgis + spatialite Add ``django.contrib.gis`` to :setting:`INSTALLED_APPS` ------------------------------------------------------- @@ -480,14 +480,14 @@ executable with ``cmd.exe``, will set this up: .. code-block:: bat - set OSGEO4W_ROOT=C:\OSGeo4W - set PYTHON_ROOT=C:\Python27 - set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal - set PROJ_LIB=%OSGEO4W_ROOT%\share\proj - set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin - reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%" - reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%" - reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%" + set OSGEO4W_ROOT=C:\OSGeo4W + set PYTHON_ROOT=C:\Python27 + set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal + set PROJ_LIB=%OSGEO4W_ROOT%\share\proj + set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin + reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%" + reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%" + reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%" For your convenience, these commands are available in the executable batch script, :download:`geodjango_setup.bat`. diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index 9c7bb82ffb..39cc6e9704 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -3,7 +3,7 @@ ==================================== .. module:: django.contrib.gis.utils.layermapping - :synopsis: Spatial data import utility for GeoDjango models. + :synopsis: Spatial data import utility for GeoDjango models. .. currentmodule:: django.contrib.gis.utils diff --git a/docs/ref/contrib/gis/measure.txt b/docs/ref/contrib/gis/measure.txt index 260e7d0276..2c76ccdbad 100644 --- a/docs/ref/contrib/gis/measure.txt +++ b/docs/ref/contrib/gis/measure.txt @@ -3,7 +3,7 @@ Measurement Objects =================== .. module:: django.contrib.gis.measure - :synopsis: GeoDjango's distance and area measurement objects. + :synopsis: GeoDjango's distance and area measurement objects. The :mod:`django.contrib.gis.measure` module contains objects that allow for convenient representation of distance and area units of measure. [#]_ @@ -113,64 +113,64 @@ Measurement API .. class:: Distance(**kwargs) - To initialize a distance object, pass in a keyword corresponding to - the desired :ref:`unit attribute name ` set with - desired value. For example, the following creates a distance - object representing 5 miles:: + To initialize a distance object, pass in a keyword corresponding to the + desired :ref:`unit attribute name ` set with desired + value. For example, the following creates a distance object representing 5 + miles:: - >>> dist = Distance(mi=5) + >>> dist = Distance(mi=5) - .. method:: __getattr__(unit_att) + .. method:: __getattr__(unit_att) - Returns the distance value in units corresponding to the given unit - attribute. For example:: + Returns the distance value in units corresponding to the given unit + attribute. For example:: - >>> print(dist.km) - 8.04672 + >>> print(dist.km) + 8.04672 - .. classmethod:: unit_attname(unit_name) + .. classmethod:: unit_attname(unit_name) - Returns the distance unit attribute name for the given full unit name. - For example:: + Returns the distance unit attribute name for the given full unit name. For + example:: - >>> Distance.unit_attname('Mile') - 'mi' + >>> Distance.unit_attname('Mile') + 'mi' .. class:: D - Alias for :class:`Distance` class. + Alias for :class:`Distance` class. ``Area`` -------- .. class:: Area(**kwargs) - To initialize an area object, pass in a keyword corresponding to - the desired :ref:`unit attribute name ` set with - desired value. For example, the following creates an area - object representing 5 square miles:: + To initialize an area object, pass in a keyword corresponding to the + desired :ref:`unit attribute name ` set with desired + value. For example, the following creates an area object representing 5 + square miles:: - >>> a = Area(sq_mi=5) + >>> a = Area(sq_mi=5) - .. method:: __getattr__(unit_att) + .. method:: __getattr__(unit_att) - Returns the area value in units corresponding to the given unit - attribute. For example:: + Returns the area value in units corresponding to the given unit attribute. + For example:: - >>> print(a.sq_km) - 12.949940551680001 + >>> print(a.sq_km) + 12.949940551680001 - .. classmethod:: unit_attname(unit_name) + .. classmethod:: unit_attname(unit_name) - Returns the area unit attribute name for the given full unit name. - For example:: + Returns the area unit attribute name for the given full unit name. For + example:: >>> Area.unit_attname('Kilometer') 'sq_km' .. class:: A - Alias for :class:`Area` class. + Alias for :class:`Area` class. .. rubric:: Footnotes .. [#] `Robert Coup `_ is the initial author of the measure objects, diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index d5fe84ebd6..d5e1d79afa 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -3,7 +3,7 @@ GeoDjango Model API =================== .. module:: django.contrib.gis.db.models - :synopsis: GeoDjango model and field API. + :synopsis: GeoDjango model and field API. This document explores the details of the GeoDjango Model API. Throughout this section, we'll be using the following geographic model of a `ZIP code`__ and diff --git a/docs/ref/contrib/gis/ogrinspect.txt b/docs/ref/contrib/gis/ogrinspect.txt index 653002418b..93077f7a70 100644 --- a/docs/ref/contrib/gis/ogrinspect.txt +++ b/docs/ref/contrib/gis/ogrinspect.txt @@ -3,7 +3,7 @@ OGR Inspection ============== .. module:: django.contrib.gis.utils.ogrinspect - :synopsis: Utilities for inspecting OGR data sources. + :synopsis: Utilities for inspecting OGR data sources. .. currentmodule:: django.contrib.gis.utils diff --git a/docs/ref/contrib/gis/serializers.txt b/docs/ref/contrib/gis/serializers.txt index 96548d4635..1a9fb8c8cb 100644 --- a/docs/ref/contrib/gis/serializers.txt +++ b/docs/ref/contrib/gis/serializers.txt @@ -3,7 +3,7 @@ ====================== .. module:: django.contrib.gis.serializers.geojson - :synopsis: Serialization of GeoDjango models in the GeoJSON format. + :synopsis: Serialization of GeoDjango models in the GeoJSON format. GeoDjango provides a specific serializer for the `GeoJSON`__ format. See :doc:`/topics/serialization` for more information on serialization. diff --git a/docs/ref/contrib/gis/utils.txt b/docs/ref/contrib/gis/utils.txt index 7110ddf43e..d7c82a248e 100644 --- a/docs/ref/contrib/gis/utils.txt +++ b/docs/ref/contrib/gis/utils.txt @@ -3,14 +3,14 @@ GeoDjango Utilities =================== .. module:: django.contrib.gis.utils - :synopsis: GeoDjango's collection of utilities. + :synopsis: GeoDjango's collection of utilities. The :mod:`django.contrib.gis.utils` module contains various utilities that are useful in creating geospatial Web applications. .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - layermapping - ogrinspect - serializers + layermapping + ogrinspect + serializers