plevin 0.1.4

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.98, 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.98,
    network_risk=0.82,
    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, so which is not a risk of zero. An address running an anonymity service carries at least that service's own risk, so a Tor exit no feed has reported still reads high. 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.

>>> plevin.lookup("2001:67c:e60:c0c:192:42:116:55").decimal_ipv4
'192.42.116.55'

decimal_ipv4 is a guess and never a tunnel: the last four hextets where an operator wrote a v4 address into them as decimal. It is None wherever a real tunnel answers.

>>> found = plevin.lookup("8.8.8.8")
>>> found.as_ipv4_mapped, found.as_6to4, found.as_nat64
('::ffff:8.8.8.8', '2002:808:808::', '64:ff9b::808:808')

as_ipv4_mapped, as_6to4 and as_nat64 write a v4 address the other way about, as the v6 addresses that carry it; all three are None for a v6 address, where embedded_ipv4 already says what it carries.

What DNS says, where you ask for it

Off unless dns=True says otherwise, since it is the one part of a lookup that leaves the machine:

>>> plevin.lookup("8.8.8.8", dns=True).dns
Dns(
    asked='8.8.8.8',
    hostname='dns.google',
    hostnames=('dns.google',),
    ipv4='8.8.4.4',
    ipv6='2001:4860:4860::8888',
    ipv4_addresses=('8.8.4.4', '8.8.8.8'),
    ipv6_addresses=('2001:4860:4860::8888', '2001:4860:4860::8844'),
    alias=None,
    zone='8.8.8.in-addr.arpa',
    zone_primary='ns1.google.com',
    zone_contact='dns-admin@google.com',
    is_confirmed=True,
    is_signed=True,
)

hostname is the first PTR name and hostnames all of them, ipv4 and ipv6 that name resolved forward with ipv4_addresses and ipv6_addresses all of those, so each address names its other half; is_confirmed says the name leads back to the address, which is forward-confirmed reverse DNS; zone, zone_primary and zone_contact come from the reverse zone's SOA, naming who runs the range; is_signed is the DNSSEC verdict and alias a CNAME in the way; asked is the address actually asked about, which for a tunnel is the v4 it carries. Four questions go out in two rounds, PTR and SOA on the reverse name together and then A and AAAA of the hostname, written onto the wire and sent to every server at once, so the system's own from /etc/resolv.conf or the Windows registry and 1.1.1.1, 8.8.8.8 and 9.9.9.9, so first real answer winning, TCP where one comes back truncated, and kept for an hour, so a log with a thousand lines from one address asks once.

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 daily 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, so dictionaries, codes already read as words, so 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

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.