Library Structure¶
-
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.
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: ASNRegistryError
– The ASN registry is not known.ASNLookupError
– The ASN lookup failed.
-
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: ASNRegistryError
– The ASN registry is not known.ASNLookupError
– The ASN lookup failed.
-
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: BlacklistError
– Raised if the whois server provided is in the global BLACKLIST or extra_blacklist.WhoisLookupError
– The whois lookup failed.
-
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
-
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