1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
========================
MaxMind DB Python Module
========================
Description
-----------
This is a Python module for reading MaxMind DB files. The module includes both
a pure Python reader and an optional C extension.
MaxMind DB is a binary file format that stores data indexed by IP address
subnets (IPv4 or IPv6).
Installation
------------
To install ``maxminddb``, type:
.. code-block:: bash
$ pip install maxminddb
If you are not able to install from PyPI, you may also use ``pip`` from the
source directory:
.. code-block:: bash
$ python -m pip install .
The installer will attempt to build the C extension. If this fails, the
module will fall-back to the pure Python implementation.
Usage
-----
To use this module, you must first download or create a MaxMind DB file. We
provide `free GeoLite2 databases
<https://dev.maxmind.com/geoip/geolocate-an-ip/databases?lang=en>`_. These
files must be decompressed with ``gunzip``.
After you have obtained a database and imported the module, call
``open_database`` with a path, or file descriptor (in the case of ``Mode.FD``),
to the database as the first argument. Optionally, you may pass a mode as the
second argument. The modes are available from ``maxminddb.Mode``. Valid modes 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.FD`` - load database into memory from a file descriptor. Pure Python.
* ``Mode.AUTO`` - try ``Mode.MMAP_EXT``, ``Mode.MMAP``, ``Mode.FILE`` in that
order. Default.
**NOTE**: When using ``Mode.FD``, it is the *caller's* responsibility to be
sure that the file descriptor gets closed properly. The caller may close the
file descriptor immediately after the ``Reader`` object is created.
The ``open_database`` function returns a ``Reader`` object. To look up an IP
address, use the ``get`` method on this object. The method will return the
corresponding values for the IP address from the database (e.g., a dictionary
for GeoIP2/GeoLite2 databases). If the database does not contain a record for
that IP address, the method will return ``None``.
If you wish to also retrieve the prefix length for the record, use the
``get_with_prefix_len`` method. This returns a tuple containing the record
followed by the network prefix length associated with the record.
You may also iterate over the whole database. The ``Reader`` class implements
the ``__iter__`` method that returns an iterator. This iterator yields a
tuple containing the network and the record.
Example
-------
.. code-block:: pycon
>>> import maxminddb
>>>
>>> with maxminddb.open_database('GeoLite2-City.mmdb') as reader:
>>>
>>> reader.get('152.216.7.110')
{'country': ... }
>>>
>>> reader.get_with_prefix_len('152.216.7.110')
({'country': ... }, 24)
>>>
>>> for network, record in reader:
>>> ...
Exceptions
----------
The module will return an ``InvalidDatabaseError`` if the database is corrupt
or otherwise invalid. A ``ValueError`` will be thrown if you look up an
invalid IP address or an IPv6 address in an IPv4 database.
Thread Safety
-------------
Both the C extension and pure Python implementations are safe for concurrent
reads and support Python 3.13+ free-threading. The C extension provides
free-threading support on platforms with pthread support (such as Linux and
macOS) and Windows. On other platforms, the extension will use GIL-based
protection. Calling ``close()`` while reads are in progress may cause
exceptions in those threads.
Requirements
------------
This code requires Python 3.10+. Older versions are not supported. The C
extension requires CPython.
Versioning
----------
The MaxMind DB Python module uses `Semantic Versioning <https://semver.org/>`_.
Support
-------
Please report all issues with this code using the `GitHub issue tracker
<https://github.com/maxmind/MaxMind-DB-Reader-python/issues>`_
If you are having an issue with a MaxMind service that is not specific to this
API, please contact `MaxMind support <https://www.maxmind.com/en/support>`_ for
assistance.
|
