summaryrefslogtreecommitdiff
path: root/parts/django/docs/ref/contrib/gis/geoip.txt
diff options
context:
space:
mode:
authorNishanth Amuluru2011-01-08 11:20:57 +0530
committerNishanth Amuluru2011-01-08 11:20:57 +0530
commit65411d01d448ff0cd4abd14eee14cf60b5f8fc20 (patch)
treeb4c404363c4c63a61d6e2f8bd26c5b057c1fb09d /parts/django/docs/ref/contrib/gis/geoip.txt
parent2e35094d43b4cc6974172e1febf76abb50f086ec (diff)
downloadpytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.gz
pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.bz2
pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.zip
Added buildout stuff and made changes accordingly
--HG-- rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt rename : taskapp/models.py => parts/django/django/conf/app_template/models.py rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py rename : taskapp/views.py => parts/django/django/conf/app_template/views.py rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py rename : profile/forms.py => pytask/profile/forms.py rename : profile/management/__init__.py => pytask/profile/management/__init__.py rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py rename : profile/models.py => pytask/profile/models.py rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py rename : taskapp/tests.py => pytask/profile/tests.py rename : profile/urls.py => pytask/profile/urls.py rename : profile/utils.py => pytask/profile/utils.py rename : profile/views.py => pytask/profile/views.py rename : static/css/base.css => pytask/static/css/base.css rename : taskapp/tests.py => pytask/taskapp/tests.py rename : taskapp/views.py => pytask/taskapp/views.py rename : templates/base.html => pytask/templates/base.html rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html rename : templates/profile/edit.html => pytask/templates/profile/edit.html rename : templates/profile/view.html => pytask/templates/profile/view.html rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html rename : templates/registration/activate.html => pytask/templates/registration/activate.html rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html rename : templates/registration/login.html => pytask/templates/registration/login.html rename : templates/registration/logout.html => pytask/templates/registration/logout.html rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html rename : utils.py => pytask/utils.py
Diffstat (limited to 'parts/django/docs/ref/contrib/gis/geoip.txt')
-rw-r--r--parts/django/docs/ref/contrib/gis/geoip.txt223
1 files changed, 223 insertions, 0 deletions
diff --git a/parts/django/docs/ref/contrib/gis/geoip.txt b/parts/django/docs/ref/contrib/gis/geoip.txt
new file mode 100644
index 0000000..784d69e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/geoip.txt
@@ -0,0 +1,223 @@
+.. _ref-geoip:
+
+======================
+Geolocation with GeoIP
+======================
+
+.. module:: django.contrib.gis.utils.geoip
+ :synopsis: High-level Python interface for MaxMind's GeoIP C library.
+
+.. currentmodule:: django.contrib.gis.utils
+
+The :class:`GeoIP` object is a ctypes wrapper for the
+`MaxMind GeoIP C API`__. [#]_ This interface is a BSD-licensed alternative
+to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind.
+
+In order to perform IP-based geolocation, the :class:`GeoIP` object requires
+the GeoIP C libary and either the GeoIP `Country`__ or `City`__
+datasets in binary format (the CSV files will not work!). These datasets may be
+`downloaded from MaxMind`__. Grab the ``GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz``
+and unzip them in a directory corresponding to what you set
+``GEOIP_PATH`` with in your settings. See the example and reference below
+for more details.
+
+__ http://www.maxmind.com/app/c
+__ http://www.maxmind.com/app/python
+__ http://www.maxmind.com/app/country
+__ http://www.maxmind.com/app/city
+__ http://www.maxmind.com/download/geoip/database/
+
+Example
+=======
+
+Assuming you have the GeoIP C library installed, here is an example of its
+usage::
+
+ >>> from django.contrib.gis.utils 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
+==================
+
+.. setting:: GEOIP_PATH
+
+GEOIP_PATH
+----------
+
+A string specifying the directory where the GeoIP data files are
+located. This setting is *required* unless manually specified
+with ``path`` keyword when initializing the :class:`GeoIP` object.
+
+.. setting:: GEOIP_LIBRARY_PATH
+
+GEOIP_LIBRARY_PATH
+------------------
+
+A string specifying the location of the GeoIP C library. Typically,
+this setting is only used if the GeoIP C library is in a non-standard
+location (e.g., ``/home/sue/lib/libGeoIP.so``).
+
+.. setting:: GEOIP_COUNTRY
+
+GEOIP_COUNTRY
+-------------
+
+The basename to use for the GeoIP country data file.
+Defaults to ``'GeoIP.dat'``.
+
+.. setting:: GEOIP_CITY
+
+GEOIP_CITY
+----------
+
+The basename to use for the GeoIP city data file.
+Defaults to ``'GeoLiteCity.dat'``.
+
+``GeoIP`` API
+=============
+
+.. class:: GeoIP([path=None, cache=0, country=None, city=None])
+
+The ``GeoIP`` object does not require any parameters to use the default
+settings. However, at the very least the :setting:`GEOIP_PATH` setting
+should be set with the path of the location of your GeoIP data sets. The
+following intialization keywords may be used to customize any of the
+defaults.
+
+=================== =======================================================
+Keyword Arguments Description
+=================== =======================================================
+``path`` Base directory to where GeoIP data is located or the
+ full path to where the city or country data files
+ (.dat) are located. Assumes that both the city and
+ country data sets are located in this directory;
+ overrides the :setting:`GEOIP_PATH` settings attribute.
+
+``cache`` The cache settings when opening up the GeoIP datasets,
+ and may be an integer in (0, 1, 2, 4) corresponding to
+ the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``,
+ ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE``
+ ``GeoIPOptions`` C API settings, respectively.
+ Defaults to 0 (``GEOIP_STANDARD``).
+
+``country`` The name of the GeoIP country data file. Defaults
+ to ``GeoIP.dat``. Setting this keyword overrides the
+ :setting:`GEOIP_COUNTRY` settings attribute.
+
+``city`` The name of the GeoIP city data file. Defaults to
+ ``GeoLiteCity.dat``. Setting this keyword overrides
+ the :setting:`GEOIP_CITY` settings attribute.
+=================== =======================================================
+
+``GeoIP`` Methods
+=================
+
+Querying
+--------
+
+All the following querying routines may take either a string IP address
+or a fully qualified domain name (FQDN). For example, both
+``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query
+parameters.
+
+.. method:: GeoIP.city(query)
+
+Returns a dictionary of city information for the given query. Some
+of the values in the dictionary may be undefined (``None``).
+
+.. method:: GeoIPcountry(query)
+
+Returns a dictionary with the country code and country for the given
+query.
+
+.. method:: GeoIP.country_code(query)
+
+Returns only the country code corresponding to the query.
+
+.. method:: GeoIP.country_name(query)
+
+Returns only the country name corresponding to the query.
+
+Coordinate Retrieval
+--------------------
+
+.. method:: GeoIP.coords(query)
+
+Returns a coordinate tuple of (longitude, latitude).
+
+.. method:: GeoIP.lon_lat(query)
+
+Returns a coordinate tuple of (longitude, latitude).
+
+.. method:: GeoIP.lat_lon(query)
+
+Returns a coordinate tuple of (latitude, longitude),
+
+.. method:: GeoIP.geos(query)
+
+Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query.
+
+Database Information
+--------------------
+
+.. attribute:: GeoIP.country_info
+
+This property returns information about the GeoIP country database.
+
+.. attribute:: GeoIP.city_info
+
+This property returns information about the GeoIP city database.
+
+.. attribute:: GeoIP.info
+
+This property returns information about all GeoIP databases (both city
+and country).
+
+GeoIP-Python API compatibility methods
+----------------------------------------
+
+These methods exist to ease compatibility with any code using MaxMind's
+existing Python API.
+
+.. classmethod:: GeoIP.open(path, cache)
+
+This classmethod instantiates the GeoIP object from the given database path
+and given cache setting.
+
+.. method:: GeoIP.region_by_addr(query)
+
+.. method:: GeoIP.region_by_name(query)
+
+.. method:: GeoIP.record_by_addr(query)
+
+.. method:: GeoIP.record_by_name(query)
+
+.. method:: GeoIP.country_code_by_addr(query)
+
+.. method:: GeoIP.country_code_by_name(query)
+
+.. method:: GeoIP.country_name_by_addr(query)
+
+.. method:: GeoIP.country_name_by_name(query)
+
+.. rubric:: Footnotes
+.. [#] GeoIP(R) is a registered trademark of MaxMind, LLC of Boston, Massachusetts.