Fixed #25205 -- Removed doc references to deprecated GeoManager class.

This commit is contained in:
Brendan Hayward 2015-05-08 22:52:15 +05:00 committed by Tim Graham
parent 7fa1dd8a80
commit c9fb4f3c45
8 changed files with 42 additions and 48 deletions

View File

@ -105,6 +105,7 @@ answer newbie questions, and generally made Django that much better:
Bouke Haarsma <bouke@haarsma.eu> Bouke Haarsma <bouke@haarsma.eu>
Božidar Benko <bbenko@gmail.com> Božidar Benko <bbenko@gmail.com>
Brant Harris Brant Harris
Brendan Hayward <brendanhayward85@gmail.com>
Brenton Simpson <http://theillustratedlife.com> Brenton Simpson <http://theillustratedlife.com>
Brett Cannon <brett@python.org> Brett Cannon <brett@python.org>
Brett Hoerner <bretthoerner@bretthoerner.com> Brett Hoerner <bretthoerner@bretthoerner.com>

View File

@ -226,18 +226,17 @@ in southern Texas::
# A projected coordinate system (only valid for South Texas!) # A projected coordinate system (only valid for South Texas!)
# is used, units are in meters. # is used, units are in meters.
point = models.PointField(srid=32140) point = models.PointField(srid=32140)
objects = models.GeoManager()
Then distance queries may be performed as follows:: Then distance queries may be performed as follows::
>>> from django.contrib.gis.geos import * >>> from django.contrib.gis.geos import fromstr
>>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance`` >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
>>> from geoapp import SouthTexasCity >>> from geoapp.models import SouthTexasCity
# Distances will be calculated from this point, which does not have to be projected. # Distances will be calculated from this point, which does not have to be projected.
>>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
# If numeric parameter, units of field (meters in this case) are assumed. # If numeric parameter, units of field (meters in this case) are assumed.
>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000)) >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
# Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit) # Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7))) >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20))) >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100))) >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))

View File

@ -216,8 +216,9 @@ In the following example, the distance from the city of Hobart to every other
:class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity`` :class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity``
queryset is calculated:: queryset is calculated::
>>> from django.contrib.gis.db.models.functions import Distance
>>> pnt = AustraliaCity.objects.get(name='Hobart').point >>> pnt = AustraliaCity.objects.get(name='Hobart').point
>>> for city in AustraliaCity.objects.distance('point', pnt): >>> for city in AustraliaCity.objects.annotate(distance=Distance('point', pnt)):
... print(city.name, city.distance) ... print(city.name, city.distance)
Wollongong 990071.220408 m Wollongong 990071.220408 m
Shellharbour 972804.613941 m Shellharbour 972804.613941 m

View File

@ -629,6 +629,8 @@ Oracle ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
This lookup is not available on SpatiaLite. This lookup is not available on SpatiaLite.
.. _geoqueryset-methods:
``GeoQuerySet`` Methods ``GeoQuerySet`` Methods
======================= =======================

View File

@ -57,7 +57,6 @@ Example
class TestGeo(models.Model): class TestGeo(models.Model):
name = models.CharField(max_length=25) # corresponds to the 'str' field name = models.CharField(max_length=25) # corresponds to the 'str' field
poly = models.PolygonField(srid=4269) # we want our model in a different SRID poly = models.PolygonField(srid=4269) # we want our model in a different SRID
objects = models.GeoManager()
def __str__(self): # __unicode__ on Python 2 def __str__(self): # __unicode__ on Python 2
return 'Name: %s' % self.name return 'Name: %s' % self.name

View File

