Updated API for new document format including subdivisions, removal of is_transparent_proxy, iso_code, and a separate postal hash

Author: oschwald

geoip2/models.py

@@ -77,9 +77,11 @@ def __init__(self, raw_response, languages=None):
             geoip2.records.City(languages, **raw_response.get('city', {}))
         self.location = \
             geoip2.records.Location(**raw_response.get('location', {}))
-        self.region = \
-            geoip2.records.Region(languages,
-                                  **raw_response.get('region', {}))
+        self.postal = \
+            geoip2.records.Postal(**raw_response.get('postal', {}))
+        self.subdivisions = \
+            geoip2.records.Subdivisions(languages,
+                                        *raw_response.get('subdivisions', []))
 
 
 class CityISPOrg(City):

geoip2/records.py

@@ -1,8 +1,12 @@
 """
+
 Records
 =======
+
 """
+
 from abc import ABCMeta
+import collections
 
 
 class Record(object):
@@ -23,7 +27,7 @@ class PlaceRecord(Record):
 
     def __init__(self, languages=None, **kwargs):
         if languages is None:
-            languages = []
+            languages = ['en']
         object.__setattr__(self, 'languages', languages)
         super(PlaceRecord, self).__init__(**kwargs)
 
@@ -46,7 +50,7 @@ class City(PlaceRecord):
       confidence that the city is correct. This attribute is only available
       from the Omni end point.
     :ivar geoname_id: This returns a GeoName ID for the city. This attribute
-      is returned by all end points.
+ N     is returned by all end points.
     :ivar name: Returns the name of the city based on the languages list
       passed to the constructor. This attribute is returned by all end points.
     :ivar names: This returns a dictionary where the keys are language codes
@@ -94,10 +98,7 @@ class Country(PlaceRecord):
       from the Omni end point.
     :ivar geoname_id: This returns a GeoName ID for the country. This attribute
       is returned by all end points.
