Merge pull request #12 from maxmind/greg/ws-v2.1

Update Python API for v2.1 of web services

Author: oalders

HISTORY.rst

@@ -3,6 +3,16 @@
 History
 -------
 
+0.6.0 (2014-07-XX)
+++++++++++++++++++
+
+* The web service client API has been updated for the v2.1 release of the web
+  service. In particular, the ``city_isp_org`` and ``omni`` methods on
+  ``geoip2.webservice.Client`` should be considered deprecated. The ``city``
+  method now provides all of the data formerly provided by ``city_isp_org``,
+  and the ``omni`` method has been replaced by the ``insights`` method.
+
+
 0.5.1 (2014-03-28)
 ++++++++++++++++++
 
@@ -26,13 +36,13 @@ History
 0.4.1 (2013-10-25)
 ++++++++++++++++++
 
-* Read in `README.rst` as UTF-8 in `setup.py`.
+* Read in ``README.rst`` as UTF-8 in ``setup.py``.
 
 0.4.0 (2013-10-21)
 ++++++++++++++++++
 
-* API CHANGE: Changed the `languages` keyword argument to `locales` on the
-  constructors for `geoip.webservice.Client` and `geoip.database.Reader`.
+* API CHANGE: Changed the ``languages`` keyword argument to ``locales`` on the
+  constructors for ``geoip.webservice.Client`` and ``geoip.database.Reader``.
 
 0.3.1 (2013-10-15)
 ++++++++++++++++++
@@ -42,17 +52,17 @@ History
 0.3.0 (2013-10-15)
 ++++++++++++++++++
 
-* IMPORTANT: `geoip.webservices` was renamed `geoip.webservice` as it
+* IMPORTANT: ``geoip.webservices`` was renamed ``geoip.webservice`` as it
   contains only one class.
-* Added GeoIP2 database reader using maxminddb. This does not work with PyPy
-  as it relies on a C extension.
+* Added GeoIP2 database reader using ``maxminddb``. This does not work with
+  PyPy as it relies on a C extension.
 * Added more specific exceptions for web service client.
 
 0.2.2 (2013-06-20)
 ++++++++++++++++++
 
-* Fixed a bug in the model objects that prevented `longitude` and `metro_code`
-  from being used.
+* Fixed a bug in the model objects that prevented ``longitude`` and
+  ``metro_code`` from being used.
 
 0.2.1 (2013-06-10)
 ++++++++++++++++++
@@ -64,9 +74,9 @@ History
 ++++++++++++++++++
 
 * Support for Python 3.2 was dropped.
-* The methods to call the web service on the `Client` object now validate
+* The methods to call the web service on the ``Client`` object now validate
   the IP addresses before calling the web service. This requires the
-  `ipaddr` module on Python 2.x.
+  ``ipaddr`` module on Python 2.x.
 * We now support more languages. The new languages are de, es, fr, and pt-BR.
 * The REST API now returns a record with data about your account. There is
   a new geoip.records.MaxMind class for this data.

README.rst

@@ -70,9 +70,9 @@ Web Service Example
     >>> # key.
     >>> client = geoip2.webservice.Client(42, 'license_key')
     >>>
-    >>> # Replace "omni" with the method corresponding to the web service
-    >>> # that you are using, e.g., "country", "city_isp_org", "city".
-    >>> response = client.omni('128.101.101.101')
+    >>> # Replace "insights" with the method corresponding to the web service
+    >>> # that you are using, e.g., "country", "city".
+    >>> response = client.insights('128.101.101.101')
     >>>
     >>> response.country.iso_code
     'US'
@@ -101,8 +101,8 @@ Web Service Client Exceptions
 -----------------------------
 
 For details on the possible errors returned by the web service itself, see
-http://dev.maxmind.com/geoip/geoip2/web-services for the GeoIP2 web service
-docs.
+http://dev.maxmind.com/geoip/geoip2/web-services for the GeoIP2 Precision web
+service docs.
 
 If the web service returns an explicit error document, this is thrown as a
 ``AddressNotFoundError``, ``AuthenticationError``, ``InvalidRequestError``, or
@@ -162,6 +162,8 @@ City Database
 Connection-Type Database
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. code-block:: pycon
+
     >>> import geoip2.database
     >>>
     >>> # This creates a Reader object. You should use the same object
@@ -180,6 +182,8 @@ Connection-Type Database
 Domain Database
 ^^^^^^^^^^^^^^^
 
+.. code-block:: pycon
+
     >>> import geoip2.database
     >>>
     >>> # This creates a Reader object. You should use the same object
@@ -197,6 +201,8 @@ Domain Database
 ISP Database
 ^^^^^^^^^^^^
 
+.. code-block:: pycon
+
     >>> import geoip2.database
     >>>
     >>> # This creates a Reader object. You should use the same object

docs/conf.py

@@ -43,7 +43,7 @@
 
 # General information about the project.
 project = 'geoip2'
-copyright = '2013, Gregory Oschwald'
+copyright = '2014, MaxMind, Inc.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/index.rst

@@ -38,6 +38,6 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-:copyright: (c) 2013 by MaxMind, Inc.
+:copyright: (c) 2014 by MaxMind, Inc.
 :license: Apache License, Version 2.0
 

geoip2/__init__.py

@@ -1,7 +1,7 @@
 # pylint:disable=C0111
 
 __title__ = 'geoip2'
-__version__ = '0.5.1'
+__version__ = '0.6.0'
 __author__ = 'Gregory Oschwald'
 __license__ = 'Apache License, Version 2.0'
 __copyright__ = 'Copyright 2014 Maxmind, Inc.'

geoip2/database.py

@@ -16,8 +16,6 @@ class Reader(object):
 
     Instances of this class provide a reader for the GeoIP2 database format.
     IP addresses can be looked up using the ``country`` and ``city`` methods.
