From c9fb4f3c45b668c9a32f9ecdfe404566657df88e Mon Sep 17 00:00:00 2001 From: Brendan Hayward Date: Fri, 8 May 2015 22:52:15 +0500 Subject: [PATCH] Fixed #25205 -- Removed doc references to deprecated GeoManager class. --- AUTHORS | 1 + docs/ref/contrib/gis/db-api.txt | 7 ++-- docs/ref/contrib/gis/functions.txt | 3 +- docs/ref/contrib/gis/geoquerysets.txt | 2 ++ docs/ref/contrib/gis/layermapping.txt | 1 - docs/ref/contrib/gis/model-api.txt | 51 ++++++++++++++------------- docs/ref/contrib/gis/tutorial.txt | 11 ++---- docs/topics/db/managers.txt | 14 +++----- 8 files changed, 42 insertions(+), 48 deletions(-) diff --git a/AUTHORS b/AUTHORS index 3738589d5a..7d594f0329 100644 --- a/AUTHORS +++ b/AUTHORS @@ -105,6 +105,7 @@ answer newbie questions, and generally made Django that much better: Bouke Haarsma Božidar Benko Brant Harris + Brendan Hayward Brenton Simpson Brett Cannon Brett Hoerner diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index cecb02de6c..36e8e2a9bf 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -226,18 +226,17 @@ in southern Texas:: # A projected coordinate system (only valid for South Texas!) # is used, units are in meters. point = models.PointField(srid=32140) - objects = models.GeoManager() 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 geoapp import SouthTexasCity + >>> from geoapp.models import SouthTexasCity # Distances will be calculated from this point, which does not have to be projected. >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # If numeric parameter, units of field (meters in this case) are assumed. >>> 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_gte=(pnt, D(mi=20))) >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100))) diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index 6f59010d5b..06fe57fe99 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/docs/ref/contrib/gis/functions.txt @@ -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`` queryset is calculated:: + >>> from django.contrib.gis.db.models.functions import Distance >>> 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) Wollongong 990071.220408 m Shellharbour 972804.613941 m diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index 8dc4c7dac7..d4b83e86c8 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -629,6 +629,8 @@ Oracle ``SDO_WITHIN_DISTANCE(poly, geom, 5)`` This lookup is not available on SpatiaLite. +.. _geoqueryset-methods: + ``GeoQuerySet`` Methods ======================= diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index 69589b05c3..9c7bb82ffb 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -57,7 +57,6 @@ Example class TestGeo(models.Model): name = models.CharField(max_length=25) # corresponds to the 'str' field poly = models.PolygonField(srid=4269) # we want our model in a different SRID - objects = models.GeoManager() def __str__(self): # __unicode__ on Python 2 return 'Name: %s' % self.name diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index d6fde26c14..fb44a5c41c 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -14,7 +14,6 @@ of a `Digital Elevation Model`__ as our examples:: class Zipcode(models.Model): code = models.CharField(max_length=5) poly = models.PolygonField() - objects = models.GeoManager() class Elevation(models.Model): 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 .. class:: GeoManager -In order to conduct geographic queries, each geographic model requires -a ``GeoManager`` model manager. This manager allows for the proper SQL -construction for geographic queries; thus, without it, all geographic filters -will fail. +The ``GeoManager`` is required in order to use the legacy +:ref:`geoqueryset-methods`. -.. note:: +.. deprecated:: 1.9 - Geographic filtering support is limited to geometry fields. ``RasterField`` - does not currently allow spatial querying. + All ``GeoQuerySet`` methods have been deprecated and replaced by + :doc:`equivalent database 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 -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:: +.. versionchanged:: 1.9 - 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): - 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() + ``GeoManager`` was required even if the model did 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:: -The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, -for example:: + from django.contrib.gis.db import models - 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 .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL `_. diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index f869e97729..a41b5ed042 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -238,20 +238,14 @@ model to represent this data:: lon = models.FloatField() lat = models.FloatField() - # GeoDjango-specific: a geometry field (MultiPolygonField), and - # overriding the default manager with a GeoManager instance. + # GeoDjango-specific: a geometry field (MultiPolygonField) mpoly = models.MultiPolygonField() - objects = models.GeoManager() # Returns the string representation of the model. def __str__(self): # __unicode__ on Python 2 return self.name -Please note two important things: - -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. +Note that the ``models`` module is imported from ``django.contrib.gis.db``. The default spatial reference system for geometry fields is WGS84 (meaning 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() lat = models.FloatField() geom = models.MultiPolygonField(srid=4326) - objects = models.GeoManager() # Auto-generated `LayerMapping` dictionary for WorldBorder model worldborders_mapping = { diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index bd46a34c07..ae5bed536f 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -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 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 -:mod:`django.contrib.gis` application that ships with Django itself. All ``gis`` -models must use a special manager class (:class:`~django.contrib.gis.db.models.GeoManager`) -because they need a special queryset (:class:`~django.contrib.gis.db.models.GeoQuerySet`) -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. +Sometimes this default class won't be the right choice. The default manager +may not have all the methods you need to work with your data. A custom manager +class of your own will allow you to create custom ``QuerySet`` objects to give +you the information you need. 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 @@ -490,8 +487,7 @@ it will use :class:`django.db.models.Manager`. Writing correct Managers for use in automatic Manager instances --------------------------------------------------------------- -As already suggested by the :mod:`django.contrib.gis` example, above, the -``use_for_related_fields`` feature is primarily for managers that need to +The ``use_for_related_fields`` feature is primarily for managers that need to return a custom ``QuerySet`` subclass. In providing this functionality in your manager, there are a couple of things to remember.