maxminddb

maxminddb reads the MaxMind DB binary format — a compact, IP-subnet-indexed database used by MaxMind’s GeoIP2 and GeoLite2 products — and returns the associated data (country, city, ASN, etc.) for a given IPv4 or IPv6 address. It ships both a pure-Python reader and an optional C extension built on libmaxminddb for significantly faster lookups.

The package handles opening a database in-memory, memory-mapped, or file-descriptor mode, and falls back automatically to the pure-Python implementation if the C extension fails to build, so it works across platforms without requiring compilation.

What You Get

• open_database() supporting in-memory, memory-mapped, and file-descriptor access modes
• A pure-Python decoder plus an optional C extension (libmaxminddb) for faster lookups
• Automatic fallback to the pure-Python reader if the C extension can’t be built
• IPv4 and IPv6 address lookup support with prefix-length metadata
• Full type stubs for static type checking

Common Use Cases

• Geolocating request IPs server-side to show localized content or pricing
• Enriching log or analytics pipelines with country/city/ASN data per IP address
• Fraud or abuse detection systems that flag requests from unexpected geographies
• CDN or routing logic that needs fast, local IP-to-location lookups without an external API call

Under The Hood

Architecture: maxminddb/reader.py implements the pure-Python reader, parsing the mmdb binary format’s search tree and data section via decoder.py; the extension/ directory bundles libmaxminddb (MaxMind’s C library) as an optional compiled extension that setup.py attempts to build, with automatic fallback to the pure-Python path if compilation fails. Tech Stack: Python core with an optional C extension via libmaxminddb, packaged with setup.py; supports memory-mapped, in-memory, and file-descriptor access modes for the underlying .mmdb file. Code Quality: tests/ includes fixture .mmdb test data and covers both the pure-Python and C-extension code paths, with GitHub Actions CI; the project ships type stubs and Sphinx-generated docs (docs/), indicating a mature, well-maintained codebase. API Design: the reader API is small and consistent — open_database() returns a Reader object exposing .get() for a straightforward IP-in, data-out lookup, keeping the common case (look up a single IP) to one or two lines of code.