Merge pull request #32 from maxmind/greg/enterprise

Add support for GeoIP2 Enterprise

Author: 2shortplanks

HISTORY.rst

@@ -6,6 +6,7 @@ History
 2.3.0 (201X-XX-XX)
 ++++++++++++++++++
 
+* Added support for the GeoIP2 Enterprise database.
 * ``geoip2.database.Reader`` now supports being used in a ``with`` statement
   (PEP 343). (PR from Nguyễn Hồng Quân. GitHub #29)
 
@@ -21,7 +22,6 @@ History
   <https://www.maxmind.com/en/geoip2-anonymous-ip-database>`_
   to determine whether an IP address is used by an anonymizing service.
 
-
 2.1.0 (2014-12-09)
 ++++++++++++++++++
 
@@ -80,7 +80,6 @@ History
   from this API.
 * Support was added for the GeoIP2 Connection Type, Domain, and ISP databases.
 
-
 0.5.1 (2014-03-28)
 ++++++++++++++++++
 

README.rst

@@ -217,6 +217,51 @@ Domain Database
     '128.101.101.101'
     >>> reader.close()
 
+Enterprise Database
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: pycon
+
+    >>> import geoip2.database
+    >>>
+    >>> # This creates a Reader object. You should use the same object
+    >>> # across multiple requests as creation of it is expensive.
+    >>> with geoip2.database.Reader('/path/to/GeoIP2-Enterprise.mmdb') as reader:
+    >>>
+    >>>     # Use the .enterprise method to do a lookup in the Enterprise database
+    >>>     response = reader.enterprise('128.101.101.101')
+    >>>
+    >>>     response.country.confidence
+    99
+    >>>     response.country.iso_code
+    'US'
+    >>>     response.country.name
+    'United States'
+    >>>     response.country.names['zh-CN']
+    u'美国'
+    >>>
+    >>>     response.subdivisions.most_specific.name
+    'Minnesota'
+    >>>     response.subdivisions.most_specific.iso_code
+    'MN'
+    >>>     response.subdivisions.most_specific.confidence
+    77
+    >>>
+    >>>     response.city.name
+    'Minneapolis'
+    >>>     response.country.confidence
+    11
+    >>>
+    >>>     response.postal.code
+    '55455'
+    >>>
+    >>>     response.location.accuracy_radius
+    50
+    >>>     response.location.latitude
+    44.9733
+    >>>     response.location.longitude
+    -93.2323
+
 ISP Database
 ^^^^^^^^^^^^
 

docs/conf.py

@@ -12,22 +12,24 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
 import geoip2
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration -----------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
+              'sphinx.ext.intersphinx', 'sphinx.ext.coverage']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -43,7 +45,7 @@
 
 # General information about the project.
 project = 'geoip2'
-copyright = '2014, MaxMind, Inc.'
+copyright = '2013-2016, 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
@@ -89,7 +91,7 @@
 #modindex_common_prefix = []
 
 
-# -- Options for HTML output ---------------------------------------------------
+# -- Options for HTML output ---------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -169,24 +171,24 @@
 htmlhelp_basename = 'geoip2doc'
 
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output --------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    #'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    #'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    #'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'geoip2.tex', 'geoip2 Documentation',
-   'Gregory Oschwald', 'manual'),
+    ('index', 'geoip2.tex', 'geoip2 Documentation',
+     'Gregory Oschwald', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -210,7 +212,7 @@
 #latex_domain_indices = True
 
 
-# -- Options for manual page output --------------------------------------------
+# -- Options for manual page output --------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
@@ -223,15 +225,15 @@
 #man_show_urls = False
 
 
-# -- Options for Texinfo output ------------------------------------------------
+# -- Options for Texinfo output ------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'geoip2', 'geoip2 Documentation',
-   'Gregory Oschwald', 'geoip2', 'One line description of project.',
-   'Miscellaneous'),
+    ('index', 'geoip2', 'geoip2 Documentation',
+     'Gregory Oschwald', 'geoip2', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.

docs/index.rst

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

geoip2/__init__.py

@@ -4,4 +4,4 @@
 __version__ = '2.2.0'
 __author__ = 'Gregory Oschwald'
 __license__ = 'Apache License, Version 2.0'
-__copyright__ = 'Copyright 2014 Maxmind, Inc.'
+__copyright__ = 'Copyright (c) 2013-2016 Maxmind, Inc.'

geoip2/database.py

@@ -142,6 +142,17 @@ def domain(self, ip_address):
         return self._flat_model_for(geoip2.models.Domain, 'GeoIP2-Domain',
                                     ip_address)
 
+    def enterprise(self, ip_address):
+        """Get the Enterprise object for the IP address
+
+        :param ip_address: IPv4 or IPv6 address as a string.
+
+        :returns: :py:class:`geoip2.models.Enterprise` object
+
+        """
+        return self._model_for(geoip2.models.Enterprise, 'Enterprise',
+                               ip_address)
+
     def isp(self, ip_address):
         """Get the ISP object for the IP address
 

geoip2/models.py

@@ -237,6 +237,70 @@ class Insights(City):
     """
 
 
+class Enterprise(City):
+    """Model for the GeoIP2 Enterprise database
+
+    .. 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.
+
+      :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 SimpleModel(SimpleEquality):
     """Provides basic methods for non-location models"""