PyFunceble

https://pyfunceble.readthedocs.io/en/latest/
Admin
PyFunceble is a tool that provides an accurate availability check of domains, IPs, or URLs using...
Tokens:563,649
Snippets:4,940
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/config/loader.html

Starts the configuration loading process. This involves getting the configuration content, merging custom configurations, and initializing storage with the loaded settings.

```APIDOC
## start

### Description
Starts the loading process. This method retrieves configuration content, merges custom configurations if provided, and initializes PyFunceble's storage with the final configuration.

### Method
```python
def start(self) -> "ConfigLoader":
    """
    Starts the loading processIs.
    """
```

### Returns
- ConfigLoader: The current instance of ConfigLoader after starting the process.
```

--------------------------------

### start Method

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.migrators.csv_file.html

Initiates the migration process and handles all related setup and execution. This is the primary method to call to begin the migration.

```python
def start(self) -> MigratorBase:
    """Starts the migration and everything related to it."""
    return self
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.config.html

Starts the loading process.

```APIDOC
## method start()

### Description
Starts the loading process.

### Returns
* PyFunceble.config.loader.ConfigLoader
```

--------------------------------

### Start Migration Method

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/migrators/json2csv/base.html

Starts the migration process after ensuring both source file and dataset are provided. Logs the start and finish of the migration.

```python
@ensure_source_file_is_given
    @ensure_dataset_is_given
    def start(self) -> "JSON2CSVMigratorBase":
        """
        Starts the migration and everything related to it.
        """

        PyFunceble.facility.Logger.info("Started migration.")

        self.migrate()

        PyFunceble.facility.Logger.info("Finished migration.")

        return self
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.filesystem.html

Starts the generation of everything possible.

```APIDOC
## start

### Description
Starts the generation of everything possible.

### Method
`start()`

### Returns
`PyFunceble.cli.filesystem.status_file.StatusFileGenerator`
```

--------------------------------

### DNS Server Configuration Example

Source: https://pyfunceble.readthedocs.io/en/latest/configuration/index.html

Example of how to configure DNS servers, including specifying port numbers.

```yaml
dns_server:
  - dns1.example.org
  - dns2.example.org
```

```yaml
- 127.0.1.53:5353
```

--------------------------------

### Start Migration

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/migrators/mariadb/base.html

Starts the migration process if authorized. Logs the start and finish of the migration. Decorated to only execute if authorized.

```python
@execute_if_authorized(None)
def start(self) -> "MariaDBMigratorBase":
        """
        Starts the migration if wanted.
        """

        PyFunceble.facility.Logger.info("Started migration.")

        self.migrate()

        PyFunceble.facility.Logger.info("Finished migration.")

        return self
```

--------------------------------

### Travis CI Configuration (.travis.yml)

Source: https://pyfunceble.readthedocs.io/en/latest/usage/index.html

This is a commented example of a .travis.yml file for PyFunceble. It shows how to set up environment variables, specify the Python version, configure caching, install dependencies, and define the script to run for testing.

```yaml
env:
    global:
        # The following is your encrypted GitHub API key.
        # Indeed as we are going to push to the repository, this is needed.
        #- GH_TOKEN: # This can be set in the travis-ci https://travis-ci.com/repo/settings as 'Environment Variables'
        # or as below: secure: encrypted code
        - secure: QQdKFquFFojFT9XJ1XZp4EMoDTVoXFgqZq8XU+sCVf+pJQR6d/oKBp8rnSTCnZizWOQXUjGXUUxUpSG/dYGyBLjo3rH3rsn9ciZHVfubxbwK860w4sqibl4DvhCv2rdsFtvzXnhm4P9OL3i+krKdewh9fxpNyUU58qOgfnS7mK9FcFhb8z5ak2sxU2XRZedwm6Ro0oyVKs8kFkL4YaADfNyAHlGTfr9rVmE52WXQXQENktb9gFgR2A8ZnmLy0BCMZGkPDShJnjRDWD4DErtasLmLQvWpzOBwdbVJTY6U9KDRXVNdC9lp5E5Ba/dc0y36q6vjfgJR+QchetOtHgNbKYbLB8c26Di90OZCFJsxMNcl1Wct4qFPXkFGvjXrISW6pbdPL5Plto0Ig3iLiulhYOPVArysMIk9ymtSXP+WE7VWX01LQ1fEkIoSfeVZ2caTnCmTsoHVGRRe978CojKaT7yU45kb15hcyDrzptQ8EP2hfxeh5F7KtueQ6Rsb9LFDZMkMDKflZn6a+bRhESlmWWmYB9stzGzTurQA1E1bcSACJ8A8hG5nHBzZYJ2S+OY0PE7UdyOJ0JK0qe/67d+F9ocQdIoFpDDTdgIjHerQnD2wRg1aKPzLDb4jJTpqgr5ssPrqUAKl3st7gyaAZzCEADPDnIBDjOJS+mFWbx9DKgc=
        # This is the Git name we have to set. (git config user.name)
        - GIT_NAME: Travis CI
        # This is the Git Email we have to set. (git config user.email)
        - GIT_EMAIL: dead-hosts@funilrys.com

# This is the language we use.
language: python

# This is the python version we are going to use for the tests.
# Note: you can add any 3.x version to the list.
python:
- "3.8"

# The following will tell Travis CI to ends as fast as possible.
matrix:
    fast_finish: true

# Here we are setting what Travis CI have to cache.
cache:
    # We are caching pip3 as we use it to install PyFunceble
    - pip3

install:
    # We install the development version of PyFunceble. If you prefer the stable version replace
    # `pyfunceble-dev` with `pyfunceble`.
    - pip3 install pyfunceble-dev

# Our tests start here.
script:
    # Let's say we want our results and our PyFunceble infrastructure to be saved in a directory
    # called `PyFunceble-tests`

    # We move inside it.
    - cd PyFunceble-tests
    # We test the file `my_awesome_list` which is located inside the current directory.
    # Note: we precise the `--ci` argument here,
    #     but you work without it if you set `travis: true` inside your `.PyFunceble.yaml`
    - PyFunceble --ci -f my_awesome_list --plain

# The following initiate email notification logic.
notifications:
    # As we want to get a mail on failure and on status change, we set the following.
    on_success:   change
    on_failure:   always

```

