Skip to content

funilrys/PyFunceble

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

image

The tool to check the availability or syntax of domain, IP or URL

image image image image image

image image image

PyFunceble aims to provide an accurate availability check through the usage of multiple sources which are for example - to only list a few:

  • the WHOIS record(s).
  • the DNS record(s).
  • the HTTP status code.

PyFunceble can be included in your existing project through:

  • its standard built-in CLI implementation.
  • its Python API.
  • the PyFunceble web-worker project that provides the core functionalities of PyFunceble behind a web API.

The PyFunceble CLI can test from a hosts file, a plain list of subjects, an AdBlock filter list or even an RPZ record.

As of today, PyFunceble is running actively - if not daily - within several servers, laptops, PCs, and Raspberry Pis. It is even used - thanks to our auto continue mechanism - with CI engines like GitHub Action, Travis CI, or GitLab CI.

Happy testing with PyFunceble!

image

Table of Content

Installation

Packages & Versioning

This project follows the semver standard.

PyFunceble is distributed through 2 packages that reflects our 2 main development and deployment branches. Both packages are stable but with 2 different phylosophies. Therefore, the choice is up to you.

The 2 packages are pyfunceble and pyfunceble-dev.

If you want a stable but mature, and slowly updating package, you should install the pyfunceble package. It reflects the master branch which only get updated once the new features and bugfixes of pyfunceble-dev are tested long enough to be considered mature.

On the other hand, if you want a stable but fast updating package, you should install the pyfunceble-dev package. It reflects the dev branch which get updated frequently to allow the community to provide feedbacks as soon as possible.

Recommendation: For most people the pyfunceble package should be sufficient. But if you want to help the community or always want to have the latest features and bugfix as soon as possible, you should prefer the pyfunceble-dev package.

PyPi - Python Package Index

Installing from the Python Package Index is for most people the prefered one - after the OS specific packages (see below).

Here is an overview of the packages and where they are hosted.

Package PyPi Link
pyfunceble https://pypi.org/project/PyFunceble
pyfunceble-dev https://pypi.org/project/PyFunceblee-dev

Optional Dependencies

The following dependencies are optional and can be installed if you need them.

Dependency Description
all Install all functional dependencies. Basically all but dev, test and docs. When a binary and non binary version is available, the binary version is installed.
full Install all dependencies listed below. When a binary and non binary version is available, the binary version is installed.
psql, postgresql Build and install the dependencies required to interact with PostgreSQL.
psql-binary, postgresql-binary Install the dependencies required to interact with PostgreSQL - from binary.
docs Install the dependencies required to build the documentation.
test Install the dependencies required to run the tests.
dev Install the dependencies required to develop PyFunceble.

They are intended to be installed through the following syntax:

pip3 install --user {pkg}[{dependency}]

As an example if you want to install the docs and test dependencies, you should run:

pip3 install --user pyfunceble[docs,test]

pyfunceble

You can install the pyfunceble through pip3:

pip3 install --user pyfunceble

pyfunceble-dev

You can install the pyfunceble-dev package through pip3:

pip3 install --user pyfunceble-dev

If you want to help and use the unstable pre-releases, you should install with the --pre argument.

pip3 install --user --pre pyfunceble-dev

Container Image Registry

Installing from a Container Image Registry is the way to go if you are in a hurry or always want the best from the beat without having to look if an update is available. πŸ˜„

Here is an overview of the packages and where they are hosted.

Host Package Link
Docker Hub pyfunceble https://hub.docker.com/r/pyfunceble/pyfunceble
Docker Hub pyfunceble-dev https://hub.docker.com/r/pyfunceble/pyfunceble-dev

pyfunceble

Docker Hub

You can install the pyfunceble image from Docker Hub through docker:

docker pull pyfunceble/pyfunceble

pyfunceble-dev

Docker Hub

You can install the pyfunceble-dev image from Docker Hub through docker:

docker pull pyfunceble/pyfunceble-dev

ArchLinux

For the pyfunceble package:

aur-helper -S pyfunceble
pyfunceble --version

For the pyfunceble-dev package:

aur-helper -S pyfunceble-dev
pyfunceble --version

Git Repository

Installing from a Git Repository with pip3 is not recommended for general user as you will get the latest development patches even before they get published. But if you are one of those who always want to be in sync with the latest development patches, this is probably for you.

