Lookup

Problematic

How can we look for information about a given subject ?

Documentation

The tool to check the availability or syntax of domains, IPv4, IPv6 or URL.

██████╗ ██╗   ██╗███████╗██╗   ██╗███╗   ██╗ ██████╗███████╗██████╗ ██╗     ███████╗
██╔══██╗╚██╗ ██╔╝██╔════╝██║   ██║████╗  ██║██╔════╝██╔════╝██╔══██╗██║     ██╔════╝
██████╔╝ ╚████╔╝ █████╗  ██║   ██║██╔██╗ ██║██║     █████╗  ██████╔╝██║     █████╗
██╔═══╝   ╚██╔╝  ██╔══╝  ██║   ██║██║╚██╗██║██║     ██╔══╝  ██╔══██╗██║     ██╔══╝
██║        ██║   ██║     ╚██████╔╝██║ ╚████║╚██████╗███████╗██████╔╝███████╗███████╗
╚═╝        ╚═╝   ╚═╝      ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚══════╝╚═════╝ ╚══════╝╚══════╝

Provides the lookup interfaces.

Author:
Nissar Chababy, @funilrys, contactTATAfunilrysTODTODcom
Special thanks:
https://pyfunceble.github.io/special-thanks.html
Contributors:
https://pyfunceble.github.io/contributors.html
Project link:
https://github.com/funilrys/PyFunceble
Project documentation:
https://pyfunceble.readthedocs.io/en/master/
Project homepage:
https://pyfunceble.github.io/

License:

MIT License

Copyright (c) 2017, 2018, 2019, 2020 Nissar Chababy

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

DNSLookup()

class PyFunceble.lookup.dns.DNSLookup(dns_server=None, lifetime=3, tcp=False)[source]

DNS lookup interface.

Parameters:
  • subject (str) – The subject we are working with.
  • dns_server (list|tuple|str) – The DNS server we are working with.
  • lifetime (int) – Set the lifetime of a query.
_DNSLookup__get_dns_servers_from(inputed_dns)

Given a list or an input representing dns servers, we ensure that we have a list of a string which represent an IP.

Parameters:input (str, list, tuple) – The inputed DNS server(s).
Returns:The list of dns server to use.
Return type:list
classmethod _DNSLookup__get_resolver(dns_server)

Provides the configured dns resolver.

_DNSLookup__get_server_and_port_from(inputed_dns)

Given a list or an input representing dns server, we split the server from the port.

Parameters:inputed_dns – The inputed DNS server(s).
Returns:A tuple with:

(The DNS, the port)
Return type:tuple
_DNSLookup__request_complete_not_ip(subject, tcp=None)

Requests and provides the complete DNS spectrum.

Return type:dict
_DNSLookup__request_ip(subject, tcp=None)

Handle the request for a subject which is an IP.

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Return type:

dict
Raises:

ValueError – When a non string subject is given.
_DNSLookup__request_not_ip(subject, complete=False, tcp=None)

Handle the request for a subject which is not an IP.

Return type:dict
Raises:ValueError – When a non string subject is given.
a_record(subject, tcp=None)[source]

Return the A record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of A record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
aaaa_record(subject, tcp=None)[source]

Return the AAAA record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of A record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
cname_record(subject, tcp=None)[source]

Return the CNAME record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of CNAME record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
dname_record(subject, tcp=None)[source]

Return the DNAME record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of DNAME record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
classmethod get_addr_info(subject)[source]

Get and return the information of the given subject (address).

Parameters:subject (str) – The subject we are working with.
Returns:A list of address.
Return type:list, None
Raises:ValueError – When a non string subject is given.
classmethod get_host_by_addr(subject)[source]

Get and return the host of the given subject (address).

Parameters:subject (str) – The subject we are working with.
Returns:A dict in the following format or None.
{
    "hostname": "",
    "aliases": [],
    "ips": []
}
Return type:dict, None
Raises:ValueError – When a non string subject is given.
classmethod is_record_present_in_result(to_check, result, allow_empty=False)[source]

Checks if the given record type is in the result.

Parameters:
  • to_check (list, str, tuple) – The record to check the presence.
  • result (dict) – The result to work with.
  • allow_empty (bool) – Tell to if we allow and empty result as present.
Return type:

bool
mx_record(subject, tcp=None)[source]

Return the MX record of the given subject (if found).

Parameters:subject (str) – The subject we are working with.
Returns:A list of MX record(s).
Return type:list, None
Raises:ValueError – When a non string subject is given.
ns_record(subject, tcp=None)[source]

Return the NS record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of NS record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
ptr_record(subject, reverse_name=True, tcp=None)[source]

Return the PTR record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of PTR record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
request(subject, complete=False, tcp=None)[source]

Perform a DNS lookup/requests.

Parameters:
  • subject (str) – The subject we are working with.
  • complete (bool) – Tell us to return as many result as possible.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A dict with following index if the given subject is not registered into the given DNS server. (More likely local subjects).

{
    "hostname": "",
    "aliases": [],
    "ips": []
}

A dict with following index for everything else (and if found).

{
    "nameservers: [],
    "A": [],
    "AAAA": [],
    "CNAME": [],
    "DNAME": [],
    "MX": [],
    "NS": [],
    "TXT": [],
    "PTR": []
}

Return type:

dict
Raises:

ValueError – When a non string subject is given.
txt_record(subject, tcp=None)[source]