--------------------------------

### DownloaderBase Start Method

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.downloader.html

Initiates the download process.

```python
def start(self) -> None[source]:
    """Starts the download process."""
```

--------------------------------

### Start Migration Method

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/migrators/db_base.html

Abstract method to start the migration process. Must be implemented by subclasses.

```python
def start(self) -> "MigratorBase":
        """
        Starts the migration.
        """

        raise NotImplementedError()
```

--------------------------------

### Install PyFunceble Development from GitHub

Source: https://pyfunceble.readthedocs.io/en/latest/update/index.html

Install the development version of PyFunceble directly from its GitHub repository. The --user flag is recommended for user-level installation.

```bash
$ pip3 install --user --upgrade git+https://github.com/funilrys/PyFunceble.git@dev#egg=PyFunceble
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.system.html

Provides a launcher for a predefined set of actions associated with the current object.

```APIDOC
## start()

### Description
Provides a launcher for a brunch of predefined actions defined by the current object.
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.processes.html

Starts all previously created worker processes.

```APIDOC
## start

### Description
Starts all - previously - created workers.

### Method
Function

### Returns
- PyFunceble.cli.processes.base.ProcessesManagerBase: The manager instance for chaining.
```

--------------------------------

### Install Missing Infrastructure Files

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/config/loader.html

Installs the configuration file and directory structure file if they are missing and the configuration has not yet been loaded.

```python
@staticmethod
    def install_missing_infrastructure_files(
        self,
    ) -> "ConfigLoader":  # pragma: no cover ## Copy method already tested
        """
        Installs the missing files (when needed).

        .. note::
            Installed if missing:
                - The configuration file.
                - The directory structure file.
        """

        if not self.is_already_loaded():
            if not self.file_helper.set_path(self.path_to_config).exists():
                self.file_helper.set_path(self.path_to_default_config).copy(
                    self.path_to_config
                )

        return self
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.scripts.html

Initiates the generation of the dataset file.

```APIDOC
## start

### Description
Starts the generation of the dataset file.

### Parameters
#### Path Parameters
- **max_workers** (Optional[int]) - Optional - The maximal number of workers we are allowed to use.
```

--------------------------------

### Global Proxy Settings Example

Source: https://pyfunceble.readthedocs.io/en/latest/configuration/index.html

Example of global HTTP and HTTPS proxy settings. If no rules match, these will be used. Both keys are required, but if one is missing, the provided one will be duplicated.

```yaml
http: http://example.org:8080
https: null
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/checker/availability/extras/base.html

Abstract method to start the gathering process. Must be implemented by subclasses.

```APIDOC
## start

### Description
Starts the gathering process.

### Method Signature
```python
def start(self) -> "ExtraRuleHandlerBase":
```

### Returns
- **ExtraRuleHandlerBase** - The instance of the handler.

### Raises
- **NotImplementedError** - This method must be implemented by subclasses.
```

--------------------------------

### Install PyFunceble using the pure Python method

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Installs PyFunceble by cloning the repository and using pip for an editable install. This method is preferred for development or when easy uninstallation/updates are desired, and it also installs dependencies at the user level.

```bash
$ git clone https://github.com/funilrys/PyFunceble.git
$ cd PyFunceble
$ python3 setup.py test
$ python3 setup.py install # Avoid this if you want to uninstall or update one day.
$ pip3 install --user -e .

```

--------------------------------

### MariaDBMigratorBase Start Method

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.migrators.mariadb.html

Starts the migration process if it is intended to be run. This method acts as an entry point for initiating the migration sequence.

```python
def start(self) -> MariaDBMigratorBase:
    """
    Starts the migration if wanted. 
    """
```

--------------------------------

### MigratorBase.start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/migrators/csv_file/base.html

Starts the migration process. This method initializes the logging for the migration start, calls the core `migrate` method, and logs the completion of the migration.

```APIDOC
## MigratorBase.start

### Description
Starts the migration and everything related to it. Logs the start and finish of the migration process.

### Method
`start`

### Parameters
None

### Returns
- **self** (MigratorBase) - Returns the instance of the migrator.

### Example
```python
# Assuming an instance of a class inheriting from MigratorBase
migrator_instance.start()
```
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.checker.availability.extras.html

Initiates the parked status checking process. This method is part of the ParkedRulesHandler and starts the gathering of parked status information.

```APIDOC
## Method: start

