{"id":13843397,"url":"https://github.com/maxmind/MaxMind-DB-Reader-python","last_synced_at":"2025-07-11T18:32:07.390Z","repository":{"id":10829450,"uuid":"13107101","full_name":"maxmind/MaxMind-DB-Reader-python","owner":"maxmind","description":"Python MaxMind DB reader extension","archived":false,"fork":false,"pushed_at":"2025-07-07T14:42:08.000Z","size":684,"stargazers_count":199,"open_issues_count":2,"forks_count":37,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-07-07T15:47:12.041Z","etag":null,"topics":["geoip","geoip2","maxmind","mmdb"],"latest_commit_sha":null,"homepage":"https://maxminddb.readthedocs.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxmind.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-09-25T22:26:14.000Z","updated_at":"2025-07-07T14:42:11.000Z","dependencies_parsed_at":"2023-10-13T13:44:31.084Z","dependency_job_id":"15e4407d-b15c-4d22-8a91-12a8a6dc4606","html_url":"https://github.com/maxmind/MaxMind-DB-Reader-python","commit_stats":{"total_commits":476,"total_committers":21,"mean_commits":"22.666666666666668","dds":"0.19117647058823528","last_synced_commit":"484d8b7c9f28fe8a21e7b9940fb9ef615d5475e5"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/maxmind/MaxMind-DB-Reader-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxmind","download_url":"https://codeload.github.com/maxmind/MaxMind-DB-Reader-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxmind%2FMaxMind-DB-Reader-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264870442,"owners_count":23676230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geoip","geoip2","maxmind","mmdb"],"created_at":"2024-08-04T17:02:06.733Z","updated_at":"2025-07-11T18:32:07.381Z","avatar_url":"https://github.com/maxmind.png","language":"Python","funding_links":[],"categories":["Python (1887)","Python"],"sub_categories":[],"readme":"========================\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\nTo install ``maxminddb``, type:\n\n.. code-block:: bash\n\n    $ pip install maxminddb\n\nIf you are not able to install from PyPI, you may also use ``pip`` from the\nsource directory:\n\n.. code-block:: bash\n\n    $ python -m pip install .\n\nThe installer will attempt to build the C extension. If this fails, the\nmodule will fall-back to the pure Python implementation.\n\nUsage\n-----\n\nTo use this module, you must first download or create a MaxMind DB file. We\nprovide `free GeoLite2 databases\n\u003chttps://dev.maxmind.com/geoip/geolocate-an-ip/databases?lang=en\u003e`_. These\nfiles must be decompressed with ``gunzip``.\n\nAfter you have obtained a database and imported the module, call\n``open_database`` with a path, or file descriptor (in the case of ``MODE_FD``),\nto the database as the first argument. Optionally, you may pass a mode as the\nsecond argument. The modes are exported 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_FD`` - load database into memory from a file descriptor. Pure Python.\n* ``MODE_AUTO`` - try ``MODE_MMAP_EXT``, ``MODE_MMAP``, ``MODE_FILE`` in that\n  order. Default.\n\n**NOTE**: When using ``MODE_FD``, it is the *caller's* responsibility to be\nsure that the file descriptor gets closed properly. The caller may close the\nfile descriptor immediately after the ``Reader`` object is created.\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\nIf you wish to also retrieve the prefix length for the record, use the\n``get_with_prefix_len`` method. This returns a tuple containing the record\nfollowed by the network prefix length associated with the record.\n\nYou may also iterate over the whole database. The ``Reader`` class implements\nthe ``__iter__`` method that returns an iterator. This iterator yields a\ntuple containing the network and the record.\n\nExample\n-------\n\n.. code-block:: pycon\n\n    \u003e\u003e\u003e import maxminddb\n    \u003e\u003e\u003e\n    \u003e\u003e\u003e with maxminddb.open_database('GeoLite2-City.mmdb') as reader:\n    \u003e\u003e\u003e\n    \u003e\u003e\u003e     reader.get('152.216.7.110')\n    {'country': ... }\n    \u003e\u003e\u003e\n    \u003e\u003e\u003e     reader.get_with_prefix_len('152.216.7.110')\n    ({'country': ... }, 24)\n    \u003e\u003e\u003e\n    \u003e\u003e\u003e     for network, record in reader:\n    \u003e\u003e\u003e         ...\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 3.9+. Older versions are not supported. The C\nextension requires CPython.\n\nVersioning\n----------\n\nThe MaxMind DB Python module uses `Semantic Versioning \u003chttps://semver.org/\u003e`_.\n\nSupport\n-------\n\nPlease report all issues with this code using the `GitHub issue tracker\n\u003chttps://github.com/maxmind/MaxMind-DB-Reader-python/issues\u003e`_\n\nIf you are having an issue with a MaxMind service that is not specific to this\nAPI, please contact `MaxMind support \u003chttps://www.maxmind.com/en/support\u003e`_ for\nassistance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxmind%2FMaxMind-DB-Reader-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxmind%2FMaxMind-DB-Reader-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxmind%2FMaxMind-DB-Reader-python/lists"}