How to Read MaxMind DB Files using Python

July 31, 2024

The MaxMind DB Python module provides a convenient way to read MaxMind DB files, which store data indexed by IP address subnets. In this article, we will explore how to install the module, open a MaxMind DB file, perform IP address lookups, and handle exceptions.

Installation

To start using the MaxMind DB Python module, you need to install it first. You can use pip to install the module by executing the following command:

bash
$ pip install maxminddb

If you are unable to use pip, you can also use easy_install from the source directory:

bash
$ easy_install .

The installation process will attempt to build the optional C extension. If the build fails, the module will fallback to the pure Python implementation.

Usage

Once you have successfully installed the MaxMind DB Python module, you can use it to read MaxMind DB files. Before using the module, you need to obtain a MaxMind DB file. MaxMind provides free GeoLite2 databases that you can download from their website.

To open a MaxMind DB file, you need to call the open_database function with the path or file descriptor of the database as the first argument. The second argument is an optional mode, which determines the method used for reading the database. The available modes are:

MODE_MMAP_EXT: Use the C extension with memory map
MODE_MMAP: Read from memory map using pure Python
MODE_FILE: Read the database as a standard file using pure Python
MODE_MEMORY: Load the database into memory using pure Python
MODE_FD: Load the database into memory from a file descriptor using pure Python
MODE_AUTO: Try MODE_MMAP_EXT, MODE_MMAP, and MODE_FILE in that order (default)

import maxminddb

# Open a MaxMind DB file
with maxminddb.open_database('GeoLite2-City.mmdb') as reader:
    # Perform IP address lookup
    result = reader.get('152.216.7.110')
    print(result)

    # Perform IP address lookup and retrieve the prefix length
    result_with_prefix_len = reader.get_with_prefix_len('152.216.7.110')
    print(result_with_prefix_len)

    # Iterate over the whole database
    for network, record in reader:
        # Process each network and record
        ...

The get method is used to perform IP address lookups. It takes an IP address as an argument and returns the corresponding values for that IP address from the database. If there is no record for the given IP address, the method returns None.

If you also need the prefix length for the returned record, you can use the get_with_prefix_len method. It returns a tuple containing the record followed by the network prefix length associated with the record.

The Reader class also implements the __iter__ method, allowing you to iterate over the whole database. Each iteration yields a tuple containing the network and the record.

Exceptions

In case of any issues with the MaxMind DB file, the module will raise an InvalidDatabaseError. The exception indicates that the database is corrupt or otherwise invalid. Additionally, if you look up an invalid IP address or an IPv6 address in an IPv4 database, a ValueError will be thrown.

Versioning and Support

The MaxMind DB Python module follows Semantic Versioning and requires Python 3.8+ and CPython. You can report any issues you encounter with the module using the GitHub issue tracker.

If you have any issues with a MaxMind service that are not specific to this API, please reach out to MaxMind support for assistance.

Conclusion

In this article, we have learned how to read MaxMind DB files using the MaxMind DB Python module. We have covered the installation process, opening a MaxMind DB file, performing IP address lookups, and handling exceptions. The MaxMind DB Python module is a powerful tool for working with IP address data and provides various modes for efficient database reading.

Category: Web Development

Tags: MaxMind, Python, IP address, Subnet, Binary File, Database, Reader

Group Sum