### Description
Starts the gathering process.

### Returns
ParkedRulesHandler - The instance of the handler after starting the process.
```

--------------------------------

### Install PyFunceble Development from GitHub

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Install the development version of PyFunceble directly from its GitHub repository using pip. The --user flag is recommended for user-level installation.

```bash
$ pip3 install --user git+https://github.com/funilrys/PyFunceble.git@dev#egg=PyFunceble
```

--------------------------------

### Start Filesystem Cleanup (Python)

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/filesystem/cleanup.html

Initiates the overall filesystem cleanup process, starting with cleaning output files.

```python
    def start(self) -> "FilesystemCleanup":
        """
        Starts the cleanup of everything unneeded.
        """

        self.clean_output_files()

        return self
```

--------------------------------

### Install PyFunceble Development using Pure Python Method

Source: https://pyfunceble.readthedocs.io/en/latest/update/index.html

Install PyFunceble development version by cloning the repository and using pip for an editable install. This method is preferred for easier uninstallation.

```bash
$ cd PyFunceble && git checkout dev
$ git fetch origin && git merge origin/dev
$ python3 setup.py test
$ python3 setup.py install # Avoid this if you want to uninstall one day.
$ pip3 install --user --upgrade -e .
```

--------------------------------

### EToxic Handler Start Method

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/checker/availability/extras/etoxic.html

This method initiates the eToxic check. It logs the start of the process and, if the domain is already marked as UP and matches a pattern in the eToxic list, it triggers a specific request to mark it as DOWN. It logs the completion of the check.

```python
    @ExtraRuleHandlerBase.ensure_status_is_given
    @ExtraRuleHandlerBase.setup_status_before
    @ExtraRuleHandlerBase.setup_status_after
    def start(self) -> "EToxicHandler":
        PyFunceble.facility.Logger.info(
            "Started to check %r against the eToxic handler.",
            self.status.idna_subject,
        )

        if self.status.status_before_extra_rules == PyFunceble.storage.STATUS.up:
            if any(self.status.netloc.endswith(x) for x in self.MATCHES):
                self.do_on_header_match(
                    self.req_url,
                    matches={"location": [f"/{self.status.netloc}", "/search/"]},
                    method=self.switch_to_down,
                    allow_redirects=False,
                    match_mode="std",
                    strict=True,
                )

        PyFunceble.facility.Logger.info(
            "Finished to check %r against our the eToxic handler.",
            self.status.idna_subject,
        )

        return self

```

--------------------------------

### Start method for File Cleanup Migration

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/migrators/file_cleanup/base.html

This method initiates the file cleanup migration process. It logs the start and end of the migration and calls the `migrate` method to perform the actual file deletion.

```python
def start(self) -> "FileClenupMigratorBase":
    """
    Starts the migration and everything related to it.
    """

    PyFunceble.facility.Logger.info("Started migration.")

    self.migrate()

    PyFunceble.facility.Logger.info("Finished migration.")

    return self
```

--------------------------------

### Clone and Install PyFunceble Development Version

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Clone the PyFunceble repository, checkout the dev branch, set up a virtual environment, and install the package in editable mode. This is recommended for development.

```bash
$ git clone https://github.com/funilrys/PyFunceble.git
$ cd PyFunceble
$ git checkout dev
$ virtualenv -p python3 venv
$ source venv/bin/activate
$ pip3 install -e .
```

--------------------------------

### Main Start Method for PyFunceble CLI (Python)

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/system/launcher.html

The main entry point for starting the PyFunceble CLI. It handles initialization, process management, continuous integration checks, and error handling. This method orchestrates the entire execution flow.

```python
@SystemBase.ensure_args_is_given
    def start(self) -> "SystemLauncher":
        try:
            self.print_home_ascii()

            print_central_messages(check_force_update=True)

            # This tries to bypass the execution when the continuous integration
            # is given and the last commit message (the one we are testing for)
            # match any of our known marker. Please report to the method itself
            # for more information about the markers.
            self.continuous_integration.bypass()

            if self.args.files or self.args.url_files:
                self.migrator_process_manager.start()

                self.migrator_process_manager.wait()

            del self.migrator_process_manager

            if not self.file_preloader.authorized or (
                not self.args.files and not self.args.url_files
            ):
                self.__start_core_processes()

            self.fill_protocol()
            self.fill_to_test_queue_from_protocol()

            self.stop_and_wait_for_all_manager()

            if self.continuous_integration.is_time_exceeded():
                # Does not includes the run_standard_end_instructions call.
                # Reason: We have to continue.
                self.run_ci_saving_instructions()
            elif self.continuous_integration.authorized:
                # Includes the run_standard_end_instructions call.
                self.run_ci_end_saving_instructions()
            else:
                self.run_standard_end_instructions()

        except (KeyboardInterrupt, StopExecution):
            pass
        except Exception as exception:  # pylint: disable=broad-except
            PyFunceble.facility.Logger.critical(
                "Fatal error.",
                exc_info=True,
            )
            print(
                f"{colorama.Fore.RED}{colorama.Style.BRIGHT}Fatal Error: "
                f"{exception}"
            )

            print(traceback.format_exc())
            sys.exit(1)

        PyFunceble.cli.utils.stdout.print_thanks()

        return self
