Merge pull request #11 from maxmind/greg/new-dbs

Greg/new dbs

Author: borisz

README.rst

@@ -97,9 +97,32 @@ Web Service Example
     >>> response.location.longitude
     -93.2323
 
+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.
+
+If the web service returns an explicit error document, this is thrown as a
+``AddressNotFoundError``, ``AuthenticationError``, ``InvalidRequestError``, or
+``OutOfQueriesError`` as appropriate. These all subclass ``GeoIP2Error``.
+
+If some other sort of error occurs, this is thrown as an ``HTTPError``. This
+is thrown when some sort of unanticipated error occurs, such as the web
+service returning a 500 or an invalid error document. If the web service
+returns any status code besides 200, 4xx, or 5xx, this also becomes an
+``HTTPError``.
+
+Finally, if the web service returns a 200 but the body is invalid, the client
+throws a ``GeoIP2Error``.
+
 Database Example
 -------------------
 
+City Database
+^^^^^^^^^^^^^
+
 .. code-block:: pycon
 
     >>> import geoip2.database
@@ -134,26 +157,65 @@ Database Example
     44.9733
     >>> response.location.longitude
     -93.2323
+    >>> reader.close()
 
-Web Service Client Exceptions
------------------------------
+Connection-Type Database
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-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.
+    >>> import geoip2.database
+    >>>
+    >>> # This creates a Reader object. You should use the same object
+    >>> # across multiple requests as creation of it is expensive.
+    >>> reader = geoip2.database.Reader('/path/to/GeoIP2-Connection-Type.mmdb')
+    >>>
+    >>> response = reader.connection_type('128.101.101.101')
+    >>>
+    >>> response.connection_type
+    'Corporate'
+    >>> response.ip_address
+    '128.101.101.101'
+    >>> reader.close()
 
-If the web service returns an explicit error document, this is thrown as a
-``AddressNotFoundError``, ``AuthenticationError``, ``InvalidRequestError``, or
-``OutOfQueriesError`` as appropriate. These all subclass ``GeoIP2Error``.
 
-If some other sort of error occurs, this is thrown as an ``HTTPError``. This
-is thrown when some sort of unanticipated error occurs, such as the web
-service returning a 500 or an invalid error document. If the web service
-returns any status code besides 200, 4xx, or 5xx, this also becomes an
-``HTTPError``.
+Domain Database
+^^^^^^^^^^^^^^^
 
-Finally, if the web service returns a 200 but the body is invalid, the client
-throws a ``GeoIP2Error``.
+    >>> import geoip2.database
+    >>>
+    >>> # This creates a Reader object. You should use the same object
+    >>> # across multiple requests as creation of it is expensive.
+    >>> reader = geoip2.database.Reader('/path/to/GeoIP2-Domain.mmdb')
+    >>>
+    >>> response = reader.domain('128.101.101.101')
+    >>>
+    >>> response.domain
+    'umn.edu'
+    >>> response.ip_address
+    '128.101.101.101'
+    >>> reader.close()
+
+ISP Database
+^^^^^^^^^^^^
+
+    >>> import geoip2.database
+    >>>
+    >>> # This creates a Reader object. You should use the same object
+    >>> # across multiple requests as creation of it is expensive.
+    >>> reader = geoip2.database.Reader('/path/to/GeoIP2-ISP.mmdb')
+    >>>
+    >>> response = reader.isp('1.128.0.0')
+    >>>
+    >>> response.autonomous_system_number
+    1221
+    >>> response.autonomous_system_organization
+    'Telstra Pty Ltd'
+    >>> response.isp
+    'Telstra Internet'
+    >>> response.organization
+    'Telstra Internet'
+    >>> response.ip_address
+    '128.101.101.101'
+    >>> reader.close()
 
 Database Reader Exceptions
 --------------------------

geoip2/database.py

@@ -17,9 +17,7 @@ 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, although we may offer the
-    ability to specify additional databases to replicate these web services in
-    the future (e.g., the ISP/Org database).
+    compatibility with the web service client.
 
      Usage
      -----
@@ -49,11 +47,9 @@ def __init__(self, filename, locales=None):
         self._locales = locales
 
     def country(self, ip_address):
-        """Get the Country record object for the IP address
+        """Get the Country object for the IP address
 
-        :param ip_address: IPv4 or IPv6 address as a string. If no address
-          is provided, the address that the web service is called from will
-          be used.
+        :param ip_address: IPv4 or IPv6 address as a string.
 
         :returns: :py:class:`geoip2.models.Country` object
 
@@ -62,23 +58,20 @@ def country(self, ip_address):
         return self._model_for(geoip2.models.Country, ip_address)
 
     def city(self, ip_address):
-        """Get the City record 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, the address that the web service is called from will
-          be used.
+        :param ip_address: IPv4 or IPv6 address as a string.
 
         :returns: :py:class:`geoip2.models.City` object
 
         """
         return self._model_for(geoip2.models.City, ip_address)
 
     def city_isp_org(self, ip_address):
-        """Get the CityISPOrg record object for the IP address
+        """Get the CityISPOrg object for the IP address
 
         :param ip_address: IPv4 or IPv6 address as a string. If no address
-          is provided, the address that the web service is called from will
-          be used.
+          is provided.
 
         :returns: :py:class:`geoip2.models.CityISPOrg` object
 
@@ -87,25 +80,62 @@ def city_isp_org(self, ip_address):
         return self._model_for(geoip2.models.CityISPOrg, ip_address)
 
     def omni(self, ip_address):
-        """Get the Omni record object for the IP address
+        """Get the Omni object for the IP address
 