Return the TXT record of the given subject (if found).

Parameters:
  • subject (str) – The subject we are working with.
  • tcp (bool) – Tell us to use TCP for query.
Returns:

A list of TXT record(s).
Return type:

list, None
Raises:

ValueError – When a non string subject is given.
update_lifetime(lifetime)[source]

Updates the lifetime of a query.

update_nameserver(nameserver)[source]

Updates the nameserver to query.

HTTPCode()

class PyFunceble.lookup.http_code.HTTPCode(subject, subject_type)[source]

Get and return the HTTP code status of a given domain.

Parameters:
  • subject (str) – The subject we are working with.
  • _type (subject) –

    The type of the subject we are working with. Should be one of the following.

    • url
    • domain
    • file_url
    • file_domain
    • ipv6
_get_it()[source]

Get the HTTP code status.

Returns:The matched HTTP status code.
Return type:int|None
get()[source]

Return the HTTP code status.

Returns:The matched and formatted status code.
Return type:str|int|None

Iana()

class PyFunceble.lookup.iana.Iana[source]

Let us interact with the IANA database.

_Iana__get_content()

Provides the content of our IANA database.

PublicSuffix()

class PyFunceble.lookup.publicsuffix.PublicSuffix[source]

Let us interact with the public suffix database.

_PublicSuffix__get_content()

Provides the content of our PSL database.

Referer()

class PyFunceble.lookup.referer.Referer(subject)[source]

Get the WHOIS server (referer) of the current domain extension according to the IANA database.

Parameters:subject (str) – The subject we are working with.
get()[source]

Return the referer aka the WHOIS server of the current domain extension.

Returns:
  • [0] None if there is no referer.
  • [0] False if the extension is unknown which implicitly means
    that the subject is INVALID
  • [0] str The resolved IP to use.
  • [1] str, None the domain referer.
Return type:tuple

HostSSLAdapter()

class PyFunceble.lookup.requests.HostSSLAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)[source]

Extends the build-in HTTP Adapter for urllib3 for our needs.

_HostSSLAdapter__resolve_with_cache(hostname)

Resolve the IP of the given hostname.

Parameters:hostname (str) – The hostname to resolve.
Returns:The IP of the host name or the hostname itself.
Return type:None, str
classmethod resolve(hostname)[source]

Resolve the IP of the given hostname.

Parameters:hostname (str) – The hostname to resolve.
Returns:The IP of the host name or the hostname itself.
Return type:None, str
send(request, **kwargs)[source]

Overwrite the upstream :code:send` method.

We basically do the same. We only ensure that we request the IP from the chosen DNS record.

Parameters:
  • request – The PreparedRequest being sent.
  • stream – (optional) Whether to stream the request content.
  • timeout (float or tuple or urllib3 Timeout object) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
  • verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use
  • cert – (optional) Any user-provided SSL certificate to be trusted.
  • proxies – (optional) The proxies dictionary to apply to the request.
Return type:

requests.Response

HostAdapter()

class PyFunceble.lookup.requests.HostAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)[source]

Extends the build-in HTTP Adapter for urllib3 for our needs.

_HostAdapter__resolve_with_cache(hostname)

Resolve the IP of the given hostname.

Parameters:hostname (str) – The hostname to resolve.
Returns:The IP of the host name or the hostname itself.
Return type:None, str
send(request, **kwargs)[source]

Overwrite the upstream :code:send` method.

We basically do the same. We only ensure that we request the IP from the chosen DNS record.

Parameters:
  • request – The PreparedRequest being sent.
  • stream – (optional) Whether to stream the request content.
  • timeout (float or tuple or urllib3 Timeout object) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
  • verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use.
  • cert – (optional) Any user-provided SSL certificate to be trusted.
  • proxies – (optional) The proxies dictionary to apply to the request.
Return type:

requests.Response

IPv4Reputation

class PyFunceble.lookup.ipv4_reputation.IPv4Reputation[source]

Let us checks a given IPv4 against the IPv4 reputation file.

_IPv4Reputation__is_present(subject)

Checks the given subject against the input file.

Requests()

class PyFunceble.lookup.requests.Requests[source]

Handles all usage of requests.

Parameters:url (str) – The URL to work with.
delete(url, **kwargs)[source]

Sends a DELETE request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response
exceptions = <module 'requests.exceptions' from '/home/docs/checkouts/readthedocs.org/user_builds/pyfunceble/envs/3.0.0/lib/python3.7/site-packages/requests/exceptions.py'>
get(url, **kwargs)[source]

Sends a GET request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response
head(url, **kwargs)[source]

Sends a HEAD request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response
options(url, **kwargs)[source]

Sends a OPTIONS request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response
patch(url, **kwargs)[source]

Sends a PATCH request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response
post(url, **kwargs)[source]

Sends a POST request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response
put(url, **kwargs)[source]

Sends a PUT request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • kwargs – Optional arguments that request takes.
Return type:

requests.Response

WhoisLookup()

class PyFunceble.lookup.whois.WhoisLookup(subject, server=None, timeout=3)[source]

Implementation of the UNIX whois command.

Parameters:
  • subject (str) – The subject we are working with.
  • server (str) –

    The WHOIS server we are working with.

    Note

    If None is given, we look for the best one.

  • timeout (int) –

    The timeout to apply.

    Warning

    The timeout must be a modulo of 3.
request()[source]

Perform the WHOIS request.