Library Structure

class ipwhois.ipwhois.IPWhois(address, timeout=5, proxy_opener=None, allow_permutations=True)

The wrapper class for performing whois/RDAP 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.
• allow_permutations – allow net.Net() to use additional methods if DNS lookups to Cymru fail.

lookup(*args, **kwargs)

Temporary wrapper for legacy whois lookups (moved to IPWhois.lookup_whois()). This will be removed in a future release (1.0.0).

lookup_rdap(inc_raw=False, retry_count=3, depth=0, excluded_entities=None, bootstrap=False, rate_limit_timeout=120, asn_alts=None, extra_org_map=None, inc_nir=True, nir_field_list=None)

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

This is now the recommended method, as RDAP contains much better information to parse.

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.
• depth – How many levels deep to run queries when additional referenced objects are found.
• excluded_entities – A list of entity handles to not perform lookups.
• bootstrap – If True, performs lookups via ARIN bootstrap rather than lookups based on ASN data. ASN lookups are not performed and no output for any of the asn* fields is provided.
• rate_limit_timeout – The number of seconds to wait before retrying when a rate limit notice is returned via rdap+json.
• asn_alts – Array of additional lookup types to attempt if the ASN dns lookup fails. Allow permutations must be enabled. Defaults to all [‘whois’, ‘http’].
• extra_org_map – Dictionary mapping org handles to RIRs. This is for limited cases where ARIN REST (ASN fallback HTTP lookup) does not show an RIR as the org handle e.g., DNIC (which is now the built in ORG_MAP) e.g., {‘DNIC’: ‘arin’}. Valid RIR values are (note the case-sensitive - this is meant to match the REST result): ‘ARIN’, ‘RIPE’, ‘apnic’, ‘lacnic’, ‘afrinic’
• inc_nir – Boolean for whether to retrieve NIR (National Internet Registry) information, if registry is JPNIC (Japan) or KRNIC (Korea). If True, extra network requests will be required. If False, the information returned for JP or KR IPs is severely restricted.
• nir_field_list – If provided and inc_nir, a list of fields to parse: [‘name’, ‘handle’, ‘country’, ‘address’, ‘postal_code’, ‘nameservers’, ‘created’, ‘updated’, ‘contacts’]

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) entities:List of entity handles referred by the top level query. network:Dictionary containing network information which consists of the fields listed in the ipwhois.rdap._RDAPNetwork dict. objects:Dictionary of (entity handle: entity dict) which consists of the fields listed in the ipwhois.rdap._RDAPEntity dict. raw:(Dictionary) - Whois results in json format if the inc_raw parameter is True. nir:(Dictionary) - nir.NIRWhois() results if inc_nir is True.

Return type:

Dictionary

lookup_whois(inc_raw=False, retry_count=3, get_referral=False, extra_blacklist=None, ignore_referral_errors=False, field_list=None, asn_alts=None, extra_org_map=None, inc_nir=True, nir_field_list=None)

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.
• field_list – If provided, a list of fields to parse: [‘name’, ‘handle’, ‘description’, ‘country’, ‘state’, ‘city’, ‘address’, ‘postal_code’, ‘emails’, ‘created’, ‘updated’]
• asn_alts – Array of additional lookup types to attempt if the ASN dns lookup fails. Allow permutations must be enabled. Defaults to all [‘whois’, ‘http’].
• extra_org_map – Dictionary mapping org handles to RIRs. This is for limited cases where ARIN REST (ASN fallback HTTP lookup) does not show an RIR as the org handle e.g., DNIC (which is now the built in ORG_MAP) e.g., {‘DNIC’: ‘arin’}. Valid RIR values are (note the case-sensitive - this is meant to match the REST result): ‘ARIN’, ‘RIPE’, ‘apnic’, ‘lacnic’, ‘afrinic’
• inc_nir – Boolean for whether to retrieve NIR (National Internet Registry) information, if registry is JPNIC (Japan) or KRNIC (Korea). If True, extra network requests will be required. If False, the information returned for JP or KR IPs is severely restricted.
• nir_field_list – If provided and inc_nir, a list of fields to parse: [‘name’, ‘handle’, ‘country’, ‘address’, ‘postal_code’, ‘nameservers’, ‘created’, ‘updated’, ‘contacts’]

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 ipwhois.whois.RIR_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 ipwhois.whois.RWHOIS dictionary. raw_referral:Raw referral whois results if the inc_raw parameter is True. (String) nir:(Dictionary) - nir.NIRWhois() results if inc_nir is True.

