Added most_specific method to Subdivisions

This method throws a ValueError exception if the object does not contain
any Subdivision objects

Author: oschwald

geoip2/records.py

@@ -210,6 +210,18 @@ def __new__(cls, languages, *subdivisions):
         subdivisions = [Subdivision(languages, **x) for x in subdivisions]
         return super(cls, Subdivisions).__new__(cls, subdivisions)
 
+    def most_specific(self):
+        """The most specific subdivision available
+
+        :returns: The most specific (smallest) :py:class:`Subdivision`
+        :raises: :py:exc:`ValueError` if :py:class:`Subdivisions` does
+          not contain any :py:class:`Subdivision` objects
+
+        """
+        try:
+            return self[-1]
+        except IndexError:
+            raise ValueError('No subdivisions are available');
 
 class Traits(Record):
     """ Contains data for the traits record associated with an IP address

tests/models_test.py

@@ -102,6 +102,8 @@ def test_omni_full(self):
                          {'en': 'Minnesota'}, 'div 1 names are correct')
         self.assertEqual(model.subdivisions[1].name, 'Hennepin',
                          'div 2 has correct name')
+        self.assertEqual(model.subdivisions.most_specific().iso_code, 'HP',
+                          'subdivisions.most_specific returns HP')
 
     def test_omni_min(self):
         model = geoip2.models.Omni({'traits': {'ip_address': '5.6.7.8'}})
@@ -120,6 +122,9 @@ def test_omni_min(self):
                          'geoip2.records.Location object')
         self.assertEqual(type(model.traits), geoip2.records.Traits,
                          'geoip2.records.Traits object')
+        with self.assertRaisesRegex(ValueError,
+                                    'No subdivisions are available'):
+            model.subdivisions.most_specific()
 
     def test_city_full(self):
         raw = {