API Documentation

Enpoints

Note

This section document what you can call directly when you use PyFunceble as an imported module.

The tool to check the availability or syntax of domain, IP or URL.

██████╗ ██╗   ██╗███████╗██╗   ██╗███╗   ██╗ ██████╗███████╗██████╗ ██╗     ███████╗
██╔══██╗╚██╗ ██╔╝██╔════╝██║   ██║████╗  ██║██╔════╝██╔════╝██╔══██╗██║     ██╔════╝
██████╔╝ ╚████╔╝ █████╗  ██║   ██║██╔██╗ ██║██║     █████╗  ██████╔╝██║     █████╗
██╔═══╝   ╚██╔╝  ██╔══╝  ██║   ██║██║╚██╗██║██║     ██╔══╝  ██╔══██╗██║     ██╔══╝
██║        ██║   ██║     ╚██████╔╝██║ ╚████║╚██████╗███████╗██████╔╝███████╗███████╗
╚═╝        ╚═╝   ╚═╝      ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝╚══════╝╚═════╝ ╚══════╝╚══════╝
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, 2021 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.
PyFunceble.dns_lookup(subject, dns_server=None, complete=False, lifetime=3)[source]

Make a DNS lookup of the given subject.

Parameters:
  • subject (str) – The subject we are working with.
  • dns_server (str|int) – A (or list of) DNS server to use while resolving.
  • complete (bool) – Tell us to look for everything instead of NS only.
  • lifetime (int) – The query lifetime.
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).

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

Return type:

dict

PyFunceble.get_complements(subject, include_given=False)[source]

Provides the complements of the given subject(s).

A complement is for example example.com if www.example.com is given and vice-versa.

Parameters:
  • subject (str, list) – The subject to get the complement for.
  • include_given (bool) – Tell us to add the given one into the result.
Return type:

list

PyFunceble.ipv4_syntax_check(ip)[source]

Check the syntax of the given IPv4.

Parameters:ip (str|list) – The IPv4 to check the syntax for.
Returns:The syntax validity.
Return type:bool|dict

Warning

This method will be deprecated one day in the future.

Please report to is_ipv4().

PyFunceble.is_domain(subject)[source]

Check if the given subject is a syntactically valid domain.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict
PyFunceble.is_domain_malicious(subject)[source]

Checks if the given domain is malicious.

Parameters:subject (str) – The subject to work with.
Return type:bool
PyFunceble.is_ip(subject)[source]

Checks if the given subject is a syntactivally valid IPv4 or IPv6.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict
PyFunceble.is_ip_range(subject)[source]

Check if the given subject is a syntactically valid IPv4 or IPv6 range.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The IPv4 range state.
Return type:bool|dict
PyFunceble.is_ipv4(subject)[source]

Check if the given subject is a syntactically valid IPv4.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict
PyFunceble.is_ipv4_malicious(subject)[source]

Checks if the given IPv4 is malicious.

Return type:bool
PyFunceble.is_ipv4_range(subject)[source]

Check if the given subject is a syntactically valid IPv4 range.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The IPv4 range state.
Return type:bool|dict
PyFunceble.is_ipv6(subject)[source]

Checks if the given subject is syntactivally valid IPv6.

Parameters:subject (str, list) – The subject to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict
PyFunceble.is_subdomain(subject)[source]

Check if the given subject is a syntactically valid subdomain.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict
PyFunceble.is_url(subject)[source]

Check if the given subject is a syntactically valid URL.

Parameters:subject (str|list) – The subject to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict
PyFunceble.is_url_malicious(subject)[source]

Checks if the given URL is malicious.

Parameters:subject (str) – The subject to work with.
Return type:bool
PyFunceble.load_config(generate_directory_structure=False, custom=None, sanity_check=False)[source]

Load the configuration.

Parameters:
  • generate_directory_structure (bool) – Tell us if we generate the directory structure along with loading the configuration file.
  • custom (dict) – A dict with the configuration index (from .PyFunceble.yaml) to update.
  • sanity_check (bool) – Tell us to run the safety check of the configuration.

Note

If config is given, the given dict overwrite the last value of the given indexes in the configuration.