Return type:

Dictionary

class ipwhois.net.Net(address, timeout=5, proxy_opener=None, allow_permutations=True)

The class for performing network queries.

Parameters:

• address – An IPv4 or IPv6 address in string format.
• timeout – The default timeout for socket connections in seconds.
• proxy_opener – The urllib.request.OpenerDirector request for proxy support or None.
• allow_permutations – Use additional methods if DNS lookups to Cymru fail.

Raises:

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

get_asn_dns()

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

Returns:The raw ASN data. Return type:String Raises:ASNLookupError – The ASN lookup failed.

get_asn_http(retry_count=3)

The function for retrieving ASN information for an IP address from Arin via port 80 (HTTP). Currently limited to fetching asn_registry through a Arin whois (REST) lookup. The other values are returned as None to keep a consistent dict output. This should be used as a last chance fallback call behind ASN DNS & ASN Whois lookups.

Parameters:retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered. Returns:The ASN data in json format. Return type:Dictionary Raises:ASNLookupError – The ASN lookup failed.

get_asn_origin_whois(asn_registry='radb', asn=None, retry_count=3, server=None, port=43)

The function for retrieving CIDR info for an ASN via whois.

Parameters:

• asn_registry – The source to run the query against (asn.ASN_ORIGIN_WHOIS).
• asn – The ASN string (required).
• 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. Defaults to RADB.
• port – The network port to connect on.

Returns:

The raw ASN origin whois data.

Return type:

String

Raises:

• WhoisLookupError – The ASN origin whois lookup failed.
• WhoisRateLimitError – The ASN origin Whois request rate limited and retries were exhausted.

get_asn_whois(retry_count=3)

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

Parameters:retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered. Returns:The raw ASN data. Return type:String Raises:ASNLookupError – The ASN lookup failed.

get_host(retry_count=3)

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_http_json(url=None, retry_count=3, rate_limit_timeout=120, headers=None)

The function for retrieving a json result via HTTP.

Parameters:

• url – The URL to retrieve.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• rate_limit_timeout – The number of seconds to wait before retrying when a rate limit notice is returned via rdap+json.
• headers – The HTTP headers dictionary. The Accept header defaults to ‘application/rdap+json’.

Returns:

The data in json format.

Return type:

Dictionary

Raises:

• HTTPLookupError – The HTTP lookup failed.
• HTTPRateLimitError – The HTTP request rate limited and retries were exhausted.

get_http_raw(url=None, retry_count=3, headers=None, request_type='GET', form_data=None)

The function for retrieving a raw HTML result via HTTP.

Parameters:

• url – The URL to retrieve.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• headers – The HTTP headers dictionary. The Accept header defaults to ‘text/html’.
• request_type – ‘GET’ or ‘POST’
• form_data – Dictionary of form POST data

Returns:

The raw data.

Return type:

String

Raises:

HTTPLookupError – The HTTP lookup failed.

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