Here is an overview of the packages and where they are hosted.

Host Package Repository
GitHub pyfunceble git+https://github.com/funilrys/PyFunceble.git@master#egg=PyFunceble
GitHub pyfunceble-dev git+https://github.com/funilrys/PyFunceble.git@dev#egg=PyFunceble-dev
GitLab pyfunceble git+https://gitlab.com/funilrys/PyFunceble.git@master#egg=PyFunceble
GitLab pyfunceble-dev git+https://gitlab.com/funilrys/PyFunceble.git@dev#egg=PyFunceble-dev

pyfunceble

GitHub

You can install the pyfunceble package from GitHub through pip3:

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

GitLab

You can install the pyfunceble package from GitLab through pip3:

pip3 install --user git+https://gitlab.com/funilrys/PyFunceble.git@master#egg=PyFunceble

pyfunceble-dev

GitHub

You can install the pyfunceble-dev package from GitHub through pip3:

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

GitLab

You can install the pyfunceble-dev package from GitLab through pip3:

pip3 install --user git+https://gitlab.com/funilrys/PyFunceble.git@dev#egg=PyFunceble-dev

From Source

Installing from source is not recommended at all as you may need to keep the repository up-to-date by yourself.

Here is an overview of the packages and where they are hosted.

Host Package Branch Repository
GitHub pyfunceble master https://github.com/funilrys/PyFunceble/tree/master
GitHub pyfunceble-dev dev https://github.com/funilrys/PyFunceble/tree/dev
GitLab pyfunceble master https://gitlab.com/funilrys/PyFunceble/tree/master
GitLab pyfunceble-dev dev https://gitlab.com/funilrys/PyFunceble/tree/master

You can install the package from source through pip3:

pip3 install --user https://github.com/funilrys/PyFunceble/archive/{{branch}}.zip # From Github
pip3 install --user https://gitlab.com/funilrys/PyFunceble/-/archive/{{branch}}/PyFunceble-{{branch}}.zip # From GitLab

Usage

Common Setups

If you installed PyFunceble through any other method that doesn't involve a container image, you can use PyFunceble "normally" through the pyfunceble executable.

pyfunceble --help

Container Image Setups

If you installed PyFunceble through the container image registry method, you can run pyfunceble through:

docker run -it pyfunceble/pyfunceble[-dev] --help

Beware: if the first parameter starts with a slash (/), the entrypoint will assume that you want to run a command within the container.

Data Persitence

If you wish to persist your data, you simply have to mount a volume to the /home/pyfunceble directory.

Example:

mkdir -p pyf-data
echo "example.com" > pyf-data/test.list

docker run -v pyf-data:/home/pyfunceble -it pyfunceble/pyfunceble[-dev] -f /home/pyf-data/test.list

Common Examples

Here are some examples to get started.

Check the availability of 'example.com'.

$ pyfunceble -d example.com

Check the availability of 'example.com' with a simple (stdout) output.

$ pyfunceble -s -d example.com

Check the availability of 'example.com' with extended (stdout) output.

$ pyfunceble -a -d example.com

Check the availability of 'example.com' and 'example.org'.

$ pyfunceble -d example.com example.org

Check the availability of 'https://example.com'.

$ pyfunceble -u https://example.com

Check the availability of 'https://example.com' and 'https://example.org'.

$ pyfunceble -u https://example.com https://example.com

Check the syntax of 'example.com'.

$ pyfunceble --syntax -d example.com

Check the reputation of 'example.com'.

$ pyfunceble --reputation -d example.com

Check the availability of all subjects in the 'myhosts' file.

$ pyfunceble -f myhosts

Check the availability of all subjects in the 'myhosts' and 'yourhosts' files.

$ pyfunceble -f myhosts yourhosts

Check the availability of all (decoded) subject of the adblock filter list 'myadblock'.

$ pyfunceble --adblock -f myadblock

Documentation as the place to be!

Want to know more about details PyFunceble? I invite you to read the documentation at docs.pyfunceble.com!

Want a local copy? I get you covered!

If you want to run the documentation locally, you can do so by following the instructions below.

Through Docker:

docker run -it -p 8080:80 pyfunceble/docs
# Open Documentation with browser: http://localhost:8080
palemoon http://127.0.0.1:8000

From source:

# Install dependencies.
pip install --user .[docs]
# Serve documentation locally.
mkdocs serve
# Open Documentation with browser.
palemoon http://127.0.0.1:8000

NOTE: You are also invited to submit changes and improvement to the documentation through a new Pull Request.

Supporting the 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!

image

Contributors

Thanks to those awesome peoples for their awesome and crazy idea(s), contribution(s) and or issue report which made or make PyFunceble a better tool.

Avinash Reddy
Avinash Reddy

πŸ›
BigDargon
BigDargon

πŸ› πŸ€” πŸ’¬ πŸ‘€ πŸ”£ ⚠️
Fanboynz
Fanboynz

πŸ› πŸ€” πŸ’΅ ⚠️ πŸ““
Haris Guőić
Haris Guőić

πŸ“– ️️️️♿️ πŸ”§ ⚠️ πŸ“Ή βœ… πŸ’»
Imre Eilertsen
Imre Eilertsen

️️️️♿️ πŸ› πŸ”£ πŸ’‘ πŸ’΅ πŸ€” πŸ“£ πŸ’¬ πŸ‘€ πŸ”§ ⚠️ πŸ““
Kowith Singkornkeeree
Kowith Singkornkeeree

πŸ›
Mitchell Krog
Mitchell Krog

️️️️♿️ πŸ› πŸ“ πŸ’» πŸ–‹ πŸ”£ πŸ“– 🎨 πŸ’‘ πŸ” πŸ€” πŸš‡ πŸ§‘β€πŸ« πŸ“¦ πŸ”Œ πŸ“£ πŸ’¬ πŸ‘€ πŸ”§ ⚠️ βœ… πŸ“’ πŸ““
Nilsonfsilva
Nilsonfsilva

πŸ› πŸš‡ πŸ“¦ πŸ”§ ⚠️
Odyseus
Odyseus

πŸ› ⚠️
Reza Rizqullah
Reza Rizqullah

🎨 πŸ’»
Samuel Bishop
Samuel Bishop

πŸ› πŸ€”
ScriptTiger
ScriptTiger

πŸ› πŸ€” ⚠️
Stephan van Ruth
Stephan van Ruth

πŸ› ⚠️
Steven Black
Steven Black

πŸ€” πŸ’΅
T145
T145

πŸ› πŸ€”
WaLLy3K
WaLLy3K

πŸ› πŸ€”
Yuki2718
Yuki2718

πŸ› ⚠️
Zachinquarantine
Zachinquarantine

πŸ’»
ZeroDot1
ZeroDot1

πŸ› πŸ€” πŸ’¬ ⚠️ πŸ’»
avatartw
avatartw

πŸ›
dnmTX
dnmTX

πŸ› πŸ€” πŸ’¬ πŸ‘€ πŸ”£ ⚠️
gwarser
gwarser

πŸ› πŸ”£ ⚠️
hawkeye116477
hawkeye116477

πŸ›
jawz101
jawz101

πŸ› πŸ€” πŸ’¬ πŸ”£
keczuppp
keczuppp

πŸ› πŸ€” πŸ’¬ ⚠️ πŸ”£
opav
opav

πŸ› ⚠️
rusty-snake
rusty-snake

πŸ› πŸ“–
smed79
smed79

πŸ› πŸ€” πŸ’» πŸ’¬ ⚠️
speedmann
speedmann

πŸ› ⚠️
spirillen
spirillen

️️️️♿️ πŸ› πŸ’» πŸ–‹ πŸ”£ πŸ“– πŸ’‘ πŸ€” 🚧 πŸ§‘β€πŸ« πŸ“£ πŸ’¬ πŸ‘€ πŸ”§ ⚠️ βœ… πŸ“’ πŸ““
watchman-pypi
watchman-pypi

πŸ›
xxcriticxx
xxcriticxx

πŸ› πŸ€” ⚠️

Special Thanks

Thanks to those awesome organization(s), tool(s) and or people(s) for

  • Their awesome documentation
  • Their awesome repository
  • Their awesome tool/software/source code
  • Their breaking reports
  • Their contributions
  • Their current work/purpose
  • Their promotion of Py-Funceble
  • Their support
  • Their testings reports

which helped and/or still help me build, test and or make PyFunceble a better tool.

License

Copyright 2017, 2018, 2019, 2020, 2022, 2023, 2024 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

    https://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.