-    :ivar iso_3166_1_alpha_2: This returns the two-character ISO 3166-1
-      (http://en.wikipedia.org/wiki/ISO_3166-1) alpha code for the country.
-      This attribute is returned by all end points.
-    :ivar iso_3166_1_alpha_3: This returns the three-character ISO 3166-1
+    :ivar iso_code: This returns the two-character ISO 3166-1
       (http://en.wikipedia.org/wiki/ISO_3166-1) alpha code for the country.
       This attribute is returned by all end points.
     :ivar name: Returns the name of the country based on the languages list
@@ -106,8 +107,7 @@ class Country(PlaceRecord):
       and the values are names. This attribute is returned by all end points.
 
     """
-    _valid_attributes = set(['confidence', 'geoname_id', 'iso_3166_1_alpha_2',
-                             'iso_3166_1_alpha_3', 'names'])
+    _valid_attributes = set(['confidence', 'geoname_id', 'iso_code', 'names'])
 
 
 class Location(Record):
@@ -134,13 +134,6 @@ class Location(Record):
       (https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions).
       This attribute is returned by all end points except the Country end
       point.
-    :ivar postal_code: This returns the postal code of the location. Postal
-      codes are not available for all countries. In some countries, this will
-      only contain part of the postal code. This attribute is returned by all
-      end points except the Country end point.
-    :ivar postal_confidence: This returns a value from 0-100 indicating
-      MaxMind's confidence that the postal code is correct. This attribute is
-      only available from the Omni end point.
     :ivar time_zone: This returns the time zone associated with location, as
       specified by the IANA Time Zone Database
       (http://www.iana.org/time-zones), e.g., "America/New_York". This
@@ -152,32 +145,94 @@ class Location(Record):
                              'time_zone'])
 
 
-class Region(PlaceRecord):
-    """Contains data for the region record associated with an IP address
+class Postal(Record):
+    """Contains data for the postal record associated with an IP address
+
+    This class contains the postal data associated with an IP address.
+
+    This record is returned by all the end points except the Country end point.
+
+    Attributes:
+
+    :ivar code: This returns the postal code of the location. Postal
+      codes are not available for all countries. In some countries, this will
+      only contain part of the postal code. This attribute is returned by all
+      end points except the Country end point.
+    :ivar confidence: This returns a value from 0-100 indicating
+      MaxMind's confidence that the postal code is correct. This attribute is
+      only available from the Omni end point.
+
+    """
+    _valid_attributes = set(['code', 'confidence'])
+
+
+class Subdivision(PlaceRecord):
+    """Contains data a subdivisions associated with an IP address
 
-    This class contains the region-level data associated with an IP address.
+    This class contains the subdivision data associated with an IP address.
 
     This record is returned by all the end points except the Country end point.
 
     Attributes:
 
     :ivar confidence: This is a value from 0-100 indicating MaxMind's
-      confidence that the region is correct. This attribute is only available
-      from the Omni end point.
-    :ivar geoname_id: This is a GeoName ID for the region. This attribute
-      is returned by all end points.
-    :ivar iso_3166_2: This is a string up to three characters long
-      contain the region portion of the ISO 3166-2 code
+      confidence that the subdivision is correct. This attribute is only
+      available from the Omni end point.
+    :ivar geoname_id: This is a GeoName ID for the subdivision. This
+      attribute is returned by all end points.
+    :ivar iso_code: This is a string up to three characters long
+      contain the subdivision portion of the ISO 3166-2 code
       (http://en.wikipedia.org/wiki/ISO_3166-2). This attribute is returned
       by all end points.
-    :ivar name: The name of the region based on the languages list
+    :ivar name: The name of the subdivision based on the languages list
       passed to the constructor. This attribute is returned by all end points.
     :ivar names: A dictionary where the keys are language codes and the
       values are names. This attribute is returned by all end points.
 
     """
-    _valid_attributes = set(['confidence', 'geoname_id', 'iso_3166_2',
-                             'names'])
+    _valid_attributes = set(['confidence', 'geoname_id', 'iso_code', 'names'])
+
+
+class Subdivisions(collections.namedtuple('Subdivisions',
+                                          'subdivision_1 subdivision_2 '
+                                          'subdivision_3')):
+    """Contains data for the subdivisions associated with an IP address
+
+    This class contains the subdivisions of the country associated with the
+    IP address.
+
+    For instance, the response for Oxford in the United Kingdom would have
+    England as subdivision_1 and Oxfordshire as subdivision_2.
+
+    This record is returned by all the end points except the Country end point.
+
+    Attributes:
+
+    :ivar subdivision_1: The first-level (largest) subdivision associated with
+      the location of the IP address. Many countries will only have this
+      subdivision. For instance, in the United States, this would be a state.
+    :ivar subdivision_2: The second-level subdivision associated with the
+      location of the IP address.
+    :ivar subdivision_3: The third-level subdivsion associated with the
+      locatin of the IP address.
+
+    """
+    __slots__ = ()
+
+    def __new__(cls, languages, subdivision_1=None, subdivision_2=None,
+                subdivision_3=None):
+        if subdivision_1 is None:
+            subdivision_1 = {}
+        if subdivision_2 is None:
+            subdivision_2 = {}
+        if subdivision_3 is None:
+            subdivision_3 = {}
+
+        subdivision_1 = Subdivision(languages, **subdivision_1)
+        subdivision_2 = Subdivision(languages, **subdivision_2)
+        subdivision_3 = Subdivision(languages, **subdivision_3)
+        return super(cls, Subdivisions).__new__(cls, subdivision_1,
+                                                subdivision_2, subdivision_3)
 
 
 class Traits(Record):
@@ -189,7 +244,7 @@ class Traits(Record):
 
     This class has the following attributes:
 
-    :ivar autonomous_system_number: This returns the autonomous system 
+    :ivar autonomous_system_number: This returns the autonomous system
       number (http://en.wikipedia.org/wiki/Autonomous_system_(Internet))
       associated with the IP address. This attribute is only available from
       the City/ISP/Org and Omni end points.
@@ -211,8 +266,6 @@ class Traits(Record):
     :ivar is_anonymous_proxy: This returns true if the IP is an anonymous
       proxy. See http://dev.maxmind.com/faq/geoip#anonproxy for further
       details. This attribute is returned by all end points.
-    :ivar is_transparent_proxy: This returns true if the IP is a transparent
-      proxy. This attribute is returned by all end points.
     :ivar isp: This returns the name of the ISP associated the IP address.
       This attribute is only available from the City/ISP/Org and Omni end
       points.
@@ -246,14 +299,12 @@ class Traits(Record):
                              'domain',
                              'is_anonymous_proxy',
                              'is_satellite_provider',
-                             'is_transparent_proxy',
                              'isp',
                              'ip_address',
                              'organization',
                              'user_type'])
 
     def __init__(self, languages=None, **kwargs):
-        for k in ['is_anonymous_proxy', 'is_satellite_provider',
-                  'is_transparent_proxy']:
+        for k in ['is_anonymous_proxy', 'is_satellite_provider']:
             kwargs[k] = bool(kwargs.get(k, False))
         super(Traits, self).__init__(**kwargs)

tests/models_test.py

@@ -38,15 +38,21 @@ def test_omni_full(self):
                 'time_zone': 'America/Chicago',
                 },
             'postal': {
-                code: '55401',
-                confidence: 33,
+                'code': '55401',
+                'confidence': 33,
                 },
             'subdivisions': [{
                 'confidence': 88,
                 'geoname_id': 574635,
                 'iso_code': 'MN',
                 'names': {'en': 'Minnesota'},
-                }],
+                },
+                {
+                'geoname_id': 123,
+                'iso_code': 'HP',
+                'names': {'en': 'Hennepin'},
+                }
+            ],
             'registered_country': {
                 'geoname_id': 2,
                 'iso_code': 'CA',
@@ -58,7 +64,6 @@ def test_omni_full(self):
                 'domain': 'example.com',
                 'ip_address': '1.2.3.4',
                 'is_anonymous_proxy': 0,
-                'is_transparent_proxy': 1,
                 'is_us_military': 1,
                 'isp': 'Comcast',
                 'network_speed': 'cable/DSL',
@@ -81,11 +86,22 @@ def test_omni_full(self):
                          'geoip2.records.Country object')
         self.assertEqual(type(model.location), geoip2.records.Location,
                          'geoip2.records.Location object')
