Metadata-Version: 2.4
Name: ipgeolocation-mmdb-reader
Version: 1.0.0
Summary: IPGeolocation MMDB Reader
Project-URL: Homepage, https://ipgeolocation.io/
Project-URL: Repository, https://git.jfreaks.com/IPGeolocation/mmdb-reader
Project-URL: Issues, https://git.jfreaks.com/IPGeolocation/mmdb-reader/issues
Author-email: "ipgeolocation.io" <support@ipgeolocation.io>
License: MIT License
        
        Copyright (c) 2025 ipgeolocation.io
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Internet
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# IPGeolocation MMDB Reader 
A fast, minimal, pure‑Python reader for MMDB files.

- Zero dependencies
- Supports both IPv4 and IPv6 lookups

## Requirements
- Python 3.9+ (older versions are not supported)

## Installation

```bash
pip install ipgeolocation-mmdb-reader
```

## Getting a Database
To use this module, you must have an MMDB file. 
You can build your own MMDB file, or download ready-made databases samples from [ipgeolocation.io](https://ipgeolocation.io/ip-geolocation-database.html). 
Downloaded files are in zip format and must be uncompressed using unzip.

## Quick Start (Python)
After you have obtained a database and imported the module, call `IPGeolocationMMDBReader` with a path to the database as the first argument.
The `IPGeolocationMMDBReader` function returns a `Reader` object. To look up an IP address, use the lookup method on this object. 
The method will return the corresponding values for the IP address from the database. 
If the database does not contain a record for that IP address, the method will return None.

If you wish to retrieve the metadata of that MMDB file, you can use the `get_metadata` method. This will return a tuple containing the metadata of that mmdb file.

```python
import json # for pretty print results
from ipgeo_mmdb_reader.reader import IPGeolocationMMDBReader

with IPGeolocationMMDBReader("db-ip-city-company-asn.mmdb") as r:
    metadata = r.get_metadata()
    result = r.lookup("1.1.1.1")
    if result is None:
        print("No match")
    else:
        print(json.dumps(metadata, indent=4, ensure_ascii=False))
        print(json.dumps(result, indent=4, ensure_ascii=False))
```

- `lookup(ip: str) -> dict | None`
Returns a dictionary of values for the IP address, or None if the IP is not present in the database.

- `get_metadata() -> dict`
Returns a dictionary containing the MMDB file’s metadata.

### Response
- #### Metadata
```
{
    "binary_format_major_version": 2,
    "binary_format_minor_version": 0,
    "build_epoch": 1754992987,
    "database_type": "ipgeolocation.io Database",
    "description": {
        "en": "MAX-IP-GEO Database from ipgeolocation.io."
    },
    "ip_version": 6,
    "languages": [
        "en",
        "de",
        "ru",
        "ko",
        "pt",
        "ja",
        "fa",
        "fr",
        "zh-CN",
        "es",
        "cs",
        "it"
    ],
    "node_count": 108458689,
    "record_size": 32
}
```

- #### IP Lookup
```
{
  "asn": {
    "as_number": "13335",
    "country_code": "US",
    "domain": "cloudflare.com",
    "organization": "Cloudflare, Inc.",
    "type": "BUSINESS"
  },
  "company": {
    "domain": "",
    "name": {
      "en": "APNIC Research and Development"
    },
    "type": ""
  },
  "connection_type": "",
  "location": {
    "accuracy_radius": "18.654",
    "city": {
      "name": {
        "cs": "Jižní Brisbane",
        "de": "South Brisbane",
        "en": "South Brisbane",
        "es": "Brisbane Sur",
        "fa": "بریزبن جنوبی",
        "fr": "Brisbane Sud",
        "it": "Brisbane Meridionale",
        "ja": "サウスブリスベン",
        "ko": "사우스브리즈번",
        "pt": "Brisbane Sul",
        "ru": "Южный Брисбен",
        "zh": "南布里斯班"
      }
    },
    "confidence": "medium",
    "coordinates": {
      "latitude": "-27.47306",
      "longitude": "153.01421"
    },
    "country": {
      "capital": {
        "cs": "Canberra",
        "de": "Canberra",
        "en": "Canberra",
        "es": "Canberra",
        "fa": "کانبرا",
        "fr": "Canberra",
        "it": "Canberra",
        "ja": "キャンベラ",
        "ko": "캔버라",
        "pt": "Camberra",
        "ru": "Канберра",
        "zh": "堪培拉"
      },
      "code2": "AU",
      "code3": "AUS",
      "code_ioc": "AUS",
      "continent": {
        "code": "OC",
        "name": {
          "cs": "Oceánie",
          "de": "Ozeanien",
          "en": "Oceania",
          "es": "Oceanía",
          "fa": "اقیانوسیه",
          "fr": "Océanie",
          "it": "Oceania",
          "ja": "オセアニア",
          "ko": "오세아니아",
          "pt": "Oceania",
          "ru": "Океания",
          "zh": "大洋洲"
        }
      },
      "currency": {
        "code": "AUD",
        "name": {
          "cs": "Australský dolar",
          "de": "Australischer Dollar",
          "en": "Australian Dollar",
          "es": "Dólar australiano",
          "fa": "دلار استرالیا",
          "fr": "Dollar australien",
          "it": "Dollaro australiano",
          "ja": "オーストラリア・ドル",
          "ko": "호주 달러",
          "pt": "Dólar australiano",
          "ru": "Австралийский доллар",
          "zh": "澳大利亚元"
        },
        "symbol": "A$"
      },
      "metadata": {
        "calling_code": "+61",
        "languages": "en-AU",
        "tld": ".au"
      },
      "name": {
        "cs": "Austrálie",
        "de": "Australien",
        "en": "Australia",
        "es": "Australia",
        "fa": "استرالیا",
        "fr": "Australie",
        "it": "Australia",
        "ja": "オーストラリア",
        "ko": "호주",
        "pt": "Austrália",
        "ru": "Австралия",
        "zh": "澳大利亚"
      },
      "name_official": {
        "cs": "Australské společenství",
        "de": "Commonwealth of Australia",
        "en": "Commonwealth of Australia",
        "es": "Mancomunidad de Australia",
        "fa": "قلمرو همسود استرالیا",
        "fr": "Commonwealth d’Australie",
        "it": "Commonwealth dell’Australia",
        "ja": "オーストラリア連邦",
        "ko": "오스트레일리아 연방",
        "pt": "Comunidade da Austrália",
        "ru": "Содружество Австралии",
        "zh": "澳大利亚联邦"
      }
    },
    "district": {
      "name": {
        "cs": "Brisbane",
        "de": "Brisbane",
        "en": "Brisbane",
        "es": "Brisbane",
        "fa": "بریزبن",
        "fr": "Brisbane",
        "it": "Brisbane",
        "ja": "ブリスベン",
        "ko": "브리즈번",
        "pt": "Brisbane",
        "ru": "Брисбен",
        "zh": "布里斯班"
      }
    },
    "dma_code": "",
    "geoname_id": "10113228",
    "state": {
      "code": "AU-QLD",
      "name": {
        "cs": "Queensland",
        "de": "Queensland",
        "en": "Queensland",
        "es": "Queensland",
        "fa": "کوئینزلند",
        "fr": "Queensland",
        "it": "Queensland",
        "ja": "クイーンズランド",
        "ko": "퀸즐랜드",
        "pt": "Queensland",
        "ru": "Квинсленд",
        "zh": "昆士兰"
      }
    },
    "zipcode": "4101"
  },
  "time_zone": "Australia/Brisbane"
}

```

## Exceptions
These custom exceptions may be raised:
- CorruptDatabaseError – The database is corrupt or invalid.
- MMDBError – Invalid IP address format, or an IPv6 address queried against an IPv4-only database.
- MetadataError – Metadata is invalid or not a dictionary.
- UnsupportedRecordSizeError – Record size is not one of 24, 28, or 32 bits.

## Versioning
This project follows semantic versioning.

## Support
Please report all issues with this code using the [GitHub issue tracker](https://git.jfreaks.com/IPGeolocation/mmdb-reader/issues)
