https://github.com/maxmind/maxmind-db-reader-python

Python MaxMind DB reader extension
https://github.com/maxmind/maxmind-db-reader-python

geoip geoip2 maxmind mmdb

Last synced: 3 days ago
JSON representation

Python MaxMind DB reader extension

• Host: GitHub
• URL: https://github.com/maxmind/maxmind-db-reader-python
• Owner: maxmind
• License: apache-2.0
• Created: 2013-09-25T22:26:14.000Z (about 11 years ago)
• Default Branch: main
• Last Pushed: 2024-12-02T17:22:18.000Z (20 days ago)
• Last Synced: 2024-12-12T20:05:27.005Z (10 days ago)
• Topics: geoip, geoip2, maxmind, mmdb
• Language: Python
• Homepage: https://maxminddb.readthedocs.org/
• Size: 528 KB
• Stars: 180
• Watchers: 24
• Forks: 37
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • Changelog: HISTORY.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
========================

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 use pip, you may also use easy_install from the

source directory:

.. code-block:: bash

    $ easy_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

`_. 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.

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.

Requirements

------------

This code requires Python 3.8+. 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.