Library Structure

exception ipwhois.ipwhois.ASNLookupError[source]

An Exception for when the ASN lookup failed.

exception ipwhois.ipwhois.ASNRegistryError[source]

An Exception for when the ASN registry does not match one of the five expected values (arin, ripencc, apnic, lacnic, afrinic).

exception ipwhois.ipwhois.BlacklistError[source]

An Exception for when the server is in a blacklist.

exception ipwhois.ipwhois.HostLookupError[source]

An Exception for when the host lookup failed.

exception ipwhois.ipwhois.IPDefinedError[source]

An Exception for when the IP is defined (does not need to be resolved).

class ipwhois.ipwhois.IPWhois(address, timeout=5, proxy_opener=None)[source]

The class for performing ASN/whois lookups and parsing for IPv4 and IPv6 addresses.

Parameters:
  • address – An IPv4 or IPv6 address as a string, integer, IPv4Address, or IPv6Address.
  • timeout – The default timeout for socket connections in seconds.
  • proxy_opener – The urllib.request.OpenerDirector request for proxy support or None.
Raises:

IPDefinedError – The address provided is defined (does not need to be resolved).

get_asn_dns()[source]

The function for retrieving ASN information for an IP address from Cymru via port 53 (DNS).

Returns:

A dictionary containing the following keys: asn (String) - The Autonomous System Number. asn_date (String) - The ASN Allocation date. asn_registry (String) - The assigned ASN registry. asn_cidr (String) - The assigned ASN CIDR. asn_country_code (String) - The assigned ASN country code.

Return type:

Dictionary

Raises:
get_asn_whois(retry_count=3)[source]

The function for retrieving ASN information for an IP address from Cymru via port 43 (WHOIS).

Parameters:

retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.

Returns:

A dictionary containing the following keys: asn (String) - The Autonomous System Number. asn_date (String) - The ASN Allocation date. asn_registry (String) - The assigned ASN registry. asn_cidr (String) - The assigned ASN CIDR. asn_country_code (String) - The assigned ASN country code.

Return type:

Dictionary

Raises:
get_host(retry_count=3)[source]

The function for retrieving host information for an IP address.

Parameters:retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
Returns:hostname, aliaslist, ipaddrlist
Return type:Tuple
Raises:HostLookupError – The host lookup failed.
get_rws(url=None, retry_count=3)[source]

The function for retrieving Whois-RWS information for an IP address via HTTP (Whois-RWS).

Parameters:
  • url – The URL to retrieve.
  • retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
Returns:

The whois data in Json format.

Return type:

Dictionary

Raises:

WhoisLookupError – The whois RWS lookup failed.

get_whois(asn_registry='arin', retry_count=3, server=None, port=43, extra_blacklist=None)[source]

The function for retrieving whois or rwhois information for an IP address via any port. Defaults to port 43 (WHOIS).

Parameters:
  • asn_registry – The NIC to run the query against.
  • retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
  • server – An optional server to connect to. If provided, asn_registry will be ignored.
  • port – The network port to connect on.
  • extra_blacklist – A list of blacklisted whois servers in addition to the global BLACKLIST.
Returns:

The raw whois data.

Return type:

String

Raises:
lookup(inc_raw=False, retry_count=3, get_referral=False, extra_blacklist=None, ignore_referral_errors=False)[source]

The function for retrieving and parsing whois information for an IP address via port 43 (WHOIS).

Parameters:
  • inc_raw – Boolean for whether to include the raw whois results in the returned dictionary.
  • retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
  • get_referral – Boolean for whether to retrieve referral whois information, if available.
  • extra_blacklist – A list of blacklisted whois servers in addition to the global BLACKLIST.
  • ignore_referral_errors – Boolean for whether to ignore and continue when an exception is encountered on referral whois lookups.
Returns:

query:The IP address (String)
asn:The Autonomous System Number (String)
asn_date:The ASN Allocation date (String)
asn_registry:The assigned ASN registry (String)
asn_cidr:The assigned ASN CIDR (String)
asn_country_code:
 The assigned ASN country code (String)
nets:Dictionaries containing network information which consists of the fields listed in the NIC_WHOIS dictionary. (List)
raw:Raw whois results if the inc_raw parameter is True. (String)
referral:Dictionary of referral whois information if get_referral is True and the server isn’t blacklisted. Consists of fields listed in the RWHOIS dictionary. Additional referral server informaion is added in the server and port keys. (Dictionary)
raw_referral:Raw referral whois results if the inc_raw parameter is True. (String)

Return type:

Dictionary

lookup_rws(inc_raw=False, retry_count=3)[source]

The function for retrieving and parsing whois information for an IP address via HTTP (Whois-RWS).

This should be faster than IPWhois.lookup(), but may not be as reliable. AFRINIC does not have a Whois-RWS service yet. We have to rely on the Ripe RWS service, which does not contain all of the data we need. LACNIC RWS is in beta.

Parameters:
  • inc_raw – Boolean for whether to include the raw whois results in the returned dictionary.
  • retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
Returns:

query:The IP address (String)
asn:The Autonomous System Number (String)
asn_date:The ASN Allocation date (String)
asn_registry:The assigned ASN registry (String)
asn_cidr:The assigned ASN CIDR (String)
asn_country_code:
 The assigned ASN country code (String)
nets:Dictionaries containing network information which consists of the fields listed in the NIC_WHOIS dictionary. (List)
raw:(Dictionary) - Whois results in Json format if the inc_raw parameter is True.

Return type:

Dictionary

exception ipwhois.ipwhois.WhoisLookupError[source]

An Exception for when the whois lookup failed.

ipwhois.utils.get_countries(is_legacy_xml=False)[source]

The function to generate a dictionary containing ISO_3166-1 country codes to names.

Parameters:is_legacy_xml – Boolean for whether to use the older country code list (iso_3166-1_list_en.xml).
Returns:A dictionary with the country codes as the keys and the country names as the values.
Return type:Dictionary
ipwhois.utils.ipv4_is_defined(address)[source]

The function for checking if an IPv4 address is defined (does not need to be resolved).

Parameters:address – An IPv4 address in string format.
Returns:
Boolean:True if given address is defined, otherwise False
String:IETF assignment name if given address is defined, otherwise ‘’
String:IETF assignment RFC if given address is defined, otherwise ‘’
Return type:Tuple
ipwhois.utils.ipv6_is_defined(address)[source]

The function for checking if an IPv6 address is defined (does not need to be resolved).

Parameters:address – An IPv6 address in string format.
Returns:
Boolean:True if address is defined, otherwise False
String:IETF assignment name if address is defined, otherwise ‘’
String:IETF assignment RFC if address is defined, otherwise ‘’
Return type:Tuple
ipwhois.utils.unique_addresses(data=None, file_path=None)[source]

The function to search an input string and/or file, extracting and counting IPv4/IPv6 addresses/networks. Summarizes ports with sub-counts. If both a string and file_path are provided, it will process them both.

Parameters:
  • data – A string to process.
  • file_path – An optional file path to process.
Returns:

ip address/network:
 

Each address or network found is a dictionary containing:

count:Total number of times seen (Integer)
ports:Dictionary with port numbers as keys and the number of times seen for this ip as values (Dictionary)

Return type:

Dictionary

Raises:

ValueError – Arguments provided are invalid.

ipwhois.utils.unique_everseen(iterable, key=None)[source]

The generator to list unique elements, preserving the order. Remember all elements ever seen. This was taken from the itertools recipes.

Parameters:
  • iterable – An iterable to process.
  • key – Optional function to run when checking elements (e.g., str.lower)
Returns:

Yields a generator object.

Return type:

Generator