maxminddb


Namemaxminddb JSON
Version 1.3.0 PyPI version JSON
download
home_pagehttp://www.maxmind.com/
SummaryReader for the MaxMind DB format
upload_time2017-03-13 15:58:18
maintainer
docs_urlNone
authorGregory Oschwald
requires_python
licenseApache License, Version 2.0
keywords
VCS
bugtrack_url https://github.com/maxmind/MaxMind-DB-Reader-python/issues
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ========================
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
<https://github.com/maxmind/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:

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

Usage
-----

To use this module, you must first download or create a MaxMind DB file. We
provide `free GeoLite2 databases
<http://dev.maxmind.com/geoip/geoip2/geolite2>`_. These files must be
decompressed with ``gunzip``.

After you have obtained a database and importing the module, call
``open_database`` with a path to the database as the first argument.
Optionally, you may pass a mode as the second arguments. 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_AUTO - try MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that order. Default.

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

.. code-block:: pycon

    >>> 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.6+ or 3.3+. The C extension requires CPython. The
pure Python implementation has been tested with PyPy.

On Python 2, the `ipaddress module <https://pypi.python.org/pypi/ipaddress>`_ is
required.

Versioning
----------

The MaxMind DB Python module uses `Semantic Versioning <http://semver.org/>`_.

Support
-------

Please report all issues with this code using the `GitHub issue tracker
<https://github.com/maxmind/MaxMind-DB-Reader-python/issues>`_

If you are having an issue with a MaxMind service that is not specific to this
API, please contact `MaxMind support <http://www.maxmind.com/en/support>`_ for
assistance.

            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "", 
    "upload_time": "2017-03-13 15:58:18", 
    "author": "Gregory Oschwald", 
    "home_page": "http://www.maxmind.com/", 
    "download_url": "https://pypi.python.org/packages/f8/7a/bac498d2b7491dd8b837dff8831a7e7628db72c4b840b54743961a8f0454/maxminddb-1.3.0.tar.gz", 
    "platform": "", 
    "version": "1.3.0", 
    "cheesecake_documentation_id": null, 
    "description": "========================\nMaxMind DB Python Module\n========================\n\nDescription\n-----------\n\nThis is a Python module for reading MaxMind DB files. The module includes both\na pure Python reader and an optional C extension.\n\nMaxMind DB is a binary file format that stores data indexed by IP address\nsubnets (IPv4 or IPv6).\n\nInstallation\n------------\n\nIf you want to use the C extension, you must first install `libmaxminddb\n<https://github.com/maxmind/libmaxminddb>`_ C library installed before\ninstalling this extension. If the library is not available, the module will\nfall-back to a pure Python implementation.\n\nTo install maxminddb, type:\n\n.. code-block:: bash\n\n    $ pip install maxminddb\n\nIf you are not able to use pip, you may also use easy_install from the\nsource directory:\n\n.. code-block:: bash\n\n    $ easy_install .\n\nUsage\n-----\n\nTo use this module, you must first download or create a MaxMind DB file. We\nprovide `free GeoLite2 databases\n<http://dev.maxmind.com/geoip/geoip2/geolite2>`_. These files must be\ndecompressed with ``gunzip``.\n\nAfter you have obtained a database and importing the module, call\n``open_database`` with a path to the database as the first argument.\nOptionally, you may pass a mode as the second arguments. The modes are\nexported from ``maxminddb``. Valid modes are:\n\n* MODE_MMAP_EXT - use the C extension with memory map.\n* MODE_MMAP - read from memory map. Pure Python.\n* MODE_FILE - read database as standard file. Pure Python.\n* MODE_MEMORY - load database into memory. Pure Python.\n* MODE_AUTO - try MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that order. Default.\n\nThe ``open_database`` function returns a ``Reader`` object. To look up an IP\naddress, use the ``get`` method on this object. The method will return the\ncorresponding values for the IP address from the database (e.g., a dictionary\nfor GeoIP2/GeoLite2 databases). If the database does not contain a record for\nthat IP address, the method will return ``None``.\n\nExample\n-------\n\n.. code-block:: pycon\n\n    >>> import maxminddb\n    >>>\n    >>> reader = maxminddb.open_database('GeoLite2-City.mmdb')\n    >>> reader.get('1.1.1.1')\n    {'country': ... }\n    >>>\n    >>> reader.close()\n\nExceptions\n----------\n\nThe module will return an ``InvalidDatabaseError`` if the database is corrupt\nor otherwise invalid. A ``ValueError`` will be thrown if you look up an\ninvalid IP address or an IPv6 address in an IPv4 database.\n\nRequirements\n------------\n\nThis code requires Python 2.6+ or 3.3+. The C extension requires CPython. The\npure Python implementation has been tested with PyPy.\n\nOn Python 2, the `ipaddress module <https://pypi.python.org/pypi/ipaddress>`_ is\nrequired.\n\nVersioning\n----------\n\nThe MaxMind DB Python module uses `Semantic Versioning <http://semver.org/>`_.\n\nSupport\n-------\n\nPlease report all issues with this code using the `GitHub issue tracker\n<https://github.com/maxmind/MaxMind-DB-Reader-python/issues>`_\n\nIf you are having an issue with a MaxMind service that is not specific to this\nAPI, please contact `MaxMind support <http://www.maxmind.com/en/support>`_ for\nassistance.\n", 
    "lcname": "maxminddb", 
    "bugtrack_url": "https://github.com/maxmind/MaxMind-DB-Reader-python/issues", 
    "github": false, 
    "name": "maxminddb", 
    "license": "Apache License, Version 2.0", 
    "summary": "Reader for the MaxMind DB format", 
    "split_keywords": [], 
    "author_email": "goschwald@maxmind.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2017-03-13T15:58:18", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/f8/7a/bac498d2b7491dd8b837dff8831a7e7628db72c4b840b54743961a8f0454/maxminddb-1.3.0.tar.gz", 
            "md5_digest": "3b1dac458e4d1ac6cfb4ccac50ad1787", 
            "downloads": 0, 
            "filename": "maxminddb-1.3.0.tar.gz", 
            "packagetype": "sdist", 
            "path": "f8/7a/bac498d2b7491dd8b837dff8831a7e7628db72c4b840b54743961a8f0454/maxminddb-1.3.0.tar.gz", 
            "size": 1428863
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}