The function for retrieving whois or rwhois information for an IP address via any port. Defaults to port 43/tcp (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.
• WhoisRateLimitError – The Whois request rate limited and retries were exhausted.

lookup_asn(*args, **kwargs)

Temporary wrapper for IP ASN lookups (moved to asn.IPASN.lookup()). This will be removed in a future release (1.0.0).

class ipwhois.rdap.RDAP(net)

The class for parsing IP address whois information via RDAP: https://tools.ietf.org/html/rfc7483 https://www.arin.net/resources/rdap.html

Parameters:

net – A ipwhois.net.Net object.

Raises:

• NetError – The parameter provided is not an instance of ipwhois.net.Net
• IPDefinedError – The address provided is defined (does not need to be resolved).

lookup(inc_raw=False, retry_count=3, asn_data=None, depth=0, excluded_entities=None, response=None, bootstrap=False, rate_limit_timeout=120)

The function for retrieving and parsing information for an IP address via RDAP (HTTP).

Parameters:

• inc_raw – Boolean for whether to include the raw results in the returned dictionary.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• asn_data – Result dictionary from ipwhois.asn.IPASN.lookup(). Optional if the bootstrap parameter is True.
• depth – How many levels deep to run queries when additional referenced objects are found.
• excluded_entities – A list of entity handles to not perform lookups.
• response – Optional response object, this bypasses the RDAP lookup.
• bootstrap – If True, performs lookups via ARIN bootstrap rather than lookups based on ASN data.
• rate_limit_timeout – The number of seconds to wait before retrying when a rate limit notice is returned via rdap+json.

Returns:

query:The IP address (String) network:Dictionary of values returned by _RDAPNetwork. The raw result is included for each entity if the inc_raw parameter is True. entities:List of entity keys referenced by the top level IP address query. objects:Dictionary of objects with the handles as keys, and the dictionary returned by _RDAPEntity, etc as the values. The raw result is included for each object if the inc_raw parameter is True.

Return type:

Dictionary

class ipwhois.rdap._RDAPCommon(json_result)

The common class for parsing RDAP objects: https://tools.ietf.org/html/rfc7483#section-5

Parameters:json_result – The JSON response from an RDAP query. Raises:ValueError – vcard is not a known RDAP object.

_parse()

The function for parsing the JSON response to the vars dictionary.

summarize_events(events_json)

The function for summarizing RDAP events in to a unique list. https://tools.ietf.org/html/rfc7483#section-4.5

Parameters:events_json – A json dictionary of events from RDAP results. Returns:A unique list of found RDAP events dictionaries. Return type:List

summarize_links(links_json)

The function for summarizing RDAP links in to a unique list. https://tools.ietf.org/html/rfc7483#section-4.2

Parameters:links_json – A json dictionary of links from RDAP results. Returns:A unique list of found RDAP link dictionaries. Return type:List

summarize_notices(notices_json)

The function for summarizing RDAP notices in to a unique list. https://tools.ietf.org/html/rfc7483#section-4.3

Parameters:notices_json – A json dictionary of notices from RDAP results. Returns:A unique list of found RDAP notices dictionaries. Return type:List

class ipwhois.rdap._RDAPContact(vcard)

The class for parsing RDAP entity contact information objects: https://tools.ietf.org/html/rfc7483#section-5.1 https://tools.ietf.org/html/rfc7095

Parameters:vcard – The vcard list from an RDAP IP address query. Raises:InvalidEntityContactObject – vcard is not an RDAP entity contact information object.

_parse_address(val)

The function for parsing the vcard address.

Parameters:val – The value to parse.

_parse_email(val)

The function for parsing the vcard email addresses.

Parameters:val – The value to parse.

_parse_kind(val)

The function for parsing the vcard kind.

Parameters:val – The value to parse.

_parse_name(val)

The function for parsing the vcard name.

Parameters:val – The value to parse.

_parse_phone(val)

The function for parsing the vcard phone numbers.

Parameters:val – The value to parse.

_parse_role(val)

The function for parsing the vcard role.

Parameters:val – The value to parse.

_parse_title(val)

The function for parsing the vcard title.

Parameters:val – The value to parse.

parse()

The function for parsing the vcard to the vars dictionary.

class ipwhois.rdap._RDAPEntity(json_result)

The class for parsing RDAP entity objects: https://tools.ietf.org/html/rfc7483#section-5.1

Parameters:json_result – The JSON response from an RDAP query. Raises:InvalidEntityObject – json_result is not an RDAP entity object.

parse()

The function for parsing the JSON response to the vars dictionary.

class ipwhois.rdap._RDAPNetwork(json_result)

The class for parsing RDAP network objects: https://tools.ietf.org/html/rfc7483#section-5.4

Parameters:json_result – The JSON response from an RDAP IP address query. Raises:InvalidNetworkObject – json_result is not an RDAP network object.

parse()

The function for parsing the JSON response to the vars dictionary.

class ipwhois.whois.Whois(net)

The class for parsing via whois

Parameters:

net – A ipwhois.net.Net object.

Raises:

• NetError – The parameter provided is not an instance of ipwhois.net.Net
• IPDefinedError – The address provided is defined (does not need to be resolved).

_get_nets_arin(response)

The function for parsing network blocks from ARIN whois data.

Parameters:response – The response from the ARIN whois server. Returns:A of dictionaries containing keys: cidr, start, end. Return type:List

_get_nets_lacnic(response)

The function for parsing network blocks from LACNIC whois data.

Parameters:response – The response from the LACNIC whois server. Returns:A of dictionaries containing keys: cidr, start, end. Return type:List

_get_nets_other(response)

The function for parsing network blocks from generic whois data.

Parameters:response – The response from the whois/rwhois server. Returns:A of dictionaries containing keys: cidr, start, end. Return type:List

_parse_fields(response, fields_dict, net_start=None, net_end=None, dt_format=None, field_list=None)

The function for parsing whois fields from a data input.

Parameters:

• response – The response from the whois/rwhois server.
• fields_dict – The dictionary of fields -> regex search values.
• net_start – The starting point of the network (if parsing multiple networks).
• net_end – The ending point of the network (if parsing multiple networks).
• dt_format – The format of datetime fields if known.
• field_list – If provided, a list of fields to parse: [‘name’, ‘handle’, ‘description’, ‘country’, ‘state’, ‘city’, ‘address’, ‘postal_code’, ‘emails’, ‘created’, ‘updated’]

Returns:

A dictionary of fields provided in fields_dict.

Return type:

Dictionary

lookup(inc_raw=False, retry_count=3, response=None, get_referral=False, extra_blacklist=None, ignore_referral_errors=False, asn_data=None, field_list=None, is_offline=False)

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

Parameters:

• inc_raw – Boolean for whether to include the raw results in the returned dictionary.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• response – Optional response object, this bypasses the Whois lookup.
• 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.
• asn_data – Optional ASN result object, this bypasses the ASN lookup.
• field_list – If provided, a list of fields to parse: [‘name’, ‘handle’, ‘description’, ‘country’, ‘state’, ‘city’, ‘address’, ‘postal_code’, ‘emails’, ‘created’, ‘updated’]
• is_offline – Boolean for whether to perform lookups offline. If True, response and asn_data must be provided. Primarily used for testing.

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. raw_referral:Raw referral whois results if the inc_raw parameter is True. (String)

Return type:

Dictionary

class ipwhois.nir.NIRWhois(net)

The class for parsing whois data for NIRs (National Internet Registry). JPNIC and KRNIC are currently the only NIRs supported. Output varies based on NIR specific whois formatting.

Parameters:

net – A ipwhois.net.Net object.

Raises:

• NetError – The parameter provided is not an instance of ipwhois.net.Net
• IPDefinedError – The address provided is defined (does not need to be resolved).

_get_contact(response=None, nir=None, handle=None, retry_count=None, dt_format=None)

The function for retrieving and parsing NIR whois data based on NIR_WHOIS contact_fields.

Parameters:

• response – Optional response object, this bypasses the lookup.
• nir – The NIR to query (‘jpnic’ or ‘krnic’).
• handle – For NIRs that have seperate contact queries (JPNIC), this is the contact handle to use in the query.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• dt_format – The format of datetime fields if known.

Returns:

A dictionary of fields provided in contact_fields.

Return type:

Dictionary

_get_nets_jpnic(response)

The function for parsing network blocks from jpnic whois data.

Parameters:response – The response from the jpnic server. Returns:A of dictionaries containing keys: cidr, start, end. Return type:List

_get_nets_krnic(response)

The function for parsing network blocks from krnic whois data.

Parameters:response – The response from the krnic server. Returns:A of dictionaries containing keys: cidr, start, end. Return type:List

_parse_fields(response, fields_dict, net_start=None, net_end=None, dt_format=None, field_list=None, hourdelta=0, is_contact=False)

The function for parsing whois fields from a data input.

Parameters:

• response – The response from the whois/rwhois server.
• fields_dict – The dictionary of fields -> regex search values.
• net_start – The starting point of the network (if parsing multiple networks).
• net_end – The ending point of the network (if parsing multiple networks).
• dt_format – The format of datetime fields if known.
• field_list – If provided, a list of fields to parse: [‘name’, ‘handle’, ‘country’, ‘address’, ‘postal_code’, ‘nameservers’, ‘created’, ‘updated’, ‘contacts’]
• is_contact – If True, uses contact information field parsing.

Returns:

A dictionary of fields provided in fields_dict.

Return type:

Dictionary

lookup(nir=None, inc_raw=False, retry_count=3, response=None, field_list=None, is_offline=False)

The function for retrieving and parsing NIR whois information for an IP address via HTTP (HTML scraping).

Parameters:

• nir – The NIR to query (‘jpnic’ or ‘krnic’).
• inc_raw – Boolean for whether to include the raw results in the returned dictionary.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• response – Optional response object, this bypasses the NIR lookup. Required when is_offline=True.
• field_list – If provided, a list of fields to parse: [‘name’, ‘handle’, ‘country’, ‘address’, ‘postal_code’, ‘nameservers’, ‘created’, ‘updated’, ‘contacts’]
• is_offline – Boolean for whether to perform lookups offline. If True, response and asn_data must be provided. Primarily used for testing.

Returns:

query:The IP address (String) nets:List of dictionaries containing network information which consists of the fields listed in the NIR_WHOIS dictionary. raw:Raw NIR whois results if the inc_raw parameter is True. (String)

Return type:

Dictionary

class ipwhois.asn.ASNOrigin(net)

The class for parsing ASN origin whois data

Parameters:net – A ipwhois.net.Net object. Raises:NetError – The parameter provided is not an instance of ipwhois.net.Net

_get_nets_radb(response, is_http=False)

The function for parsing network blocks from ASN origin data.

Parameters:

• response – The response from the RADB whois/http server.
• is_http – If the query is RADB HTTP instead of whois, set to True.

Returns:

A of dictionaries containing keys: cidr, start, end.

Return type:

List

_parse_fields(response, fields_dict, net_start=None, net_end=None, field_list=None)

The function for parsing ASN whois fields from a data input.

Parameters:

• response – The response from the whois/rwhois server.
• fields_dict – The dictionary of fields -> regex search values.
• net_start – The starting point of the network (if parsing multiple networks).
• net_end – The ending point of the network (if parsing multiple networks).
• field_list – If provided, a list of fields to parse: [‘description’, ‘maintainer’, ‘updated’, ‘source’]

Returns:

A dictionary of fields provided in fields_dict.

Return type:

Dictionary

lookup(asn=None, inc_raw=False, retry_count=3, response=None, field_list=None, asn_alts=None)

The function for retrieving and parsing ASN origin whois information via port 43/tcp (WHOIS).

Parameters:

• asn – The ASN string (required).
• inc_raw – Boolean for whether to include the raw results in the returned dictionary.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• response – Optional response object, this bypasses the Whois lookup.
• field_list – If provided, a list of fields to parse: [‘description’, ‘maintainer’, ‘updated’, ‘source’]
• asn_alts – Array of additional lookup types to attempt if the ASN whois lookup fails. Defaults to all [‘http’].

Returns:

query:The Autonomous System Number (String) nets:Dictionaries containing network information which consists of the fields listed in the ASN_ORIGIN_WHOIS dictionary. (List) raw:Raw ASN origin whois results if the inc_raw parameter is True. (String)

Return type:

Dictionary

class ipwhois.asn.IPASN(net)

The class for parsing ASN data for an IP address.

Parameters:net – A ipwhois.net.Net object. Raises:NetError – The parameter provided is not an instance of ipwhois.net.Net

_parse_fields_dns(response)

The function for parsing ASN fields from a dns response.

Parameters:

response – The response from the ASN dns server.

Returns:

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)