-        self.assertEqual(type(model.region), geoip2.records.Region,
-                         'geoip2.records.Regin object')
+        self.assertEqual(type(model.subdivisions.subdivision_1),
+                         geoip2.records.Subdivision,
+                         'geoip2.records.Subdivision object')
         self.assertEqual(type(model.traits), geoip2.records.Traits,
                          'geoip2.records.Traits object')
         self.assertEqual(model.raw, raw, 'raw method returns raw input')
+        self.assertEqual(model.subdivisions.subdivision_1.iso_code, 'MN',
+                         'div 1 has correct iso_code')
+        self.assertEqual(model.subdivisions.subdivision_1.confidence, 88,
+                         'div 1 has correct confidence')
+        self.assertEqual(model.subdivisions.subdivision_1.geoname_id, 574635,
+                         'div 1 has correct geoname_id')
+        self.assertEqual(model.subdivisions.subdivision_1.names,
+                         {'en': 'Minnesota'}, 'div 1 names are correct')
+        self.assertEqual(model.subdivisions.subdivision_2.name, 'Hennepin',
+                         'div 2 has correct name')
 
     def test_omni_min(self):
         model = geoip2.models.Omni({'traits': {'ip_address': '5.6.7.8'}})
@@ -102,8 +118,9 @@ def test_omni_min(self):
                          'geoip2.records.Country object')
         self.assertEqual(type(model.location), geoip2.records.Location,
                          'geoip2.records.Location object')
-        self.assertEqual(type(model.region), geoip2.records.Region,
-                         'geoip2.records.Regin object')
+        self.assertEqual(type(model.subdivisions.subdivision_1),
+                         geoip2.records.Subdivision,
+                         'geoip2.records.Subdivision object')
         self.assertEqual(type(model.traits), geoip2.records.Traits,
                          'geoip2.records.Traits object')
 
@@ -143,8 +160,9 @@ def test_city_full(self):
                          'geoip2.records.Country object')
         self.assertEqual(type(model.location), geoip2.records.Location,
                          'geoip2.records.Location object')
-        self.assertEqual(type(model.region), geoip2.records.Region,
-                         'geoip2.records.Regin object')
+        self.assertEqual(type(model.subdivisions.subdivision_1), 
+                         geoip2.records.Subdivision,
+                         'geoip2.records.Subdivision object')
         self.assertEqual(type(model.traits), geoip2.records.Traits,
                          'geoip2.records.Traits object')
         self.assertEqual(model.raw, raw, 'raw method returns raw input')
@@ -177,8 +195,6 @@ def test_city_full(self):
                          'registered_country name is correct')
         self.assertEqual(model.traits.is_anonymous_proxy, False,
                          'traits is_anonymous_proxy returns False by default')
-        self.assertEqual(model.traits.is_transparent_proxy, False,
-                         'traits is_anonymous_proxy returns False by default')
         self.assertEqual(model.traits.is_satellite_provider, True,
                          'traits is_setellite_provider is True')
         self.assertEqual(model.raw, raw, 'raw method produces raw output')

tests/webservices_test.py

@@ -38,8 +38,7 @@ def setUp(self):
             },
         'country': {
             'geoname_id': 1,
-            'iso_3166_1_alpha_2': 'US',
-            'iso_3166_1_alpha_3': 'USA',
+            'iso_code': 'US',
             'names': { 'en': 'United States of America'}
             },
         'traits': {'ip_address': '1.2.3.4',},
@@ -83,10 +82,8 @@ def test_country_ok(self, get):
                          'continent name is North America')
         self.assertEqual(country.country.geoname_id, 1,
                          'country geoname_id is 1')
-        self.assertEqual(country.country.iso_3166_1_alpha_2, 'US',
-                         'country iso_3166_1_alpha_2 is US')
-        self.assertEqual(country.country.iso_3166_1_alpha_3, 'USA',
-                         'country iso_3166_1_alpha_3 is USA')
+        self.assertEqual(country.country.iso_code, 'US',
+                         'country iso_code is US')
         self.assertEqual(country.country.names,
                          { 'en': 'United States of America' },
                          'country names' )