Merge pull request maxmind#19 from maxmind/greg/db-modes

Add support for DB open modes

Author: autarch

.travis.yml

@@ -27,7 +27,7 @@ install:
 
 script:
   - coverage run --source=geoip2 setup.py test
-  - if [[ $TRAVIS_PYTHON_VERSION != '3.3' ]]; then pylint geoip2; fi
+  - if [[ $TRAVIS_PYTHON_VERSION == '2.7' ]]; then pylint geoip2; fi
 
 after_success:
   - coveralls

HISTORY.rst

@@ -3,6 +3,16 @@
 History
 -------
 
+2.1.0 (2014-12-XX)
+++++++++++++++++++
+
+* The reader now supports pure Python file and memory modes. If you are not
+  using the C extension and your Python does not provide the ``mmap`` module,
+  the file mode will be used by default. You can explicitly set the mode using
+  the ``mode`` keyword argument with the ``MODE_AUTO``, ``MODE_MMAP``,
+  ``MODE_MMAP_EXT``, ``MODE_FILE``, and ``MODE_MEMORY`` constants exported  by
+  ``geoip2.database``.
+
 2.0.2 (2014-10-28)
 ++++++++++++++++++
 

geoip2/database.py

@@ -11,10 +11,14 @@
 import geoip2.errors
 import maxminddb
 
+# pylint: disable=unused-import
+from maxminddb import (MODE_AUTO, MODE_MMAP, MODE_MMAP_EXT, MODE_FILE,
+                       MODE_MEMORY)
+
 
 class Reader(object):
 
-    """Creates a new GeoIP2 database Reader object.
+    """GeoIP2 database 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.
@@ -40,10 +44,46 @@ class Reader(object):
 
 """
 
-    def __init__(self, filename, locales=None):
+    def __init__(self, filename, locales=None, mode=MODE_AUTO):
+        """Create GeoIP2 Reader
+
+        :param filename: The path to the GeoIP2 database.
+        :param locales: This is list of locale codes. This argument will be
+          passed on to record classes to use when their name properties are
+          called. The default value is ['en'].
+
+          The order of the locales is significant. When a record class has
+          multiple names (country, city, etc.), its name property will return
+          the name in the first locale that has one.
+
+          Note that the only locale which is always present in the GeoIP2
+          data is "en". If you do not include this locale, the name property
+          may end up returning None even when the record has an English name.
+
+          Currently, the valid locale codes are:
+
+          * de -- German
+          * en -- English names may still include accented characters if that
+            is the accepted spelling in English. In other words, English does
+            not mean ASCII.
+          * es -- Spanish
+          * fr -- French
+          * ja -- Japanese
+          * pt-BR -- Brazilian Portuguese
+          * ru -- Russian
+          * zh-CN -- Simplified Chinese.
+        :param mode: The mode to open the database with. Valid mode are:
+          * MODE_MMAP_EXT - use the C extension with memory map.
+          * MODE_MMAP - read from memory map. Pure Python.
+          * MODE_FILE - read database as standard file. Pure Python.
+          * MODE_MEMORY - load database into memory. Pure Python.
+          * MODE_AUTO - try MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that order.
+             Default.
+
+        """
         if locales is None:
             locales = ['en']
-        self._db_reader = maxminddb.Reader(filename)
+        self._db_reader = maxminddb.open_database(filename, mode)
         self._locales = locales
 
     def country(self, ip_address):

tests/database_test.py

@@ -7,6 +7,12 @@
 sys.path.append('..')
 
 import geoip2.database
+import maxminddb
+
+try:
+    import maxminddb.extension
+except ImportError:
+    maxminddb.extension = None
 
 if sys.version_info[:2] == (2, 6):
     import unittest2 as unittest
@@ -18,7 +24,7 @@
     unittest.TestCase.assertRegex = unittest.TestCase.assertRegexpMatches
 
 
-class TestReader(unittest.TestCase):
+class BaseTestReader(object):
 
     def test_default_locale(self):
         reader = geoip2.database.Reader(
@@ -142,3 +148,24 @@ def test_isp(self):
                          "ISP repr can be eval'd")
 
         reader.close()
+
+
+@unittest.skipUnless(maxminddb.extension, 'No C extension module found. Skipping tests')
+class TestExtensionReader(BaseTestReader, unittest.TestCase):
+    mode = geoip2.database.MODE_MMAP_EXT
+
+
+class TestMMAPReader(BaseTestReader, unittest.TestCase):
+    mode = geoip2.database.MODE_MMAP
+
+
+class TestFileReader(BaseTestReader, unittest.TestCase):
+    mode = geoip2.database.MODE_FILE
+
+
+class TestMemoryReader(BaseTestReader, unittest.TestCase):
+    mode = geoip2.database.MODE_MEMORY
+
+
+class TestMemoryReader(BaseTestReader, unittest.TestCase):
+    mode = geoip2.database.MODE_AUTO