It’s actually something like following:

pyfunceble.configuration.update(config_given_by_user)
PyFunceble.syntax_check(domain)[source]

Check the syntax of the given domain.

Parameters:domain (str|list) – The domain to check the syntax from.
Returns:The syntax validity.
Return type:bool|dict

Warning

This method will be deprecated one day in the future.

Please report to is_domain().

PyFunceble.test(subject, complete=False, config=None)[source]

Test the availability of the given subject (domain or IP).

Parameters:
  • subject (str|list) – The subject (IP or domain) to test.
  • complete (bool) – Activate the return of a dict with some significant data from the test.
  • config (dict) – A dict with the configuration index (from .PyFunceble.yaml) to update.
Returns:

The status or the informations of the domain.

Return type:

str|dict

Note

If config is given, the given dict overwrite the last value of the given indexes in the configuration.

It’s actually something like following:

pyfunceble.configuration.update(config_given_by_user)

Note

If complete is set to True, we return the following indexes.

{
    "_status_source": None,
    "_status": None,
    "dns_lookup": [],
    "domain_syntax_validation": None,
    "expiration_date": None,
    "given": None,
    "http_status_code": None,
    "ipv4_range_syntax_validation": None,
    "ipv4_syntax_validation": None,
    "ipv6_range_syntax_validation": None,
    "ipv6_syntax_validation": None,
    "status": None,
    "status_source": None,
    "subdomain_syntax_validation": None,
    "tested": None,
    "url_syntax_validation": None,
    "whois_record": None,
    "whois_server": None,
}
PyFunceble.url_syntax_check(url)[source]

Check the syntax of the given URL.

Parameters:url (str|list) – The URL to check the syntax for.
Returns:The syntax validity.
Return type:bool|dict

Warning

This method will be deprecated one day in the future.

Please report to is_url().

PyFunceble.url_test(subject, complete=False, config=None)[source]

Test the availability of the given subject (URL).

Parameters:
  • subject (str|list) – The subject (URL) to test.
  • complete (bool) – Activate the return of a dict with some significant data from the test.
  • config (dict) – A dict with the configuration index (from .PyFunceble.yaml) to update.
Returns:

The status or the informations of the URL.

Return type:

str|dict

Note

If config is given, the given dict overwrite the last value of the given indexes in the configuration.

It’s actually something like following:

pyfunceble.configuration.update(config_given_by_user)

Note

If complete is set to True, we return the following indexes.

{
    "_status_source": None,
    "_status": None,
    "dns_lookup": [],
    "domain_syntax_validation": None,
    "expiration_date": None,
    "given": None,
    "http_status_code": None,
    "ipv4_range_syntax_validation": None,
    "ipv4_syntax_validation": None,
    "ipv6_range_syntax_validation": None,
    "ipv6_syntax_validation": None,
    "status": None,
    "status_source": None,
    "subdomain_syntax_validation": None,
    "tested": None,
    "url_syntax_validation": None,
    "whois_record": None,
    "whois_server": None,
}
PyFunceble.whois(subject, server=None, timeout=3)[source]

Request the WHOIS record of the given subject.

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

    The WHOIS server to communicate with.

    Note

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

  • timeout (int) – The timeout to apply to the request.
Returns:

None or the WHOIS record.

Return type:

None|str

File generation while using the API

You may want to test using the API but still want the result structured normally like a CLI usage. For that case simply add the following.

Global configuration load

import PyFunceble

OUR_CUSTOM_PYFUNCEBLE_CONFIGURATION = {"api_file_generation": True}

PyFunceble.load_config(
    generate_directory_structure=True, custom=OUR_CUSTOM_PYFUNCEBLE_CONFIGURATION
)

# The output directory is then generated, and the file(s) too.

# You logic or whatever you want.

Local configuration load

import PyFunceble

OUR_CUSTOM_PYFUNCEBLE_CONFIGURATION = {"api_file_generation": True}

print(
    "google.com is "
    f"{PyFunceble.test('google.com', config=OUR_CUSTOM_PYFUNCEBLE_CONFIGURATION)}"
)

# The output directory is then generated, and the file(s) too.