This is the PyFunceble Web Worker. It tries to bring the PyFunceble project to you through a Web API.

If you don't know what PyFunceble is, please report to the PyFunceble repository.

This project is not intended to fully replace the official PyFunceble Command Line Interface provided by @funilrys.

This project is intended for those who don't necessarily use Python for their projects, but still want to use PyFunceble to check the availability, syntax, or reputation of a domain, IP, or URL. In other words, this project only provides the core functions of PyFunceble, but behind a Web API.

When you use the PyFunceble CLI, it is just an implementation of functionalities on top of the core ideas of PyFunceble. In fact, if one wants to implement or create their CLI on top of the core capabilities of PyFunceble, they are welcome to do so. They can even submit it so that it may become the standard or an alternative documented implementation.

You won't find the following inside this project (to only list a few):

• Almost everything specially implemented by the CLI of PyFunceble.
  • The output file(s).
  • The inactive datasets.
  • The auto continue datasets.
  • The continuous integration module.
  • Any form of database.

Instead, you will find the following:

• Web endpoints to test the availability of a domain, IP, or URL.
• Web endpoints to test the syntax of a domain, IP, or URL.
• Web endpoints to test the reputation of a domain, IP, or URL.
• Web endpoint to get the complement of a given subject.
• Web endpoint for the decoding or conversion from and to several formats.

Please be informed that we recommend you to use docker as much as possible.

To manually install this project, simply run the following:

$ git clone https://github.com/PyFunceble/web-worker.git pyfunceble-web-worker
$ cd pyfunceble-web-worker

## Install by choosing your PyFunceble flavor.
## For PyFunceble run:
$ pip3 install --user .[pyfunceble]
## For PyFunceble-dev run:
$ pip3 install --user .[pyfunceble-dev]

This project provides 2 docker images that you can pull:

1. ghcr.io/pyfunceble/web-worker/web-worker is built with PyFunceble (stable).
2. ghcr.io/pyfunceble/web-worker/web-worker-dev is built with PyFunceble-dev.

To pull the image that has been built on top of PyFunceble (stable):

$ docker pull ghcr.io/pyfunceble/web-worker/web-worker:latest

To pull the image that has been built on top of PyFunceble-dev:

$ docker pull ghcr.io/pyfunceble/web-worker/web-worker-dev:latest

To build the Containerfile provided, simply run or adapt the following:

$ docker build -t pyfunceble_webworker -f [Containerfile] .

By default, this project will be built against the latest available version of PyFunceble. If you want to change that behavior, simply add the following build arguments:

--build-arg PYFUNCEBLE_VERSION=[PyFunceble Version]

Please choose your method to start the project.

Once the project running, you may visit the /v1/docs or /v1/rdocs endpoint from your browser to document yourself about all available endpoints.

To start the project, simply run or adapt the following:

$ cd pyfunceble-web-worker
$ uvicorn pyfunceble_webworker.main:app --host 0.0.0.0 --port 80

To start the project after pulling it from the GitHub Packages, simply run or adapt the following:

$ docker run -v pyfunceble-worker-data:/data -d --name [my-awesome-name] -p [my-port]:80 ghcr.io/pyfunceble/web-worker/web-worker:latest

To start the project, simply run or adapt the following:

$ docker run -v pyfunceble-worker-data:/data -d --name [my-awesome-name] -p [my-port]:80 pyfunceble_webworker:latest

In addition to:

• any PyFunceble environment variable
• any uvicorn-gunicorn-fastapi environment variable - when using the docker image

the following are available for you to use.

If you chose to manually run this project, you are invited to use a .env file to declare your environment variables.

To configure PyFunceble, simply create a .PyFunceble.overwrite.yaml file at the root of the given data directory. The data directory is by default /data under the docker container.

The .PyFunceble.overwrite.yaml, will be automatically merged into the PyFunceble configuration module. Meaning that you can define anything that PyFunceble knows.

For example:

dns:
  server:
    - 192.168.1.1

Will overwrite the DNS server used by PyFunceble with the given one.

This project, PyFunceble, Dead-Hosts, adblock-decoder and all other analog projects are powered by free time and a lot of coffee!

This project helps you and you have to possibility to help back financially? Sponsor @funilrys through the GitHub Sponsor program by clicking the image below!

Copyright 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025 Nissar Chababy

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.