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
- Domain (Second level domain / Subdomain):
-
or
from PyFunceble import DomainAvailabilityChecker
- Second Level Domain:
-
or
from PyFunceble import SecondLvlDomainSyntaxChecker
- Subdomain:
-
or
from PyFunceble import SubDomainSyntaxChecker
- URL:
-
or
from PyFunceble import URLSyntaxChecker
- IP (v4 / v6):
-
or
from PyFunceble import IPSyntaxChecker
- IPv4
-
or
from PyFunceble import IPv4SyntaxChecker
- IPv6
-
or
from PyFunceble import IPv6SyntaxChecker
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.