-        :param ip_address: IPv4 or IPv6 address as a string. If no address
-          is provided, the address that the web service is called from will
-          be used.
+        :param ip_address: IPv4 or IPv6 address as a string.
 
         :returns: :py:class:`geoip2.models.Omni` object
 
         """
         return self._model_for(geoip2.models.Omni, ip_address)
 
-    def _model_for(self, model_class, ip_address):
+    def connection_type(self, ip_address):
+        """Get the ConnectionType object for the IP address
+
+        :param ip_address: IPv4 or IPv6 address as a string.
+
+        :returns: :py:class:`geoip2.models.ConnectionType` object
+
+        """
+        return self._flat_model_for(geoip2.models.ConnectionType, ip_address)
+
+    def domain(self, ip_address):
+        """Get the Domain object for the IP address
+
+        :param ip_address: IPv4 or IPv6 address as a string.
+
+        :returns: :py:class:`geoip2.models.Domain` object
+
+        """
+        return self._flat_model_for(geoip2.models.Domain, ip_address)
+
+    def isp(self, ip_address):
+        """Get the ISP object for the IP address
+
+        :param ip_address: IPv4 or IPv6 address as a string.
+
+        :returns: :py:class:`geoip2.models.ISP` object
+
+        """
+        return self._flat_model_for(geoip2.models.ISP, ip_address)
+
+    def _get(self, ip_address):
         record = self._db_reader.get(ip_address)
         if record is None:
             raise geoip2.errors.AddressNotFoundError(
                 "The address %s is not in the database." % ip_address)
+        return record
+
+    def _model_for(self, model_class, ip_address):
+        record = self._get(ip_address)
         record.setdefault('traits', {})['ip_address'] = ip_address
         return model_class(record, locales=self._locales)
 
+    def _flat_model_for(self, model_class, ip_address):
+        record = self._get(ip_address)
+        record['ip_address'] = ip_address
+        return model_class(record)
+
     def close(self):
         """Closes the GeoIP2 database"""
 

geoip2/models.py

@@ -16,10 +16,9 @@
 
 class Country(object):
 
-    """Model class for the GeoIP2 Country end point
+    """Model class for the GeoIP2 Country
 
-    This class provides the following methods, each of which returns a record
-    object.
+    This class provides the following attributes:
 
     .. attribute:: continent
 
@@ -93,7 +92,7 @@ def __init__(self, raw_response, locales=None):
 
 class City(Country):
 
-    """Model class for the GeoIP2 Precision City end point
+    """Model class for the GeoIP2 Precision City
 
     .. attribute:: city
 
@@ -171,7 +170,7 @@ def __init__(self, raw_response, locales=None):
 
 class CityISPOrg(City):
 
-    """Model class for the GeoIP2 Precision City/ISP/Org end point
+    """Model class for the GeoIP2 Precision City/ISP/Org
 
     .. attribute:: city
 
@@ -237,7 +236,7 @@ class CityISPOrg(City):
 
 class Omni(CityISPOrg):
 
-    """Model class for the GeoIP2 Precision Omni end point
+    """Model class for the GeoIP2 Precision Omni
 
     .. attribute:: city
 
@@ -299,3 +298,110 @@ class Omni(CityISPOrg):
       :type: :py:class:`geoip2.records.Traits`
 
     """
+
+
+class ConnectionType(object):
+
+    """Model class for the GeoIP2 Connection-Type
+
+    This class provides the following attribute:
+
+    .. attribute:: connection_type
+
+      The connection type may take the following values:
+
+      - Dialup
+      - Cable/DSL
+      - Corporate
+      - Cellular
+
+      Additional values may be added in the future.
+
+      :type: unicode
+
+    .. attribute:: ip_address
+
+      The IP address used in the lookup.
+
+      :type: unicode
+    """
+
+    def __init__(self, raw):
+        self.connection_type = raw.get('connection_type')
+        self.ip_address = raw.get('ip_address')
+        self.raw = raw
+
+
+class Domain(object):
+
+    """Model class for the GeoIP2 Domain
+
+    This class provides the following attribute:
+
+    .. attribute:: domain
+
+      The domain associated with the IP address.
+
+      :type: unicode
+
+    .. attribute:: ip_address
+
+      The IP address used in the lookup.
+
+      :type: unicode
+
+    """
+
+    def __init__(self, raw):
+        self.domain = raw.get('domain')
+        self.ip_address = raw.get('ip_address')
+        self.raw = raw
+
+
+class ISP(object):
+
+    """Model class for the GeoIP2 ISP
+
+    This class provides the following attribute:
+
+    .. attribute:: autonomous_system_number
+
+      The autonomous system number associated with the IP address.
+
+      :type: int
+
+    .. attribute:: autonomous_system_organization
+
+      The organization associated with the registered autonomous system number
+      for the IP address.
+
+      :type: unicode
+
+    .. attribute:: isp
+
+      The name of the ISP associated with the IP address.
+
+      :type: unicode
+
+    .. attribute:: organization
+
+      The name of the organization associated with the IP address.
+
+      :type: unicode
+
+    .. attribute:: ip_address
+
+      The IP address used in the lookup.
+
+      :type: unicode
+    """
+
+    # pylint:disable=too-many-arguments
+    def __init__(self, raw):
+        self.autonomous_system_number = raw.get('autonomous_system_number')
+        self.autonomous_system_organization = raw.get(
+            'autonomous_system_organization')
+        self.isp = raw.get('isp')
+        self.organization = raw.get('organization')
+        self.ip_address = raw.get('ip_address')
+        self.raw = raw