Many useful utilities are provided for IP addresses outside of whois functionality. The following utilities are used throughout the ipwhois library for validation and parsing.

Country Codes

The legacy country code listing (iso_3166-1_list_en.xml) is no longer available as a free export from iso.org. Support has been added for iso_3166-1.csv, which is now the default.

Use Legacy XML File:

>>>> from ipwhois.utils import get_countries
>>>> countries = get_countries(is_legacy_xml=True)

Human Readable Fields

Human readable translations are available for all result fields (RDAP and Legacy Whois). Translations are currently limited to the short name (_short), the name (_name), and the description (_description).

See the ipwhois CLI (ipwhois_utils_cli.py) for an example.

Import the human readable translation dictionaries

>>>> from ipwhois.hr import (HR_ASN, HR_ASN_ORIGIN, HR_RDAP_COMMON,
                             HR_RDAP, HR_WHOIS, HR_WHOIS_NIR)

Usage Examples

IPv4 Strip Zeros

Strip leading zeros in each octet of an IPv4 address string.

>>>> from ipwhois.utils import ipv4_lstrip_zeros
>>>> print(ipv4_lstrip_zeros(''))

CIDR Calculation

Get a list of CIDR range(s) from a start and end IP address.

>>>> from ipwhois.utils import calculate_cidr
>>>> print(calculate_cidr('', ''))

['', '', '', '',
'', '', '', '',
'', '', '', '']

Check if IP is reserved/defined

Check if an IPv4 or IPv6 address is in a reserved/defined pool.

>>>> from ipwhois.utils import (ipv4_is_defined, ipv6_is_defined)
>>>> print(ipv4_is_defined(''))

(True, 'Private-Use Networks', 'RFC 1918')

>>>> print(ipv6_is_defined('fe80::'))

(True, 'Link-Local', 'RFC 4291, Section 2.5.6')

Country Code Mapping

Retrieve a dictionary mapping ISO 3166-1 country codes to country names.

>>>> from ipwhois import IPWhois
>>>> from ipwhois.utils import get_countries

>>>> countries = get_countries()
>>>> obj = IPWhois('')
>>>> results = obj.lookup_whois(False)
>>>> print(countries[results['nets'][0]['country']])

United States

Iterable to unique elements (order preserved)

List unique elements, preserving the order. This was taken from the itertools recipes.

>>>> from ipwhois.utils import unique_everseen
>>>> print(list(unique_everseen(['b', 'a', 'b', 'a', 'c', 'a', 'b', 'c')))

['b', 'a', 'c']

Parse IPs/ports from text/file

Search an input string and/or file, extracting and counting IPv4/IPv6 addresses/networks. Summarizes ports with sub-counts.

>>>> from ipwhois.utils import unique_addresses
>>>> from pprint import pprint

>>>> input_data = (
        'You can have IPs like, or 2001:4860:4860::8888'
        'Put a port at the end or for IPv6: '
        '[2001:4860:4860::8888]:443 or even networks like '
        ' and 2001:4860::/32.'

>>>> results = unique_addresses(data=input_data, file_path=None)
>>>> pprint(results)

{'2001:4860:4860::8888': {'count': 2, 'ports': {'443': 1}},
 '2001:4860::/32': {'count': 1, 'ports': {}},
 '': {'count': 1, 'ports': {}},
 '': {'count': 2, 'ports': {'80': 1}}}

Generate random IP addresses

Generate random, unique IPv4/IPv6 addresses that are not defined (can be looked up using ipwhois).

>>>> from ipwhois.utils import ipv4_generate_random
>>>> for address in ipv4_generate_random(10):
>>>>     print(address)

>>>> from ipwhois.utils import ipv6_generate_random
>>>> for address in ipv6_generate_random(10):
>>>>     print(address)