Metadata-Version: 2.4
Name: maxminddb-polars
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: polars>=1.43.2,<2.1
Requires-Dist: pytest>=9 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Fast Polars expressions for MaxMind DB lookups
Keywords: maxmind,geoip,mmdb,polars
Author-email: Gregory Oschwald <oschwald@gmail.com>
License-Expression: ISC
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/oschwald/maxminddb-polars/issues
Project-URL: Changelog, https://github.com/oschwald/maxminddb-polars/blob/main/CHANGELOG.md
Project-URL: Contributing, https://github.com/oschwald/maxminddb-polars/blob/main/CONTRIBUTING.md
Project-URL: Homepage, https://github.com/oschwald/maxminddb-polars
Project-URL: Repository, https://github.com/oschwald/maxminddb-polars

# maxminddb-polars

Look up IP addresses in MaxMind databases with Polars expressions, implemented
in Rust. Read a single field with `lookup_path` or a record with `lookup`.

You supply the database. The package does not bundle or download one.

Install it from PyPI with:

```console
python -m pip install maxminddb-polars
```

```python
from pathlib import Path

import polars as pl
import maxminddb_polars as mmp

database = Path("/data/GeoLite2-City.mmdb")
frame = pl.DataFrame({"ip": ["81.2.69.142", None]})

result = frame.select(
    country=mmp.lookup_path("ip", database, ("country", "iso_code")),
    city=mmp.lookup("ip", database),
)

# The expression namespace is equivalent:
country = pl.col("ip").mmdb.lookup_path(database, ("country", "iso_code"))
```

`lookup` detects the schema for
[14 standard database families](https://github.com/oschwald/maxminddb-polars/blob/main/docs/api.md#supported-database-metadata).
Pass `dtype` to read only selected fields or use a custom database. See
[Custom and partial schemas](https://github.com/oschwald/maxminddb-polars/blob/main/docs/custom-schemas.md).

The IP column must have String dtype. Null inputs, lookup misses, and missing
paths return null. Invalid IP strings raise an error by default. Pass
`strict=False` to turn them into nulls. Database and schema errors still raise.

To update a database, replace the file atomically and create new expressions.
See [Database updates](https://github.com/oschwald/maxminddb-polars/blob/main/docs/api.md#database-updates)
for cache behavior and memory limits.

## Development

Install the prerequisites in
[CONTRIBUTING.md](https://github.com/oschwald/maxminddb-polars/blob/main/CONTRIBUTING.md#prerequisites)
and run:

```console
git submodule update --init --recursive
scripts/check
```

Documentation:

- [API and supported databases](https://github.com/oschwald/maxminddb-polars/blob/main/docs/api.md)
- [Custom and partial schemas](https://github.com/oschwald/maxminddb-polars/blob/main/docs/custom-schemas.md)
- [Installation and compatibility](https://github.com/oschwald/maxminddb-polars/blob/main/docs/compatibility.md)
- [Performance and benchmarks](https://github.com/oschwald/maxminddb-polars/blob/main/docs/performance.md)
- [Competitor comparison](https://github.com/oschwald/maxminddb-polars/blob/main/docs/comparison.md)
- [Security testing](https://github.com/oschwald/maxminddb-polars/blob/main/docs/security-testing.md)
- [Maintainer operations](https://github.com/oschwald/maxminddb-polars/blob/main/docs/maintaining.md)

## Project policies

The Python API follows Semantic Versioning. The crates.io package is the native
implementation of the Python plugin and has no supported Rust API.

- [Changelog](https://github.com/oschwald/maxminddb-polars/blob/main/CHANGELOG.md)
- [Contributing](https://github.com/oschwald/maxminddb-polars/blob/main/CONTRIBUTING.md)
- [Security policy](https://github.com/oschwald/maxminddb-polars/blob/main/SECURITY.md)
- [ISC license](https://github.com/oschwald/maxminddb-polars/blob/main/LICENSE)

