PyFunceble is a tool designed to check the availability or syntax of domains, IP addresses, or URLs. It achieves accurate availability checks by utilizing multiple sources, including:

• WHOIS records
• DNS records
• HTTP status codes

Developers can integrate PyFunceble into their projects via:

• A standard built-in CLI implementation.
• A Python API.
• The pyfunceble-web-worker project, which exposes core functionalities through a web API.

The CLI is capable of testing subjects from various sources such as hosts files, plain lists, AdBlock filter lists, or RPZ records.

PyFunceble uses YAML files to manage its settings. The configuration follows a hierarchy where specific files or CLI arguments can override defaults:

1. .PyFunceble.yaml: The primary configuration file containing default settings for your current version. PyFunceble may update this file automatically as features change between versions to ensure compatibility.
2. .PyFunceble.overwrite.yaml: An empty file generated in your configuration folder. You should use this file to define your custom configuration choices. PyFunceble will never overwrite this file, making it the safe place for user-defined settings.
3. CLI Parameters: Any configuration value can be overridden directly via the command line.

# Example of what you might put in .PyFunceble.overwrite.yaml
some_setting: custom_value

Aggressive mode (--aggressive) instructs PyFunceble to decode input files without strictly following technical conventions. This is useful for extracting maximum data from non-standard or complex files.

• AdBlock lists: It will attempt to decode almost every domain it encounters.
• Hosts/Plain text files: It will automatically convert full URLs (e.g., https://example.com/hello/world) into testable domains (e.g., example.com).

Type: boolean (yes/no) Default: no CLI Flag: --aggressive

# Example CLI usage
pyfunceble --aggressive input_file.txt

PyFunceble adjusts its configuration lookup behavior in specific environments:

• CI/CD Engines: PyFunceble primarily uses the workspace folder as the current folder. If PYFUNCEBLE_CONFIG_DIR is not set, the root folder of your repository will be used as the configuration directory.
• Cloned PyFunceble Repository: If you are running tests from the root of a cloned PyFunceble repository, the repository's root folder is treated as the configuration directory.

On Linux and MacOS, PyFunceble searches for configuration folders in the following order. The first matching folder found is used to install initial configuration or system files:

1. ~/.config/PyFunceble
2. ~/.PyFunceble
3. $PWD (the current working directory)

Note on folder creation: If no folder is found, PyFunceble will attempt to create ~/.config/PyFunceble. If the parent directory (e.g., ~/.config) does not exist, it will traverse upwards until a viable parent folder is found to create the directory.

The wildcard parameter (--wildcard) enables the reduction of wildcards found in input files. This converts wildcard patterns into valid, testable domains.

Example: *.example.org is reduced to example.org.

This is useful when you want to test the underlying domain rather than the specific wildcard pattern.

Type: boolean (yes/no) Default: no CLI Flag: --wildcard

# Example CLI usage
# This will treat *.example.org as example.org
pyfunceble --wildcard input_list.txt

When using PyFunceble, CLI arguments for boolean parameters act as a 'light switch' (toggle) rather than an explicit assignment.

If a boolean parameter is defined in your configuration file (e.g., .PyFunceble.overwrite.yaml), passing the corresponding CLI flag will invert its current value:

• If the config is set to yes, passing the flag sets it to no.
• If the config is set to no, passing the flag sets it to yes.

This behavior allows you to quickly override your default configuration settings without modifying the configuration file itself.

verify-ssl-certificates: yes

If you run:

pyfunceble --verify-ssl-certificate -d example.org

The parameter verify_ssl_certificates will be set to no.

PyFunceble allows you to proxy requests to other servers or services using two main configuration keys: global and rules.

• global: Defines the fallback proxies used for all HTTP/HTTPS traffic when no specific rule matches the target domain.
• rules: Defines granular proxy settings based on the Top Level Domain (TLD). If a domain's TLD matches a rule in this list, the rule's proxy settings take precedence over the global settings.

While PyFunceble respects standard HTTP_PROXY and HTTPS_PROXY environment variables, using the proxy configuration parameters is recommended for TLD-specific routing.

proxy:
  global:
    http: http://proxy.example.com
    https: http://proxy.example.com:8443
  rules:
    - http: http://spec-proxy.example.com
      https: http://spec-proxy.example.com:8443
      tld:
        - com
        - org
        - dev

PyFunceble supports three mutually exclusive testing modes. You must select one to produce outputs. If no mode is specified, it defaults to Availability mode.

Testing speed in PyFunceble is influenced by several external and internal factors. When troubleshooting slow performance, consider the following:

• Network/Connectivity: Bandwidth, DNS Server response time, and ISP filters (which may block connections to large amounts of IPs).
• Hardware: CPU availability and Disk I/O. Since PyFunceble is heavy on I/O (using CSV storage), using RAM Drives or NVMe disks is highly recommended.
• Data: The total size of the dataset being tested.
• Database Management: Internal database management (though this does not apply if using PostgreSQL, MySQL, or MariaDB).

On Windows, PyFunceble searches for configuration folders in the following order. The first matching folder found is used to install initial configuration or system files:

1. %APPDATA%\PyFunceble
2. %CD% (the current working directory)

Note on folder creation: If no folder is found, PyFunceble will attempt to create %APPDATA%\PyFunceble. If the %APPDATA% directory does not exist, it will traverse upwards until a viable parent folder is found to create the directory.

You can force PyFunceble to use a specific decoder exclusively using the adblock or rpz parameters.

AdBlock Exclusive Decoding

Use --adblock or set adblock: yes in your config. WARNING: This makes PyFunceble assume that all input files are AdBlock filter lists. If you provide a different file type, it will still attempt to decode it as an AdBlock list.

RPZ Exclusive Decoding

Use --rpz or set rpz: yes in your config. WARNING: This makes PyFunceble assume that all input files are RPZ files.

Type: boolean (yes/no) Default: no CLI Flags: --adblock, --rpz