-    We also provide ``city_isp_org`` and ``omni`` methods to ease
-    compatibility with the web service client.
 
      Usage
      -----
@@ -68,26 +66,30 @@ def city(self, ip_address):
         return self._model_for(geoip2.models.City, ip_address)
 
     def city_isp_org(self, ip_address):
-        """Get the CityISPOrg object for the IP address
+        """Get the City object for the IP address
 
         :param ip_address: IPv4 or IPv6 address as a string. If no address
           is provided.
 
-        :returns: :py:class:`geoip2.models.CityISPOrg` object
+        :returns: :py:class:`geoip2.models.City` object
 
+        .. deprecated:: 0.6.0
+           Use :py:method:`city` instead.
         """
 
-        return self._model_for(geoip2.models.CityISPOrg, ip_address)
+        return self.city(ip_address)
 
     def omni(self, ip_address):
-        """Get the Omni object for the IP address
+        """Get the Insights object for the IP address
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
-        :returns: :py:class:`geoip2.models.Omni` object
+        :returns: :py:class:`geoip2.models.Insights` object
 
+        .. deprecated:: 0.6.0
+           Use :py:method:`city` instead.
         """
-        return self._model_for(geoip2.models.Omni, ip_address)
+        return self._model_for(geoip2.models.Insights, ip_address)
 
     def connection_type(self, ip_address):
         """Get the ConnectionType object for the IP address

geoip2/models.py

@@ -3,10 +3,10 @@
 ======
 
 These classes provide models for the data returned by the GeoIP2
-end points.
+web service and databases.
 
-The only difference between the City, City/ISP/Org, and Omni model classes is
-which fields in each record may be populated. See
+The only difference between the City and Insights model classes is which
+fields in each record may be populated. See
 http://dev.maxmind.com/geoip/geoip2/web-services for more details.
 
 """
@@ -16,7 +16,7 @@
 
 class Country(object):
 
-    """Model class for the GeoIP2 Country
+    """Model for the GeoIP2 Precision: Country and the GeoIP2 Country database
 
     This class provides the following attributes:
 
@@ -51,8 +51,7 @@ class Country(object):
 
       Object for the country represented by the users of the IP address
       when that country is different than the country in ``country``. For
-      instance, the country represented by an overseas military base or
-      embassy.
+      instance, the country represented by an overseas military base.
 
       :type: :py:class:`geoip2.records.RepresentedCountry`
 
@@ -92,8 +91,7 @@ def __init__(self, raw_response, locales=None):
 
 class City(Country):
 
-    """Model class for the GeoIP2 Precision City
-
+    """Model for the GeoIP2 Precision: City and the GeoIP2 City database
     .. attribute:: city
 
       City object for the requested IP address.
@@ -135,8 +133,7 @@ class City(Country):
 
       Object for the country represented by the users of the IP address
       when that country is different than the country in ``country``. For
-      instance, the country represented by an overseas military base or
-      embassy.
+      instance, the country represented by an overseas military base.
 
       :type: :py:class:`geoip2.records.RepresentedCountry`
 
@@ -153,7 +150,7 @@ class City(Country):
 
       :type: :py:class:`geoip2.records.Traits`
 
-"""
+    """
 
     def __init__(self, raw_response, locales=None):
         super(City, self).__init__(raw_response, locales)
@@ -168,75 +165,9 @@ def __init__(self, raw_response, locales=None):
                                         *raw_response.get('subdivisions', []))
 
 
-class CityISPOrg(City):
-
-    """Model class for the GeoIP2 Precision City/ISP/Org
-
-    .. attribute:: city
-
-      City object for the requested IP address.
-
-      :type: :py:class:`geoip2.records.City`
-
-    .. attribute:: continent
-
-      Continent object for the requested IP address.
-
-      :type: :py:class:`geoip2.records.Continent`
-
-    .. attribute:: country
-
-      Country object for the requested IP address. This record represents the
-      country where MaxMind believes the IP is located.
-
-      :type: :py:class:`geoip2.records.Country`
-
-    .. attribute:: location
-
-      Location object for the requested IP address.
-
-    .. attribute:: maxmind
-
-      Information related to your MaxMind account.
-
-      :type: :py:class:`geoip2.records.MaxMind`
-
-    .. attribute:: registered_country
-
-      The registered country object for the requested IP address. This record
-      represents the country where the ISP has registered a given IP block in
-      and may differ from the user's country.
-
-      :type: :py:class:`geoip2.records.Country`
-
-    .. attribute:: represented_country
-
-      Object for the country represented by the users of the IP address
-      when that country is different than the country in ``country``. For
-      instance, the country represented by an overseas military base or
-      embassy.
-
-      :type: :py:class:`geoip2.records.RepresentedCountry`
-
-    .. attribute:: subdivisions
-
-      Object (tuple) representing the subdivisions of the country to which
-      the location of the requested IP address belongs.
-
-      :type: :py:class:`geoip2.records.Subdivisions`
-
-    .. attribute:: traits
-
-      Object with the traits of the requested IP address.
-
-      :type: :py:class:`geoip2.records.Traits`
-
-    """
-
-
-class Omni(CityISPOrg):
+class Insights(City):
 
-    """Model class for the GeoIP2 Precision Omni
+    """Model for the GeoIP2 Precision: Insights web service endpoint
 
     .. attribute:: city
 
@@ -279,8 +210,7 @@ class Omni(CityISPOrg):
 
       Object for the country represented by the users of the IP address
       when that country is different than the country in ``country``. For
-      instance, the country represented by an overseas military base or
-      embassy.
+      instance, the country represented by an overseas military base.
 
       :type: :py:class:`geoip2.records.RepresentedCountry`