======================== 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 GeoLite databases
_. These
files must be decompressed with gunzip.
After you have obtained a database and imported the module, call
open_database with a path, or binary file object (with Mode.FD or Mode.AUTO),
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 binary file object. Pure Python.Mode.AUTO- tryMode.MMAP_EXT,Mode.MMAP,Mode.FILEin that
Mode.FD. Pass a path to use the faster C extension. Default.
NOTE: When using a file object, it is the caller's responsibility to be
sure that the file object gets closed properly. The caller may close the
file object immediately after the
Reader object is created. The pure
Python reader closes a file descriptor that you pass to it. This includes
Mode.AUTO when the C extension is not installed.
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 GeoIP/GeoLite 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.
The reader also raises
InvalidDatabaseError when one record, or the
database metadata, exceeds its resource limits: 65,536 decoded values, 512
levels of nesting, or 2 MiB of string and bytes data. Real databases stay far
below these limits. Python's recursion limit may stop decoding sooner.
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.
Versioning
----------
The MaxMind DB Python module uses
Semantic Versioning _.
Support
-------
Please report all issues with this code using the
GitHub issue tracker
_
If you are having an issue with a MaxMind service that is not specific to this
API, please contact
MaxMind support