```

--------------------------------

### start_time

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.continuous_integration.html

Represents the starting time of the CI process. Defaults to None.

```APIDOC
## start_time

### Description
Represents the starting time of the CI process.

### Attribute
`start_time` (Optional) - Defaults to None.
```

--------------------------------

### Get Authorized URI

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/credential_loader.html

Retrieves the URI to use, ensuring authorization and that the process has started. This method is decorated with authorization and start-up checks.

```python
@execute_if_authorized("")
    @start_if_not_started
    def get_uri(self) -> str:
        """
        Provides the URI to use.
        """

        return self.credential.get_uri()
```

--------------------------------

### Initialize DownloadHelper with URL

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/helpers/download.html

Demonstrates how to initialize the DownloadHelper with a specific URL. The URL can be set during instantiation.

```python
from PyFunceble.helpers.download import DownloadHelper

# Initialize with a URL
downloader = DownloadHelper(url="https://example.com/file.zip")

print(downloader.url)
```

--------------------------------

### Guess All Settings

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/checker/availability/base.html

Iterates through available methods starting with 'guess_' (excluding 'guess_all_settings') and calls them to set various configurations. This method is marked with `no cover` as its primary purpose is configuration setup.

```python
to_ignore = ["guess_all_settings"]

        for method in dir(self):
            if method in to_ignore or not method.startswith("guess_"):
                continue

            getattr(self, method)()

        return self
```

--------------------------------

### Get Execution Information

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/execution_time.html

Retrieves detailed execution information, including the time difference between start and end times. If the end time is not set, it will be set to the current time. Formats days, hours, minutes, and seconds for display.

```python
    @execute_if_authorized(None)
    def get_info(self) -> dict:
        """
        Provides the information to work with.
        """

        if not self.end_time:
            self.set_end_time()

        result = self.split_difference(self.start_time, self.end_time)

        result["days"] = str(int(result["days"])).zfill(2)
        result["hours"] = str(int(result["hours"])).zfill(2)
        result["minutes"] = str(int(result["minutes"])).zfill(2)
        result["seconds"] = str(round(result["seconds"], 6)).zfill(2)

        return result

```

--------------------------------

### Check IPv4 Range Syntax

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble.html

Demonstrates how to check if a given subject is a valid IPv4 range using IPSyntaxChecker. Includes examples of getting status in dictionary and JSON formats, and a specific check for IPv4 range validity.

```python
from PyFunceble import IPSyntaxChecker

my_subject = "192.168.0.0"
the_status = IPSyntaxChecker(
    my_subject
).get_status()

# Get the status in dict format.
print(the_status.to_dict())

# Get the status in json format.
print(the_status.to_json())

# Check if it is IPv4 range.
print(f"{my_subject} is IPv4 range ? {the_status.is_valid_v4_range()}")
```

--------------------------------

### try_to_query_status_from_whois

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/checker/availability/base.html

Tries to get the status from the WHOIS record. It prioritizes querying from the best database if configuration is loaded, otherwise it queries the best WHOIS server. It can also add the record to the database if the expiration date extraction is successful and the process name does not start with 'PyFunceble'.

```APIDOC
## try_to_query_status_from_whois

### Description
Tries to get and the status from the WHOIS record.

### Method
This is a method within a class, not a direct HTTP endpoint.

### Parameters
None explicitly defined in the signature, relies on class instance attributes.

### Request Example
```python
# This is a method call on an instance of a class
checker_instance.try_to_query_status_from_whois()
```

### Response
Returns the AvailabilityCheckerBase instance itself, allowing for method chaining.
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.html

Initiates the file pre-loading process. This method begins the operation of pre-loading the currently configured file path, with an option to print progress dots.

```APIDOC
## start

### Description
Starts the pre-loading of the currently set file path.

### Method Signature
`start(_print_dots: bool = False_) → PyFunceble.cli.file_preloader.FilePreloader`

### Parameters
#### Path Parameters
- **print_dots** (bool) - Optional - If True, progress dots will be printed during the pre-loading process. Defaults to False.
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/processes/base.html

Starts all previously created workers. If workers are already running, it skips starting them again.

```APIDOC
## start

### Description
Starts all workers that have been previously created. It handles cases where a worker might already be running to prevent errors.

### Method
`start`

### Returns
- `ProcessesManagerBase`: The instance of the ProcessesManagerBase with workers started.
```

--------------------------------

### CredentialLoader start Method

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.html

Initiates the credential loading process. Can optionally ignore prompts to the end-user.

```python
def start(self, *args, ignore_cli: bool = True) -> 'CredentialLoader':
    """Starts the loading of the credential.
    Parameters:| **ignore_cli** – Ignore questions to end-user.  
    ---|--- 

    """
    if self.is_already_loaded():
        return self
    if self.db_type not in self.DB_TYPE2OBJ:
        raise TypeError(f"Database type '{self.db_type}' not supported.")
    credential_class = self.DB_TYPE2OBJ[self.db_type]
    if credential_class:
        self.credential = credential_class(self)
        if not ignore_cli:
            self.credential.load_from_input()
        else:
            self.credential.load_from_environ()
    return self
