README.rst
1========================
2MaxMind DB Python Module
3========================
4
5Description
6-----------
7
8This is a Python module for reading MaxMind DB files. The module includes both
9a pure Python reader and an optional C extension.
10
11MaxMind DB is a binary file format that stores data indexed by IP address
12subnets (IPv4 or IPv6).
13
14Installation
15------------
16
17If you want to use the C extension, you must first install `libmaxminddb
18<https://github.com/maxmind/libmaxminddb>`_ C library installed before
19installing this extension. If the library is not available, the module will
20fall-back to a pure Python implementation.
21
22To install maxminddb, type:
23
24.. code-block:: bash
25
26 $ pip install maxminddb
27
28If you are not able to use pip, you may also use easy_install from the
29source directory:
30
31.. code-block:: bash
32
33 $ easy_install .
34
35Usage
36-----
37
38To use this module, you must first download or create a MaxMind DB file. We
39provide `free GeoLite2 databases
40<https://dev.maxmind.com/geoip/geoip2/geolite2>`_. These files must be
41decompressed with ``gunzip``.
42
43After you have obtained a database and imported the module, call
44``open_database`` with a path, or file descriptor (in the case of ``MODE_FD``),
45to the database as the first argument. Optionally, you may pass a mode as the
46second argument. The modes are exported from ``maxminddb``. Valid modes are:
47
48* ``MODE_MMAP_EXT`` - use the C extension with memory map.
49* ``MODE_MMAP`` - read from memory map. Pure Python.
50* ``MODE_FILE`` - read database as standard file. Pure Python.
51* ``MODE_MEMORY`` - load database into memory. Pure Python.
52* ``MODE_FD`` - load database into memory from a file descriptor. Pure Python.
53* ``MODE_AUTO`` - try ``MODE_MMAP_EXT``, ``MODE_MMAP``, ``MODE_FILE`` in that
54 order. Default.
55
56**NOTE**: When using ``MODE_FD``, it is the *caller's* responsibility to be
57sure that the file descriptor gets closed properly. The caller may close the
58file descriptor immediately after the ``Reader`` object is created.
59
60The ``open_database`` function returns a ``Reader`` object. To look up an IP
61address, use the ``get`` method on this object. The method will return the
62corresponding values for the IP address from the database (e.g., a dictionary
63for GeoIP2/GeoLite2 databases). If the database does not contain a record for
64that IP address, the method will return ``None``.
65
66If you wish to also retrieve the prefix length for the record, use the
67``get_with_prefix_len`` method. This returns a tuple containing the record
68followed by the network prefix length associated with the record.
69
70Example
71-------
72
73.. code-block:: pycon
74
75 >>> import maxminddb
76 >>>
77 >>> with maxminddb.open_database('GeoLite2-City.mmdb') as reader:
78 >>>
79 >>> reader.get('152.216.7.110')
80 {'country': ... }
81 >>>
82 >>> reader.get_with_prefix_len('152.216.7.110')
83 ({'country': ... }, 24)
84
85Exceptions
86----------
87
88The module will return an ``InvalidDatabaseError`` if the database is corrupt
89or otherwise invalid. A ``ValueError`` will be thrown if you look up an
90invalid IP address or an IPv6 address in an IPv4 database.
91
92Requirements
93------------
94
95This code requires Python 3.6+. Older versions are not supported. The C
96extension requires CPython.
97
98Versioning
99----------
100
101The MaxMind DB Python module uses `Semantic Versioning <https://semver.org/>`_.
102
103Support
104-------
105
106Please report all issues with this code using the `GitHub issue tracker
107<https://github.com/maxmind/MaxMind-DB-Reader-python/issues>`_
108
109If you are having an issue with a MaxMind service that is not specific to this
110API, please contact `MaxMind support <https://www.maxmind.com/en/support>`_ for
111assistance.
112