Lookup

Problematic

How can we look for information about a given subject ?

Documentation

The tool to check the availability or syntax of domain, IP 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:

Copyright 2017, 2018, 2019, 2020 Nissar Chababy

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

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__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.
_get_server_and_port_from(inputed_dns)[source]

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
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(max_retries=None)[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.3.2/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.