```

--------------------------------

### Start Workers

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/processes/base.html

Starts all previously created workers. Includes error handling for attempting to start a worker that is already running.

```python
    @ensure_worker_obj_is_given
    @create_workers_if_missing
    @ignore_if_running
    def start(self) -> "ProcessesManagerBase":
        """
        Starts all - previously - created workers.
        """

        for worker in self._created_workers:
            try:
                worker.start()
            except AssertionError:
                # Example: cannot start a process twice
                pass

            self._running_workers.append(worker)

        if self.input_datasets:
            while self.input_datasets:
                self.add_to_input_queue(self.input_datasets.pop())
```

--------------------------------

### Start If Not Started Decorator

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/credential_loader.html

A decorator that ensures the start method is called before executing the decorated method. It checks if the credential has been initialized.

```python
def start_if_not_started(func):
    """
    Launches the start method before launching the decorated method.
    """

    @functools.wraps(func)
    def wrapper(self, *args, **kwargs):
        if not isinstance(self.credential, CredentialBase):
            self.start()

        return func(self, *args, **kwargs)  # pylint: disable=not-callable

    return wrapper
```

--------------------------------

### Initialize DownloadHelper with Certificate Validation and Retries

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/helpers/download.html

Shows how to initialize the DownloadHelper, customizing certificate validation and the number of retries. Certificate validation defaults to True and retries to 3.

```python
from PyFunceble.helpers.download import DownloadHelper

# Initialize with custom certificate validation and retries
downloader_no_validation = DownloadHelper(certificate_validation=False, retries=5)

print(f"Certificate Validation: {downloader_no_validation.certificate_validation}")
print(f"Retries: {downloader_no_validation.retries}")
```

--------------------------------

### Load Configuration

Source: https://pyfunceble.readthedocs.io/en/latest/api/endpoints.html

Use ConfigLoader.start() to load the configuration. This method is generally not required since version 4.0.0 but can be used for special CLI-related methods.

```python
import PyFunceble.facility

PyFunceble.facility.ConfigLoader.start()
```

--------------------------------

### Start Backup Process

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/filesystem/dir_structure/backup.html

Initiates the backup process by first cleaning up any existing backup and then storing the new backup. This method orchestrates the backup operation.

```python
def start(self) -> "DirectoryStructureBackup":
        """
        Starts the backup process.
        """

        return self.cleanup().store_backup()
```

--------------------------------

### Send GET Request

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/query/requests/requester.html

Sends an HTTP GET request using the configured session and returns the response. This method is decorated with `@request_factory('GET')`.

```python
    @request_factory("GET")
    def get(self, *args, **kwargs) -> requests.Response:
        """
        Sends a GET request and get its response.
        """

```

--------------------------------

### Update setup.py Content

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/scripts/production.html

Updates the content of the 'setup.py' file. This script is part of the production preparation process and logs its activity.

```python
PyFunceble.facility.Logger.info(
    "Started to update setup.py.",
)
```

--------------------------------

### Install PyFunceble Development from PyPI

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Install the development version of PyFunceble from PyPI using pip. The --user flag is recommended for user-level installation.

```bash
$ pip3 install --user PyFunceble-dev
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/downloader/base.html

Initiates the download process if authorized and the download has expired. It performs checks for download destination and link before proceeding.

```APIDOC
## start

### Description
Starts the download process.

### Method
```python
def start(self) -> None:
    # ... implementation ...
```

### Raises
- **PyFunceble.downloader.exceptions.NoDownloadDestinationGiven** - If no download destination is provided.
- **PyFunceble.downloader.exceptions.NoDownloadLinkGiven** - If no download link is provided.
```

--------------------------------

### Start Production Process

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/scripts/production.html

Orchestrates the entire production preparation process by calling the necessary update methods in sequence.

```python
    def start(self) -> "ProductionPrep":
        """
        Starts the production process.
        """

        return (
            self.update_setup_py()
            .update_code_urls()
            .update_code_format()
            .update_version_file()
        )
```

--------------------------------

### Install PyFunceble Development from PyPI

Source: https://pyfunceble.readthedocs.io/en/latest/update/index.html

Install the development version of PyFunceble from PyPI using pip. The --user flag is recommended for user-level installation.

```bash
$ pip3 install --user --upgrade PyFunceble-dev
```

--------------------------------

### Install PyFunceble Development with makepkg (AUR)

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Install the PyFunceble development version on Arch Linux using makepkg by downloading the PKGBUILD file and then installing the package with pacman.

```bash
$ curl https://aur.archlinux.org/cgit/aur.git/plain/PKGBUILD?h=pyfunceble-dev -o PKGBUILD
$ makepkg
$ sudo pacman -U pyfunceble-dev*.tar.xz
```

--------------------------------

### Initialize Nameservers with Custom List

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/query/dns/nameserver.html

Instantiate the Nameservers class with a custom list of DNS servers. If no custom list is provided, default servers will be used.

```python
nameserver_instance = Nameservers(nameserver=["8.8.8.8", "1.1.1.1"])
```

--------------------------------

### start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/checker/availability/extras/rules.html

