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

If you want to use the C extension, you must first install libmaxminddb C library installed before installing this extension. If the library is not available, the module will fall-back to a pure Python implementation. Note that when installing the C library from a package, you may be required to install additonal packages containing build requirements such as libmaxminddb-dev on Debian.

To install maxminddb, type:

$ pip install maxminddb

If you are not able to use pip, you may also use easy_install from the source directory:

$ easy_install .

Usage

To use this module, you must first download or create a MaxMind DB file. We provide free GeoLite2 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 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 exported from maxminddb. 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.

Example

>>> 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)

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.

Requirements

This code requires Python 3.6+. Older versions are not supported. The C extension requires CPython.

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 for assistance.

Modules

exception maxminddb.InvalidDatabaseError

Bases: RuntimeError

This error is thrown when unexpected data is found in the database.

class maxminddb.Reader(database: Union[AnyStr, int, os.PathLike, IO], mode: int = 0)

Bases: object

Instances of this class provide a reader for the MaxMind DB format. IP addresses can be looked up using the get method.

close() → None

Closes the MaxMind DB file and returns the resources to the system

get(ip_address: Union[str, ipaddress.IPv6Address, ipaddress.IPv4Address]) → Union[AnyStr, bool, float, int, RecordList, RecordDict, None]

Return the record for the ip_address in the MaxMind DB

Arguments: ip_address – an IP address in the standard string notation

get_with_prefix_len(ip_address: Union[str, ipaddress.IPv6Address, ipaddress.IPv4Address]) → Tuple[Union[AnyStr, bool, float, int, RecordList, RecordDict, None], int]

Return a tuple with the record and the associated prefix length

Arguments: ip_address – an IP address in the standard string notation

metadata() → maxminddb.reader.Metadata

Return the metadata associated with the MaxMind DB file

maxminddb.open_database(database: Union[AnyStr, int, os.PathLike, IO], mode: int = 0) → maxminddb.reader.Reader

Open a MaxMind DB database

Arguments:
database – A path to a valid MaxMind DB file such as a GeoIP2 database
file, or a file descriptor in the case of MODE_FD.
mode – 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_FD - the param passed via database is a file descriptor, not
    a path. This mode implies MODE_MEMORY.
  • MODE_AUTO - tries MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that
    order. Default mode.

maxminddb.errors

This module contains custom errors for the MaxMind DB reader

exception maxminddb.errors.InvalidDatabaseError

Bases: RuntimeError

This error is thrown when unexpected data is found in the database.

maxminddb.reader

This module contains the pure Python database reader and related classes.

class maxminddb.reader.Metadata(**kwargs)

Bases: object

Metadata for the MaxMind DB reader

binary_format_major_version

The major version number of the binary format used when creating the database.

Type:int
binary_format_minor_version

The minor version number of the binary format used when creating the database.

Type:int
build_epoch

The Unix epoch for the build time of the database.

Type:int
database_type

A string identifying the database type, e.g., “GeoIP2-City”.

Type:str
description

A map from locales to text descriptions of the database.

Type:dict(str, str)
ip_version

The IP version of the data in a database. A value of “4” means the database only supports IPv4. A database with a value of “6” may support both IPv4 and IPv6 lookups.

Type:int
languages

A list of locale codes supported by the databse.

Type:list(str)
node_count

The number of nodes in the database.

Type:int
record_size

The bit size of a record in the search tree.

Type:int
node_byte_size

The size of a node in bytes

Type:int
search_tree_size

The size of the search tree

Type:int
class maxminddb.reader.Reader(database: Union[AnyStr, int, os.PathLike, IO], mode: int = 0)

Bases: object

Instances of this class provide a reader for the MaxMind DB format. IP addresses can be looked up using the get method.

close() → None

Closes the MaxMind DB file and returns the resources to the system

get(ip_address: Union[str, ipaddress.IPv6Address, ipaddress.IPv4Address]) → Union[AnyStr, bool, float, int, RecordList, RecordDict, None]

Return the record for the ip_address in the MaxMind DB

Arguments: ip_address – an IP address in the standard string notation

get_with_prefix_len(ip_address: Union[str, ipaddress.IPv6Address, ipaddress.IPv4Address]) → Tuple[Union[AnyStr, bool, float, int, RecordList, RecordDict, None], int]

Return a tuple with the record and the associated prefix length

Arguments: ip_address – an IP address in the standard string notation

metadata() → maxminddb.reader.Metadata

Return the metadata associated with the MaxMind DB file

Indices and tables

copyright:
  1. 2013-2021 by MaxMind, Inc.
license:

Apache License, Version 2.0