Return type:

Dictionary

Raises:

• ASNRegistryError – The ASN registry is not known.
• ASNParseError – ASN parsing failed.

_parse_fields_http(response, extra_org_map=None)

The function for parsing ASN fields from a http response.

Parameters:

• response – The response from the ASN http server.
• extra_org_map – Dictionary mapping org handles to RIRs. This is for limited cases where ARIN REST (ASN fallback HTTP lookup) does not show an RIR as the org handle e.g., DNIC (which is now the built in ORG_MAP) e.g., {‘DNIC’: ‘arin’}. Valid RIR values are (note the case-sensitive - this is meant to match the REST result): ‘ARIN’, ‘RIPE’, ‘apnic’, ‘lacnic’, ‘afrinic’

Returns:

asn:None, can’t retrieve with this method. asn_date:None, can’t retrieve with this method. asn_registry:The assigned ASN registry (String) asn_cidr:None, can’t retrieve with this method. asn_country_code:  None, can’t retrieve with this method.

Return type:

Dictionary

Raises:

• ASNRegistryError – The ASN registry is not known.
• ASNParseError – ASN parsing failed.

_parse_fields_whois(response)

The function for parsing ASN fields from a whois response.

Parameters:

response – The response from the ASN whois server.

Returns:

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)

Return type:

Dictionary

Raises:

• ASNRegistryError – The ASN registry is not known.
• ASNParseError – ASN parsing failed.

lookup(inc_raw=False, retry_count=3, asn_alts=None, extra_org_map=None)

The wrapper function for retrieving and parsing ASN information for an IP address.

Parameters:

• inc_raw – Boolean for whether to include the raw results in the returned dictionary.
• retry_count – The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered.
• asn_alts – Array of additional lookup types to attempt if the ASN dns lookup fails. Allow permutations must be enabled. Defaults to all [‘whois’, ‘http’].
• extra_org_map – Dictionary mapping org handles to RIRs. This is for limited cases where ARIN REST (ASN fallback HTTP lookup) does not show an RIR as the org handle e.g., DNIC (which is now the built in ORG_MAP) e.g., {‘DNIC’: ‘arin’}. Valid RIR values are (note the case-sensitive - this is meant to match the REST result): ‘ARIN’, ‘RIPE’, ‘apnic’, ‘lacnic’, ‘afrinic’

Returns:

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) raw:Raw ASN results if the inc_raw parameter is True. (String)

Return type:

Dictionary

Raises:

• ASNRegistryError – ASN registry does not match.
• HTTPLookupError – The HTTP lookup failed.

ipwhois.utils.calculate_cidr(start_address, end_address)

