PyFunceble Development

Common errors

• ModuleNotFoundError: No module named 'PyFunceble'

  cause The pyfunceble-dev package is not installed in your current Python environment, or the environment is not active.
  fix Run `pip install pyfunceble-dev` to install the package. If using a virtual environment, ensure it's activated.

• TypeError: PyFunceble.__init__() got an unexpected keyword argument 'config_file'

  cause In PyFunceble v4.x, the 'config_file' parameter for initialization has been removed. Configuration is now primarily handled through constructor arguments or the internal configuration module.
  fix Remove the `config_file` argument from the PyFunceble constructor. Instead, pass configuration options directly as keyword arguments (e.g., `PyFunceble(output_dir='...', log_level='...')`) or manage configuration via `PyFunceble.configure()`.

• PyFunceble.exceptions.ConnectionError: The following DNS server(s) failed to respond: [...]

  cause PyFunceble could not reach any configured or default DNS servers. This can be due to network issues, misconfigured DNS settings on the system, or firewalls blocking DNS traffic.
  fix Check your system's network connectivity and DNS server configuration. Ensure ports 53 (UDP/TCP) are not blocked. PyFunceble v4.2.0 and above provide default Quad9 DNS servers if none are found, so upgrading may help in some cases.

Warnings

• breaking Version 4.0.0 introduced a significant rewrite of the internal data work and a reinforcement of the Python module. Users upgrading from the 3.x series should expect breaking changes, especially if relying on deep internal interactions.
  Fix: Review the official PyFunceble v4 documentation and migration guides. Update any code interacting directly with PyFunceble's internal structures or previously deprecated APIs.
• gotcha Prior to v4.3.0, there were issues using MariaDB or PostgreSQL databases in 'single mode' (without a file-based input). This could lead to errors or unexpected behavior when trying to persist or retrieve data.
  Fix: Upgrade to PyFunceble v4.3.0 or newer. Ensure your database configuration is correct and accessible.
• gotcha Developers interacting with PyFunceble's database layer should be aware that the way PyFunceble works and interacts with SQLAlchemy 2.0 Declarative Mapping was improved in v4.3.1. This might affect custom integrations or extensions.
  Fix: Consult the PyFunceble GitHub repository for changes related to SQLAlchemy 2.0 interaction. Ensure your code aligns with the updated declarative mapping patterns if you're extending PyFunceble's ORM.
• gotcha Earlier versions (prior to v4.2.27) experienced unstable results when testing against HTTP status codes, leading to potentially inaccurate availability assessments.
  Fix: Upgrade to PyFunceble v4.2.27 or newer to benefit from improved stability and accuracy in HTTP status code checks.

Install

• pip install pyfunceble-dev Install latest version

Imports

• PyFunceble
  wrong:

  import pyfunceble

  correct:

  from PyFunceble import PyFunceble

  The primary programmatic entry point is the PyFunceble class itself, not the package as a whole.
• Engine

  from PyFunceble import Engine

  For more advanced control or integration with PyFunceble's core engine logic.

Quickstart

This quickstart demonstrates how to programmatically use PyFunceble to check the status of domains. It initializes the PyFunceble engine, tests a single domain, and prints key results. A temporary directory is used for output files to keep your system clean, and logging is suppressed for a concise output.

import tempfile
import shutil
from PyFunceble import PyFunceble

# Create a temporary directory for PyFunceble's output (logs, databases)
output_dir = tempfile.mkdtemp()

try:
    print(f"PyFunceble output will be stored in: {output_dir}")

    # Initialize PyFunceble. Pass output_dir to control where files are created.
    # For a fully quiet operation, you can configure logging separately.
    funceble = PyFunceble(output_dir=output_dir, 
                          log_level='CRITICAL', 
                          autodisconnect=True)

    # Test a single domain
    domain_to_test = "google.com"
    print(f"\nTesting '{domain_to_test}'...")
    results = funceble.test_single(domain_to_test)
    print(f"Results for {domain_to_test}: Status = {results.get('status', 'N/A')}, ")
    print(f"  Expiration = {results.get('expiration_date', 'N/A')}, ")
    print(f"  HTTP Status = {results.get('http_status_code', 'N/A')}")

    # Test a known non-existent domain (for demonstration)
    non_existent_domain = "thisdomainreallyshouldntexist.xyz"
    print(f"\nTesting '{non_existent_domain}'...")
    results_non_existent = funceble.test_single(non_existent_domain)
    print(f"Results for {non_existent_domain}: Status = {results_non_existent.get('status', 'N/A')}")

finally:
    # Clean up the temporary directory after use
    print(f"\nCleaning up temporary output directory: {output_dir}")
    shutil.rmtree(output_dir)