API Documentation

Checkers

As of PyFunceble 4.0.0, it is possible to use our checker without any configuration of initialization of any sort. Simply choose your checker, interact with it and get what you are looking for!

Getting started

Before starting to play with any checkers you need to understand 2 things:

The first one is the base of all checkers, and the second is the base of all status you get when you call the get_status() method.

Interaction with checkers

Note

This method is the same for all available checkers.

Let’s say we want to test the availability of github.com.

We first have to select and prepare the checker.

from PyFunceble import DomainAvailabilityChecker

# Here we take the default configuration.
checker = DomainAvailabilityChecker()

Then we just set the subject to work with.

checker.set_subject("github.com")

We can then get the status.

status = checker.get_status()

# Note: You can also do it in one shot.
status = checker.set_subject("github.com").get_status()

Once we have a status object, we can convert it to a different format.

# To dict.
status_dict = status.to_dict()

# To JSON.
status_json = status.to_json()

We can also interact with any of the attributes of the status object.

# This is the status.
print("GitHub is", status.status)

But finally, and probably most importantly, we can ask questions.

Warning

Each checker have their own set of methods. Be sure to read them or follow the autocomplete of your editor.

# Is it active ?
print("Is GitHub active ?", status.is_active())

# Is it inactive ?
print("Is GitHub inactive ?", status.is_inactive())

# Is it invalid ?
print("Is github.com invalid ?", status.is_invalid())

Available Checkers

In this section you can find the list of available checkers and how to import them.

Availability checkers

  • Domain:
    • PyFunceble.checker.availability.domain.DomainAvailabilityChecker

    or

    • from PyFunceble import DomainAvailabilityChecker

  • Domain and IP:
    • PyFunceble.checker.availability.domain_and_ip.DomainAndIPAvailabilityChecker

    or

    • from PyFunceble import DomainAndIPAvailabilityChecker

  • URL:
    • PyFunceble.checker.availability.url.URLAvailabilityChecker

    or

    • from PyFunceble import URLAvailabilityChecker

  • IP (v4 / v6):
    • PyFunceble.checker.availability.ip.IPAvailabilityChecker

    or

    • from PyFunceble import IPAvailabilityChecker

Syntax checkers

Reputation checkers

  • Domain:
    • PyFunceble.checker.reputation.domain.DomainReputationChecker

    or

    • from PyFunceble import DomainReputationChecker

  • Domain and IP:
    • PyFunceble.checker.reputation.domain_and_ip.DomainAndIPReputationChecker

    or

    • from PyFunceble import DomainAndIPReputationChecker

  • URL:
    • PyFunceble.checker.reputation.url.URLReputationChecker

    or

    • from PyFunceble import URLReputationChecker

  • IP (v4 / v6):
    • PyFunceble.checker.reputation.ip.IPReputationChecker

    or

    • from PyFunceble import IPReputationChecker

Endpoints

Note

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

Warning

Some of those methods may be deprecated and removed in the future (open for discussion).

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.

"""
This is an example which let us manipulate the data and also generate the files
as if it was the CLI.
"""

import copy

import colorama

import PyFunceble.facility
import PyFunceble.storage
from PyFunceble import DomainAvailabilityChecker
from PyFunceble.cli.filesystem.dir_structure.restore import (
    DirectoryStructureRestoration,
)
from PyFunceble.cli.processes.producer import ProducerProcessesManager
from PyFunceble.cli.utils import ascii_logo

# We initiate the coloration.
colorama.init(autoreset=True)


# We are in control, so we need to manually start the loading.
PyFunceble.facility.ConfigLoader.custom_config = {
    "cli_testing": {"file_generation": {"plain": True}, "display_mode": {"quiet": True, "color": True}}
}
PyFunceble.facility.ConfigLoader.start()

print(ascii_logo.get_home_representation())

# This is needed as our idea is to communicate with the producer process instead
# of trying to implement everything again.
# So, this describes the dataset as they are sent to the tester process
# (normally from the CLi).
STD_COMMUNICATION_DATASET = {
    "type": "single",
    "subject_type": "domain",
    # Destination inside the output directory.
    "destination": "my_awesome_pyfunceble_wrapper",
    "subject": None,
    "idna_subject": None,
    "source": "my_awesome_pyfunceble_wrapper",
    "output_dir": None,  # Will be handled automatically
    "checker_type": "AVAILABILITY",  # Must be one of our supported one!!
}

DOMAINS = ["github.com", "twitter.com"]

# In this example, we are cleaning up and regenerating the output directory
# at each run.
dir_structure_restoration = DirectoryStructureRestoration(
    parent_dirname=STD_COMMUNICATION_DATASET["destination"]
).restore_from_backup()

# We start the producer process.
producer_proc = ProducerProcessesManager()
# We start the process manager now that we are ready.
producer_proc.start()

# We start and configure our availability checker.
avail_checker = DomainAvailabilityChecker(use_whois_lookup=False)

for domain in DOMAINS:
    # We loop through our list of subject to test.

    # We parse the current subject to the availability checker.
    avail_checker.subject = domain

    # Now we fetch the status object.
    test_result = avail_checker.get_status()

    # We prepare our communication dataset.
    communication_dataset = copy.deepcopy(STD_COMMUNICATION_DATASET)
    communication_dataset["subject"] = test_result.subject
    communication_dataset["idna_subject"] = test_result.idna_subject

    # We print the result (for us as we call this script.)
    print(
        f"{test_result.idna_subject} (IDNA: {test_result.subject}) "
        f"is {test_result.status}"
    )

    # We order the generation of the status file by putting our information
    # to the producer queue.
    producer_proc.add_to_input_queue(
        (communication_dataset, test_result), worker_name="main"
    )

# We are now done, it's time to send the stop signal.
# The stop signal will inform the producer process that it needs to stop
# listening to new order (from the time it reads the stop signal).
producer_proc.send_stop_signal()

# Now we wait until it's done.
producer_proc.wait()

# From here all files were generated we can do whatever we want with them.