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.
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
.
Example¶
>>> import maxminddb
>>>
>>> reader = maxminddb.open_database('GeoLite2-City.mmdb')
>>> reader.get('1.1.1.1')
{'country': ... }
>>>
>>> reader.close()
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 2.7+ or 3.3+. The C extension requires CPython. The pure Python implementation has been tested with PyPy.
On Python 2, the ipaddress module is required.
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¶
-
maxminddb.
Reader
(database)¶ This exists for backwards compatibility. Use open_database instead
-
maxminddb.
open_database
(database, mode=0)¶ 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:
exceptions.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, mode=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
()¶ Closes the MaxMind DB file and returns the resources to the system
-
get
(ip_address)¶ Return the record for the ip_address in the MaxMind DB
Arguments: ip_address – an IP address in the standard string notation
-
metadata
()¶ Return the metadata associated with the MaxMind DB file
-
Indices and tables¶
copyright: |
|
---|---|
license: | Apache License, Version 2.0 |