Starts the extra rules checking process for a given subject.

```APIDOC
## start

### Description
Starts the process of applying extra rules to check the status of a subject. It handles active-to-inactive status deescalation and potential switch to UP status for IP ranges.

### Method
This is a method within a class, not a direct HTTP endpoint.

### Endpoint
N/A (Internal method)

### Parameters
None explicitly documented for direct user invocation.

### Request Example
N/A

### Response
Returns the current instance of the handler for chaining.

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Example CI Branch Configuration

Source: https://pyfunceble.readthedocs.io/en/latest/usage/terminal.html

Illustrates the use of separate branches for PyFunceble tests and result distribution in a CI environment.

```bash
--ci-branch processing
--ci-distribution-branch master
```

--------------------------------

### SubjectSwitchRulesHandler Start Method

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/checker/availability/extras/subject_switch.html

Initiates the subject switching rules check. It logs the start of the process and conditionally performs a request if the subject's netloc starts with 'www.' or 'm.'.

```python
@ExtraRuleHandlerBase.ensure_status_is_given
    @ExtraRuleHandlerBase.setup_status_before
    @ExtraRuleHandlerBase.setup_status_after
    def start(self) -> "SubjectSwitchRulesHandler":
        """
        Process the check and handling of the current subject.
        """

        PyFunceble.facility.Logger.info(
            "Started to check %r against our subject switcher rules.",
            self.status.idna_subject,
        )

        try:
            if any(self.status.netloc.startswith(x) for x in ("www.", "m.")):
                self.do_request()
```

--------------------------------

### Start File Preloading Process

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/file_preloader.html

Initiates the file preloading process. It loads descriptions, calculates file hashes, and handles cleanup and line number resets based on file changes.

```python
    @execute_if_authorized(None)
    @ensure_protocol_is_given
    def start(self, print_dots: bool = False) -> "FilePreloader":
        """
        Starts the pre-loading of the currently set file path.
        """

        self.__load_description()

        broken = False
        file_helper = FileHelper(self.protocol["subject"])
        self.__description[self.__matching_index]["hash"] = HashHelper().hash_file(
            file_helper.path
        )

        if isinstance(self.continue_dataset, CSVContinueDataset):
            self.continue_dataset.set_base_directory(self.protocol["output_dir"])

        if (
            self.__description[self.__matching_index]["checker_type"]
            != self.protocol["checker_type"]
            or self.__description[self.__matching_index]["subject_type"]
            != self.protocol["subject_type"]
        ):
            try:
                self.continue_dataset.cleanup()
            except TypeError:
                self.continue_dataset.cleanup(session_id=self.protocol["session_id"])

        if (
            self.__description[self.__matching_index]["previous_hash"]
            and self.__description[self.__matching_index]["hash"]
            != self.__description[self.__matching_index]["previous_hash"]
        ):
            # Forces the reading of each lines because there is literally no
            # way to know where something has been changed.
            self.__description[self.__matching_index]["line_number"] = 1

        if (
            self.__description[self.__matching_index]["checker_type"]
            != self.protocol["checker_type"]
            or self.__description[self.__matching_index]["subject_type"]
            != self.protocol["subject_type"]
            or self.__description[self.__matching_index]["hash"]
            != self.__description[self.__matching_index]["previous_hash"]
        ):
            try:
                with file_helper.open("r", encoding="utf-8") as file_stream:
                    line_num = 1

```

--------------------------------

### Install PyFunceble from PyPI using pip

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Installs the stable version of PyFunceble from the Python Package Index. The `--user` flag is recommended for user-level installation, but not for containers or CI environments.

```bash
$ pip3 install --user PyFunceble

```

--------------------------------

### Start Download Process

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/downloader/base.html

Initiates the download process if authorized and the last download has expired. Raises exceptions if destination or link are not provided. Sets current downtime and saves it upon successful download.

```python
    def start(self) -> None:
        """
        Starts the download process.
        """

        if self.authorized and self.is_last_download_expired():
            if not hasattr(self, "destination") or not self.destination:
                raise PyFunceble.downloader.exceptions.NoDownloadDestinationGiven()

            if not hasattr(self, "download_link") or not self.download_link:
                raise PyFunceble.downloader.exceptions.NoDownloadLinkGiven()

            if DownloadHelper(self.download_link).download_text(
                destination=self.destination
            ):
                self.set_current_downtime()
                self.save_all_downtimes()

```

--------------------------------

### Install PyFunceble from GitHub using pip

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Installs the latest development version of PyFunceble directly from its GitHub repository. The `--user` flag is recommended for user-level installation, but not for containers or CI environments.

```bash
$ pip3 install --user git+https://github.com/funilrys/PyFunceble.git@master#egg=PyFunceble

```

--------------------------------

### Initialize and Use Domain Availability Checker

Source: https://pyfunceble.readthedocs.io/en/latest/api/index.html

Demonstrates initializing the DomainAvailabilityChecker with default configuration, setting a subject, and retrieving its status. The status can also be obtained in a single chained operation.

```python
from PyFunceble import DomainAvailabilityChecker

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

checker.set_subject("github.com")

status = checker.get_status()

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

--------------------------------

### Get State History

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/sqlalchemy/orm/attributes.html