@ -14,7 +14,6 @@ of a `Digital Elevation Model`__ as our examples::
class Zipcode(models.Model): class Zipcode(models.Model):
code = models.CharField(max_length=5) code = models.CharField(max_length=5)
poly = models.PolygonField() poly = models.PolygonField()
objects = models.GeoManager()
class Elevation(models.Model): class Elevation(models.Model):
name = models.CharField(max_length=100) name = models.CharField(max_length=100)
@ -246,36 +245,40 @@ determining `when to use geography data type over geometry data type
.. currentmodule:: django.contrib.gis.db.models .. currentmodule:: django.contrib.gis.db.models
.. class:: GeoManager .. class:: GeoManager
In order to conduct geographic queries, each geographic model requires The ``GeoManager`` is required in order to use the legacy
a ``GeoManager`` model manager. This manager allows for the proper SQL :ref:`geoqueryset-methods`.
construction for geographic queries; thus, without it, all geographic filters
will fail.
.. note:: .. deprecated:: 1.9
Geographic filtering support is limited to geometry fields. ``RasterField`` All ``GeoQuerySet`` methods have been deprecated and replaced by
does not currently allow spatial querying. :doc:`equivalent database functions </ref/contrib/gis/functions>`. As soon
as the legacy methods have been replaced in your code, you should be able
to remove the special ``GeoManager`` from your GIS-enabled classes.
It should also be noted that ``GeoManager`` is required even if the .. versionchanged:: 1.9
model does not have a geographic field itself, e.g., in the case of a
``ForeignKey`` relation to a model with a geographic field. For example,
if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
model::
from django.contrib.gis.db import models In older versions, the manager was required to conduct geographic queries.
Without it, all geographic filters failed.
class Address(models.Model): ``GeoManager`` was required even if the model did not have a geographic
num = models.IntegerField() field itself, e.g., in the case of a ``ForeignKey`` relation to a model
street = models.CharField(max_length=100) with a geographic field. For example, if we had an ``Address`` model with
city = models.CharField(max_length=100) a ``ForeignKey`` to our ``Zipcode`` model::
state = models.CharField(max_length=2)
zipcode = models.ForeignKey(Zipcode, on_delete=models.CASCADE)
objects = models.GeoManager()
The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, from django.contrib.gis.db import models
for example::
qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)') class Address(models.Model):
num = models.IntegerField()
street = models.CharField(max_length=100)
city = models.CharField(max_length=100)
state = models.CharField(max_length=2)
zipcode = models.ForeignKey(Zipcode, on_delete=models.CASCADE)
objects = models.GeoManager()
The geographic manager was needed to do spatial queries on related
``Zipcode`` objects, for example::
qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
.. rubric:: Footnotes .. rubric:: Footnotes
.. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengeospatial.org/standards/sfs>`_. .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengeospatial.org/standards/sfs>`_.

View File

@ -238,20 +238,14 @@ model to represent this data::
lon = models.FloatField() lon = models.FloatField()
lat = models.FloatField() lat = models.FloatField()
# GeoDjango-specific: a geometry field (MultiPolygonField), and # GeoDjango-specific: a geometry field (MultiPolygonField)
# overriding the default manager with a GeoManager instance.
mpoly = models.MultiPolygonField() mpoly = models.MultiPolygonField()
objects = models.GeoManager()
# Returns the string representation of the model. # Returns the string representation of the model.
def __str__(self): # __unicode__ on Python 2 def __str__(self): # __unicode__ on Python 2
return self.name return self.name
Please note two important things: Note that the ``models`` module is imported from ``django.contrib.gis.db``.
1. The ``models`` module is imported from ``django.contrib.gis.db``.
2. You must override the model's default manager with
:class:`~django.contrib.gis.db.models.GeoManager` to perform spatial queries.
The default spatial reference system for geometry fields is WGS84 (meaning The default spatial reference system for geometry fields is WGS84 (meaning
the `SRID`__ is 4326) -- in other words, the field coordinates are in the `SRID`__ is 4326) -- in other words, the field coordinates are in
@ -579,7 +573,6 @@ directly into the ``models.py`` of a GeoDjango application::
lon = models.FloatField() lon = models.FloatField()
lat = models.FloatField() lat = models.FloatField()
geom = models.MultiPolygonField(srid=4326) geom = models.MultiPolygonField(srid=4326)
objects = models.GeoManager()
# Auto-generated `LayerMapping` dictionary for WorldBorder model # Auto-generated `LayerMapping` dictionary for WorldBorder model
worldborders_mapping = { worldborders_mapping = {

View File

@ -455,13 +455,10 @@ Throughout this section, we will use the term "automatic manager" to mean a
manager that Django creates for you -- either as a default manager on a model manager that Django creates for you -- either as a default manager on a model
with no managers, or to use temporarily when accessing related objects. with no managers, or to use temporarily when accessing related objects.
Sometimes this default class won't be the right choice. One example is in the Sometimes this default class won't be the right choice. The default manager
:mod:`django.contrib.gis` application that ships with Django itself. All ``gis`` may not have all the methods you need to work with your data. A custom manager
models must use a special manager class (:class:`~django.contrib.gis.db.models.GeoManager`) class of your own will allow you to create custom ``QuerySet`` objects to give
because they need a special queryset (:class:`~django.contrib.gis.db.models.GeoQuerySet`) you the information you need.
to be used for interacting with the database. It turns out that models which require
a special manager like this need to use the same manager class wherever an automatic
manager is created.
Django provides a way for custom manager developers to say that their manager Django provides a way for custom manager developers to say that their manager
class should be used for automatic managers whenever it is the default manager class should be used for automatic managers whenever it is the default manager
@ -490,8 +487,7 @@ it will use :class:`django.db.models.Manager`.
Writing correct Managers for use in automatic Manager instances Writing correct Managers for use in automatic Manager instances
--------------------------------------------------------------- ---------------------------------------------------------------
As already suggested by the :mod:`django.contrib.gis` example, above, the The ``use_for_related_fields`` feature is primarily for managers that need to
``use_for_related_fields`` feature is primarily for managers that need to
return a custom ``QuerySet`` subclass. In providing this functionality in your return a custom ``QuerySet`` subclass. In providing this functionality in your
manager, there are a couple of things to remember. manager, there are a couple of things to remember.