The function to calculate a CIDR range(s) from a start and end IP address.

Parameters:

• start_address – The starting IP address in string format.
• end_address – The ending IP address in string format.

Returns:

A list of calculated CIDR ranges.

Return type:

List

ipwhois.utils.get_countries(is_legacy_xml=False)

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)

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.ipv4_lstrip_zeros(address)

The function to strip leading zeros in each octet of an IPv4 address.

Parameters:address – An IPv4 address in string format. Returns:The modified IPv4 address string. Return type:String

ipwhois.utils.ipv6_is_defined(address)

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)

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 w/:

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)

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

exception ipwhois.exceptions.ASNLookupError

An Exception for when the ASN lookup failed.

exception ipwhois.exceptions.ASNParseError

An Exception for when the ASN parsing failed.

exception ipwhois.exceptions.ASNRegistryError

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

exception ipwhois.exceptions.BlacklistError

An Exception for when the server is in a blacklist.

exception ipwhois.exceptions.HTTPLookupError

An Exception for when the RDAP lookup failed.

exception ipwhois.exceptions.HTTPRateLimitError

An Exception for when HTTP queries exceed the NIC’s request limit and have exhausted all retries.

exception ipwhois.exceptions.HostLookupError

An Exception for when the host lookup failed.

exception ipwhois.exceptions.IPDefinedError

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

exception ipwhois.exceptions.InvalidEntityContactObject

An Exception for when JSON output is not an RDAP entity contact information object: https://tools.ietf.org/html/rfc7483#section-5.4

exception ipwhois.exceptions.InvalidEntityObject

An Exception for when JSON output is not an RDAP entity object: https://tools.ietf.org/html/rfc7483#section-5.1

exception ipwhois.exceptions.InvalidNetworkObject

An Exception for when JSON output is not an RDAP network object: https://tools.ietf.org/html/rfc7483#section-5.4

exception ipwhois.exceptions.NetError

An Exception for when a parameter provided is not an instance of ipwhois.net.Net.

exception ipwhois.exceptions.WhoisLookupError

An Exception for when the whois lookup failed.

exception ipwhois.exceptions.WhoisRateLimitError

An Exception for when Whois queries exceed the NIC’s request limit and have exhausted all retries.