Internal helper to get history from an InstanceState. Used by get_history.

```Python
def get_state_history(
    state: InstanceState[Any], key: str, passive: PassiveFlag = PASSIVE_OFF
) -> History:
    return state.get_history(key, passive)
```

--------------------------------

### Start Alembic Migration and Superclass Start

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/processes/migrator.html

This method initiates the database migration process using Alembic and then calls the superclass's start method to begin processing. It requires a worker object to be provided.

```python
@ProcessesManagerBase.ensure_worker_obj_is_given
@ProcessesManagerBase.create_workers_if_missing
def start(self) -> "ProcessesManagerBase":
    # We start the migration (as a standalone)
    Alembic(self._created_workers[0].db_session).upgrade()

    return super().start()
```

--------------------------------

### Prepare Production/Dev Files

Source: https://pyfunceble.readthedocs.io/en/latest/contributing/index.html

Use the PyFunceble CLI with the --production flag to prepare version.yaml and code for production or development usage.

```bash
$ # Prepare our files, :code:`version.yaml` and code for production/dev usage.
$ PyFunceble --production

```

--------------------------------

### GET Request

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/query/requests/requester.html

Sends an HTTP GET request to the specified URL and returns the server's response.

```APIDOC
## GET

### Description
Sends a GET request and returns its response.

### Method
GET

### Endpoint
This method is a wrapper around `requests.get` and does not define a fixed endpoint. The endpoint is provided as an argument during the call.

### Parameters
This method accepts arbitrary positional and keyword arguments that are passed directly to the underlying `requests.get` function.

### Request Example
```python
# Assuming 'requester' is an instance of Requester
response = requester.get('https://example.com')
```

### Response
#### Success Response (200 OK)
- The response object from the `requests` library.
```

--------------------------------

### Start Configuration Loading

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/config/loader.html

Initiates the configuration loading process. It retrieves the configuration, merges custom settings, applies conditional switches, and populates PyFunceble's storage with the processed configuration.

```python
def start(self) -> "ConfigLoader":
        """
        Starts the loading processIs.
        """

        config = self.get_config_file_content()

        if self.custom_config:
            config = Merge(self.custom_config).into(config)

        config = self.conditional_switch(config)

        PyFunceble.storage.CONFIGURATION = Box(
            config,
        )
        PyFunceble.storage.FLATTEN_CONFIGURATION = DictHelper(
            PyFunceble.storage.CONFIGURATION
        ).flatten()
        PyFunceble.storage.HTTP_CODES = Box(
            config["http_codes"],
        )
        if "collection" in config and config["collection"]:
            PyFunceble.storage.COLLECTION = Box(config["collection"])
        PyFunceble.storage.LINKS = Box(config["links"])

        if "proxy" in config and config["proxy"]:
            PyFunceble.storage.PROXY = Box(config["proxy"])

        return self
```

--------------------------------

### Starting Credential Loading Process

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/credential_loader.html

Initiates the credential loading process, fetching information from environment variables or prompting the user if necessary. Handles environment file loading.

```python
if not isinstance(self.credential, CredentialBase) and self.authorized:
    self.credential = (
        PyFunceble.cli.factory.DBSession.credential
    ) = self.DB_TYPE2OBJ[self.db_type]()

    env_var_helper = EnvironmentVariableHelper(
        env_file_path=self.credential.get_dot_env_file()
    )

    for cred_var, env_var in self.credential.VAR2ENV.items():
        if env_var_helper.set_name(env_var).exists():
            self.set_credential_var(cred_var, env_var_helper.get_value())
        else:
            from_file = env_var_helper.get_value_from_env_file()

            if from_file:
                self.set_credential_var(cred_var, from_file)
            elif not ignore_cli:
                self.set_credential_var(
                    cred_var,
                    self.ask_for_info(
                        cred_var,
                        getattr(self.credential, f"STD_{cred_var.upper()}"),
                    ),
                )
            else:
                self.set_credential_var(
                    cred_var,
                    getattr(self.credential, f"STD_{cred_var.upper()}"),
                )

            env_var_helper.set_value_in_env_file(
                str(getattr(self.credential, cred_var))
            )
```

--------------------------------

### Install PyFunceble using makepkg for Arch Linux

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Installs PyFunceble on Arch Linux by downloading the PKGBUILD file, building the package, and then installing it using pacman. This method is for users who prefer building from source or using AUR tools.

```bash
$ curl https://aur.archlinux.org/cgit/aur.git/plain/PKGBUILD?h=pyfunceble -o PKGBUILD
$ makepkg
$ sudo pacman -U pyfunceble*.tar.xz

```

--------------------------------

### Initialize FileHelper with a path

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/helpers/file.html

Instantiate FileHelper with an initial file path. The path can also be set later using the `set_path` method.

```python
from PyFunceble.helpers.file import FileHelper

# Initialize with a path
file_helper = FileHelper("/path/to/your/file.txt")

# Or set the path later
file_helper_2 = FileHelper()
file_helper_2.set_path("/path/to/another/file.txt")
```

--------------------------------

### SystemLauncher Initialization

Source: https://pyfunceble.readthedocs.io/en/latest/_modules/PyFunceble/cli/system/launcher.html

