Merge pull request maxmind#36 from maxmind/greg/credit-exceptions

Add credit errors, use ipaddress, doc tweaks

Author: rafl

HISTORY.rst

@@ -3,9 +3,13 @@
 History
 -------
 
-2.3.1 (2016-XX-XX)
+2.4.0 (2016-XX-XX)
 ++++++++++++++++++
 
+* This module now uses ``ipaddress`` on Python 2 rather than ``ipaddr`` to
+  validate IP addresses before sending them to the web service.
+* Added handling of additional error codes that the web service may return.
+* PEP 257 documentation fixes.
 * Updated documentation to reflect that the accuracy radius is now included
   in City.
 

geoip2/compat.py

@@ -0,0 +1,17 @@
+"""Intended for internal use only."""
+import sys
+
+import ipaddress
+
+# pylint: skip-file
+
+if sys.version_info[0] == 2:
+    def compat_ip_address(address):
+        """Intended for internal use only."""
+        if isinstance(address, bytes):
+            address = address.decode()
+        return ipaddress.ip_address(address)
+else:
+    def compat_ip_address(address):
+        """Intended for internal use only."""
+        return ipaddress.ip_address(address)

geoip2/database.py

@@ -41,7 +41,7 @@ class Reader(object):
 """
 
     def __init__(self, filename, locales=None, mode=MODE_AUTO):
-        """Create GeoIP2 Reader
+        """Create GeoIP2 Reader.
 
         :param filename: The path to the GeoIP2 database.
         :param locales: This is list of locale codes. This argument will be
@@ -89,7 +89,7 @@ def __exit__(self, exc_type, exc_value, traceback):
         self.close()
 
     def country(self, ip_address):
-        """Get the Country object for the IP address
+        """Get the Country object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -100,7 +100,7 @@ def country(self, ip_address):
         return self._model_for(geoip2.models.Country, 'Country', ip_address)
 
     def city(self, ip_address):
-        """Get the City object for the IP address
+        """Get the City object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -110,7 +110,7 @@ def city(self, ip_address):
         return self._model_for(geoip2.models.City, 'City', ip_address)
 
     def anonymous_ip(self, ip_address):
-        """Get the AnonymousIP object for the IP address
+        """Get the AnonymousIP object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -121,7 +121,7 @@ def anonymous_ip(self, ip_address):
                                     'GeoIP2-Anonymous-IP', ip_address)
 
     def connection_type(self, ip_address):
-        """Get the ConnectionType object for the IP address
+        """Get the ConnectionType object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -132,7 +132,7 @@ def connection_type(self, ip_address):
                                     'GeoIP2-Connection-Type', ip_address)
 
     def domain(self, ip_address):
-        """Get the Domain object for the IP address
+        """Get the Domain object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -143,7 +143,7 @@ def domain(self, ip_address):
                                     ip_address)
 
     def enterprise(self, ip_address):
-        """Get the Enterprise object for the IP address
+        """Get the Enterprise object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -154,7 +154,7 @@ def enterprise(self, ip_address):
                                ip_address)
 
     def isp(self, ip_address):
-        """Get the ISP object for the IP address
+        """Get the ISP object for the IP address.
 
         :param ip_address: IPv4 or IPv6 address as a string.
 
@@ -187,13 +187,13 @@ def _flat_model_for(self, model_class, types, ip_address):
         return model_class(record)
 
     def metadata(self):
-        """The metadata for the open database
+        """The metadata for the open database.
 
         :returns: :py:class:`maxminddb.reader.Metadata` object
         """
         return self._db_reader.metadata()
 
     def close(self):
-        """Closes the GeoIP2 database"""
+        """Closes the GeoIP2 database."""
 
         self._db_reader.close()

geoip2/errors.py

@@ -45,3 +45,7 @@ class InvalidRequestError(GeoIP2Error):
 
 class OutOfQueriesError(GeoIP2Error):
     """Your account is out of funds for the service queried."""
+
+
+class PermissionRequiredError(GeoIP2Error):
+    """Your account does not have permission to access this service."""

geoip2/models.py

@@ -18,7 +18,7 @@
 
 
 class Country(SimpleEquality):
-    """Model for the GeoIP2 Precision: Country and the GeoIP2 Country database
+    """Model for the GeoIP2 Precision: Country and the GeoIP2 Country database.
 
     This class provides the following attributes:
 
@@ -99,7 +99,8 @@ def __repr__(self):
 
 
 class City(Country):
-    """Model for the GeoIP2 Precision: City and the GeoIP2 City database
+    """Model for the GeoIP2 Precision: City and the GeoIP2 City database.
+
     .. attribute:: city
 
       City object for the requested IP address.
@@ -174,7 +175,7 @@ def __init__(self, raw_response, locales=None):
 
 
 class Insights(City):
-    """Model for the GeoIP2 Precision: Insights web service endpoint
+    """Model for the GeoIP2 Precision: Insights web service endpoint.
 
     .. attribute:: city
 
@@ -238,7 +239,7 @@ class Insights(City):
 
 
 class Enterprise(City):
-    """Model for the GeoIP2 Enterprise database
+    """Model for the GeoIP2 Enterprise database.
 
     .. attribute:: city
 
@@ -315,7 +316,7 @@ def __repr__(self):
 
 
 class AnonymousIP(SimpleModel):
-    """Model class for the GeoIP2 Anonymous IP
+    """Model class for the GeoIP2 Anonymous IP.
 
     This class provides the following attribute:
 
@@ -368,7 +369,7 @@ def __init__(self, raw):
 
 
 class ConnectionType(SimpleModel):
-    """Model class for the GeoIP2 Connection-Type
+    """Model class for the GeoIP2 Connection-Type.
 
     This class provides the following attribute:
 
@@ -399,7 +400,7 @@ def __init__(self, raw):
 
 
 class Domain(SimpleModel):
-    """Model class for the GeoIP2 Domain
+    """Model class for the GeoIP2 Domain.
 
     This class provides the following attribute:
 
@@ -424,7 +425,7 @@ def __init__(self, raw):
 
 
 class ISP(SimpleModel):
-    """Model class for the GeoIP2 ISP
+    """Model class for the GeoIP2 ISP.
 
     This class provides the following attribute: