plevin 0.1.3

Location, network and abuse information for any IP address in one offline file.
No API, no rate limit, no lookup leaving the machine.

pip install "plevin[db,full]"

import plevin

found = plevin.lookup("1.1.1.1")  # str, int, packed bytes or ipaddress object

Always a Result, never None; ValueError for anything that is not an address, and an integer reads as v6 only above 0xFFFFFFFF, so lookup(1) is 0.0.0.1.

>>> found.place.city.name, found.place.city.region.name, found.place.country.name
('Brisbane', 'Queensland', 'Australia')

>>> found.network.asn, found.network.operator.brand, found.network.cidr
(13335, 'Cloudflare', '1.1.1.0/24')

>>> exit_node = plevin.lookup("185.220.101.1")
>>> exit_node.abuse.service, exit_node.abuse.risk, exit_node.abuse.is_tor_exit_node
('tor_exit_node', 0.97, True)

The database is a separate wheel, found without being given a path. Install one, or several and the richest wins.

PLEVIN_DB=/path/to/plevin.plv or plevin.use("plevin.plv") reads a file of your own instead; plevin.Plevin(path) opens one without touching the module's.

Every field

found.place is where the address is, found.network who announces it, found.abuse what has been seen from it. Any of the three is None where the build carries none of it, and every leaf is None rather than "" or 0 where a source says nothing.

Place(
    lat=-27.4675,
    lon=153.0281,
    accuracy=200,
    confidence=36,
    granularity='city',
    city=City(
        id=2174003,
        name='Brisbane',
        ascii='Brisbane',
        country='AU',
        population=2780063,
        elevation=27,
        postal='4000',
        postal_partial=None,
        timezone='Australia/Brisbane',
        type='regional capital',
        capital='region',
        region=Region(id=2152274, code='04', iso='AU-QLD', name='Queensland',
                      type='State'),
        district=District(id=7839562, code='31000', name='Brisbane'),
        metro=None,
    ),
    country=Country(
        code='AU',
        name='Australia',
        official=None,
        common=None,
        iso3='AUS',
        numeric='036',
        flag='🇦🇺',
        european_union=False,
        driving_side='left',
    ),
    time=Time(
        timezone='Australia/Brisbane',
        abbreviation='AEST',
        local='2026-08-13T19:20:00+10:00',
        utc_offset='+10:00',
        is_dst=False,
        dst_start=None,
        dst_end=None,
    ),
)

country and time are derived, not stored: country from the two-letter code through pycountry, time from the zone name through zoneinfo, both only with the full extra. Without it the code, the flag, the EU and driving-side answers and the zone name still come through. capital says which capital the city is, region.iso is ISO 3166-2 and region.code the GeoNames admin1 number, postal_partial is the leading part of postal a source could only narrow that far.

Network(
    asn=13335,
    handle='CLOUDFLARENET',
    prefix=24,
    cidr='1.1.1.0/24',
    start='1.1.1.0',
    end='1.1.1.255',
    rpki='valid',
    roas=1,
    operator=Operator(
        company='Cloudflare, Inc.',
        brand='Cloudflare',
        domain='cloudflare.com',
        website='https://www.cloudflare.com',
        category='content',
        tier=2,
        peering=356,
        scope='Global',
        rir='arin',
        since=2010,
        street='101 Townsend St',
        state='CA',
        postal='94107-1934',
        country='US',
        abuse_email='abuse@cloudflare.com',
        city=City(name='San Francisco', ...),  # a full City, as above
    ),
    carrier=Carrier(user_type='hosting', user_count=19, mcc=None, mnc=None,
                    is_mobile=False),
)

cidr is the announcement the address falls in, masked out of the address itself, so 1.1.1.1 and 1.0.0.1 reach one operator through two prefixes. rpki is valid, invalid or unknown and roas how many ROAs agree. brand drops the legal form and the words every network carries, so GOOGLE and Google LLC both read Google; domain is the host of website, else of abuse_email. tier is 1 transit-free, 2 has customers, 3 edge; peering the exchange count; category one of residential, business, hosting, education, government, military, cdn, content, infrastructure, cellular, search_engine_spider, traveler, transit, exchange or non-profit.

>>> plevin.lookup("185.220.101.1").abuse
Abuse(
    name='Tor',
    service='tor_exit_node',
    evidence='measured',
    risk=0.97,
    network_risk=None,
    last_seen_days=1,
    is_anycast=False,
    is_satellite=False,
    is_hosting_provider=True,
    is_proxy=False,
    is_public_proxy=False,
    is_residential_proxy=False,
    is_anonymous_vpn=False,
    is_tor_exit_node=True,
    is_private_relay=False,
    is_anonymous=True,
)