Initializes the SystemLauncher by setting up database sessions, execution time, testing mode, dataset objects, continuous integration, and output printers. It also initializes multiprocessing managers and process managers based on configuration.

```python
def __init__(self, args: Optional[argparse.Namespace] = None) -> None:
    try:
        self.db_session = (
            PyFunceble.cli.factory.DBSession.get_db_session().get_new_session()()
        )
    except TypeError:
        self.db_session = None

    self.execution_time_holder = ExecutionTime().set_start_time()
    self.checker_type = get_testing_mode()
    self.continue_dataset = get_continue_databaset_object(
        db_session=self.db_session
    )
    self.inactive_dataset = get_inactive_dataset_object(db_session=self.db_session)
    self.continuous_integration = ci_object()

    if self.continuous_integration.authorized:
        self.continuous_integration.init()

    self.stdout_printer.guess_allow_coloration()

    self.manager = multiprocessing.Manager()

    if not PyFunceble.storage.CONFIGURATION.cli_testing.chancy_tester:
        self.tester_process_manager = TesterProcessesManager(
            self.manager,
            max_worker=PyFunceble.storage.CONFIGURATION.cli_testing.max_workers,
            continuous_integration=self.continuous_integration,
            daemon=True,
            output_workers_count=1,
            output_queue_num=2,
        )
        self.producer_process_manager = ProducerProcessesManager(
            self.manager,
            max_worker=1,
            continuous_integration=self.continuous_integration,
            input_queue=self.tester_process_manager.output_queue[0],
            daemon=True,
            generate_output_queue=False,
        )
    else:
        self.tester_process_manager = ChancyTesterProcessesManager(
            self.manager,
            max_worker=PyFunceble.storage.CONFIGURATION.cli_testing.max_workers,
            continuous_integration=self.continuous_integration,
            daemon=True,
            output_workers_count=1,
            output_queue_num=2,
        )
        self.producer_process_manager = ChancyProducerProcessesManager(
            self.manager,
            max_worker=1,
            continuous_integration=self.continuous_integration,
            input_queue=self.tester_process_manager.output_queue[0],
            daemon=True,
            generate_output_queue=False,
        )
```

--------------------------------

### Requester GET Method

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.query.requests.html

Sends a GET request and retrieves the response. This method is part of the custom request handler.

```python
get(_*args , _**kwargs_) -> requests.models.Response[source]
```

--------------------------------

### Sample `.gitlab-ci.yml` for PyFunceble

Source: https://pyfunceble.readthedocs.io/en/latest/usage/index.html

This snippet shows a commented `.gitlab-ci.yml` file for setting up PyFunceble in a GitLab CI/CD pipeline. It includes image selection, variable definitions for Git configuration, a `before_script` to install PyFunceble, and a `run` script to execute PyFunceble with the `--ci` argument.

```yaml
# Python needed, so we use the python image.
image: python:latest

variables:
    # This is the Git name we have to set. (git config user.name)
    GIT_EMAIL: "dead-hosts@funilrys.com"
    # This is the Git Email we have to set. (git config user.email)
    GIT_NAME: "GitLab CI/CD"

before_script:
    # We install the development version of PyFunceble.
    # If you prefer the stable version replace `pyfunceble-dev`
    # with `pyfunceble`.
    - pip3 install PyFunceble-dev

run:
    script:
        # Let's say we want our results and our PyFunceble
        # infrastructure to be saved in a directory called `PyFunceble-tests`

        # We move inside it.
        - cd PyFunceble-tests
        # We test the file `my_awesome_list` which is located inside the current directory.
        # Note: we precise the `--ci` argument here,
        #     but you work without it if you set `ci: true` inside your `.PyFunceble.yaml`
        - PyFunceble --ci -f my_awesome_list --plain

```

--------------------------------

### init

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.cli.continuous_integration.html

Initializes the CI engine infrastructure. This method should be manually called before any other actions.

```APIDOC
## init

### Description
Initiate our infrastructure for the current CI engine.
The purpose of this method is to be able to have some custom init based on the CI we are currently on.
The init method should be manually started before runing any further action.

Warning
We assume that we are aware that you should run this method first.
```

--------------------------------

### Install PyFunceble with PostgreSQL support

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Use this command to install PyFunceble with optional PostgreSQL support, including development headers.

```bash
pip3 install --user pyfunceble[-dev][psql]

```

--------------------------------

### Pure Python Installation of PyFunceble Development

Source: https://pyfunceble.readthedocs.io/en/latest/installation/index.html

Install the PyFunceble development version using a pure Python method. This involves cloning the repository, checking out the dev branch, and then installing using setup.py or pip in editable mode. Prefer pip for easier uninstallation/updates.

```bash
$ git clone https://github.com/funilrys/PyFunceble.git
$ cd PyFunceble && git checkout dev
$ tox # Run tests
$ python3 setup.py install # Avoid this if you want to uninstall or update one day.
$ pip3 install --user -e . # Prefer this method.
```

--------------------------------

### Get Nameservers (Python)

Source: https://pyfunceble.readthedocs.io/en/latest/code/PyFunceble.query.dns.html

Provides the list of currently configured nameservers. Returns None if not set.

```python
Nameservers.get_nameservers()
```
Tokens:
Raw