risk is 0 to 1 for the address, network_risk the same for the whole ASN, None where nothing has ever been seen — which is not a risk of zero. evidence is published, measured, reported or inferred, strongest first; service is tor_exit_node, private_relay, anonymous_vpn, residential_proxy or public_proxy, most specific first. A public proxy on a residential or cellular line reads as residential_proxy with evidence='inferred'. The ten booleans are read off service and the carrier's type, never stored.

What an address says on its own

Answered without the database, so they hold for every address:

>>> found = plevin.lookup("2606:4700::1111")
>>> found.number, found.compressed
(50543257672059871404715951523469725969, '2606:4700::1111')

>>> found.expanded
'2606:4700:0000:0000:0000:0000:0000:1111'

>>> found.arpa
'1.1.1.1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.7.4.6.0.6.2.ip6.arpa'

is_global and is_bogon, then is_private, is_loopback, is_multicast, is_reserved, is_link_local, is_unique_local, is_documentation, is_shared (100.64/10) and is_benchmark (198.18/15), bisected out of the IANA special-purpose registries.

>>> plevin.lookup("::ffff:8.8.8.8").tunnel, plevin.lookup("::ffff:8.8.8.8").embedded_ipv4
('ipv4-mapped', '8.8.8.8')

>>> plevin.lookup("2002:808:808::1").is_6to4
True

tunnel is ipv4-mapped, 6to4, teredo, nat64 or None, with embedded_ipv4 the address it carries; is_ipv4_mapped, is_6to4 and is_teredo beside it.

Good for

• Country routing, pricing and compliance without a third-party call
• Local time and flag before the user types anything
• Bulk log enrichment, at 2M lookups/s on repeats
• Abuse handling and RPKI triage in the same process, no whois or RDAP
• Air-gapped deployments, where no address leaves the process

Data

Rebuilt monthly from MaxMind GeoLite2, IP2Location LITE, GeoNames, Natural Earth, a RIPE RIS RIB, RPKI ROAs, the NRO delegations, CAIDA, PeeringDB, asn-abuse and the feeds in builder/data/feeds.json. Plevin(path).built dates your copy, .selection names which fields it carries and .fields lists them.

Python 3.10+. No dependencies on 3.14, where compression.zstd is in the standard library; pyzstd below it. pycountry and, on Windows, tzdata come with the full extra.

Speed

Blocks decode on reach and stay decoded, so a real log lands between the two: the boundary a lookup found, the rows it linked to and the answer itself are all kept.

Your own file

from plevin import Plevin

with_places = Plevin("dist/plevin.metro-place.plv")
with_places.lookup("1.1.1.1").place.city.name

Read-only and memory-mapped, so processes and threads share one file. For the stored rows without any of the shaping above — dictionaries, codes already read as words — Plevin(path).file.row(value, wide) is the reader underneath.

Builder

The Rust builder, its sources, the file format and the selection language are in builder/README.md.

cd builder && cargo build --release
./target/release/plevin-builder              # dist/plevin.plv, every field
./target/release/plevin-builder place+metro  # dist/plevin.metro-place.plv

Lookup page

plevin.tn3w.dev reads the database in the tab and answers there: no API, and no address of yours sent anywhere except to the service that tells you your own, and to a resolver for the hostname. It is plain HTML, CSS and JavaScript in site/, built and deployed by pages.yml whenever a database is released.

The same deployment rehosts every release file with open CORS, which the GitHub release downloads do not carry:

Cloudflare Worker

worker/ is the smallest useful API around the file: it keeps the newest release in a KV namespace and answers out of an isolate that opened it once.

cd worker && npm install
npx wrangler kv namespace create PLEVIN   # put the id in wrangler.toml
npx wrangler deploy
curl -X POST https://plevin.<you>.workers.dev/refresh   # then monthly, on a cron

curl https://plevin.<you>.workers.dev/1.1.1.1   # any address
curl https://plevin.<you>.workers.dev/me        # the caller's own
curl https://plevin.<you>.workers.dev/about     # what the file carries

REFRESH_TOKEN guards the refresh where it is set, and DATABASE picks a smaller file than plevin.plv.

Mini file

plevin_mini.py is the lookup with no package around it. Drop it beside a .plv and it runs.

python plevin_mini.py plevin.plv 8.8.8.8

>>> from plevin_mini import Plevin
>>> Plevin("plevin.plv").lookup("8.8.8.8")["network"]["asn"]
15169

Plain dictionaries of the stored rows, codes already read as words, and nothing derived: no models, no country, no clock, no discovery. 3,600,000 lookups a second warm. It is linted and type-checked with the package.

Development

cd python
uv run pytest          # 168 tests, 100% branch coverage
uv run mypy
uv run basedpyright
uvx ruff check . ../plevin_mini.py --config pyproject.toml
uv build --wheel

cd ../builder && cargo fmt --check && cargo clippy

License

Apache 2.0 for the readers and the builder, see LICENSE. The database carries the licenses of the sources it was built from, listed in builder/README.md.