<div align="center">
<img src="https://user-images.githubusercontent.com/71208042/226755154-ed482978-89a3-4d2b-8a49-78f6ca07c290.png" alt="Ballyregan" width=550/>
<h3><em>Find fetch & validate free proxies fast.</em></h3>
<p>
<a href="https://pypi.org/project/ballyregan" target="_blank">
<img src="https://img.shields.io/pypi/v/ballyregan?label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/ballyregan" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/ballyregan.svg?color=%2334D058" alt="Supported Python versions">
</a>
<a href="https://pypi.org/project/ballyregan" target="_blank">
<img src="https://img.shields.io/badge/license-Apache%202.0-yellow" alt="License: Apache 2.0">
</a>
</p>
</div>
---
Ballyregan is a super fast proxy fetcher.
<br>
It provides a python package and an easy-to-use CLI to help you fetch <bFree Tested Proxies</b> fast, and keep your privacy.
<br>
---
Key features:
* **Fetch** free tested proxies super fast using the [ProxyFetcher](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/fetcher.py)
* **Validate** your own proxies using the [ProxyValidator](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/validator.py)
* **Filter** custom proxy list by protocol & anonymity using the [ProxyFilterer](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/filterer.py)
---
## How does it work?
When you use the ProxyFetcher to fetch a proxy, it performs several steps:
1. Gather all the available proxies from a list of built-in providers (each provider gathers its own and returns it to the fetcher).
- > Provider - any website that serves free proxy lists (e.g https://free-proxy-list.net).
2. Filter all the gathered proxies by the given protocols and anonymities (if exist).
3. Validate the filtered proxies and return them.
<br>
> **Note** <br>
> You can write and append your own custom providers and pass them to the ProxyFetcher class as an attribute. <br>
> Every custom proxy provider must implement the [IProxyProvider](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/providers/interface.py) base interface.
<br>
## Behind the scenes
Fetching a proxy is an [IO bound operation](https://en.wikipedia.org/wiki/I/O_bound) that depends on the network. A common approach for this problem is performing your network requests async. <br>
After digging a bit, and testing Threads, Greenlets, and async operations, we decided to go the async way. <br>
To perform async HTTP requests, ballyregan uses [aiohttp](https://docs.aiohttp.org/en/stable/) and [asyncio](https://docs.python.org/3/library/asyncio.html),
as <em>"asyncio is often a perfect fit for IO-bound and high-level structured network code."</em> (from asyncio docs). <br>
By using the power of async HTTP requests, ballyregan can validate thousands of proxies really fast. <br>it to the ProxyFetcher class as an attribute. <br>
> Every custom proxy provider must implement the [IProxyProvider](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/providers/interface.py) base interface.
---
## Install
All you need to do is install the package from pypi, and it will automatically install the CLI for you.
```sh
pip install ballyregan
```
## Usage
### 📦 Package
#### Create a fetcher instance
```python
from ballyregan import ProxyFetcher
# Setting the debug mode to True, defaults to False
fetcher = ProxyFetcher(debug=True)
```
#### Get one proxy
```python
proxy = fetcher.get_one()
print(proxy)
```
#### Get multiple proxies
```python
proxies = fetcher.get(limit=4)
print(proxies)
```
#### Get proxies by filters
```python
from ballyregan.models import Protocols, Anonymities
proxies = fetcher.get(
limit=4,
protocols=[Protocols.HTTPS, Protocols.SOCKS5],
anonymities=[Anonymities.ELITE]
)
print(proxies)
```
### 💻 CLI
#### Need some help?
```sh
ballyregan get --help
```
#### Get one proxy
```sh
ballyregan get
```
#### Get all proxies
```sh
ballyregan get --all
```
#### Use debug mode
```sh
ballyregan --debug get [OPTIONS]
```
#### Format output to json
```sh
ballyregan get -o json
```
#### Get proxies by limit
```sh
ballyregan get -l 4
```
#### Get proxies by filters
```sh
ballyregan get -l 4 -p https -p socks5 -a elite
```
---
## 📝 License
Copyright © 2022 [Idan Daniel](https://github.com/idandaniel).<br />
This project is [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) licensed.
Raw data
{
"_id": null,
"home_page": "",
"name": "ballyregan",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "python,proxy,http-proxy,https-proxy,socks-proxy,proxy-list,proxy-checker,python-proxy,proxy-fetcher,free-proxy,get-proxy,proxy-finder,find-proxy",
"author": "idandaniel",
"author_email": "idandaniel12@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/36/01/9f9f9b6e042cc7d0394b7856d15ec762534b076adb903dc47371c6879010/ballyregan-1.0.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"https://user-images.githubusercontent.com/71208042/226755154-ed482978-89a3-4d2b-8a49-78f6ca07c290.png\" alt=\"Ballyregan\" width=550/>\n<h3><em>Find fetch & validate free proxies fast.</em></h3>\n\n<p>\n <a href=\"https://pypi.org/project/ballyregan\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/ballyregan?label=pypi%20package\" alt=\"Package version\">\n </a>\n <a href=\"https://pypi.org/project/ballyregan\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/ballyregan.svg?color=%2334D058\" alt=\"Supported Python versions\">\n </a>\n <a href=\"https://pypi.org/project/ballyregan\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/license-Apache%202.0-yellow\" alt=\"License: Apache 2.0\">\n </a>\n</p>\n</div>\n\n---\n\nBallyregan is a super fast proxy fetcher.\n<br>\nIt provides a python package and an easy-to-use CLI to help you fetch <bFree Tested Proxies</b> fast, and keep your privacy.\n<br>\n\n---\n\nKey features:\n * **Fetch** free tested proxies super fast using the [ProxyFetcher](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/fetcher.py)\n * **Validate** your own proxies using the [ProxyValidator](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/validator.py)\n * **Filter** custom proxy list by protocol & anonymity using the [ProxyFilterer](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/filterer.py)\n\n---\n\n## How does it work?\nWhen you use the ProxyFetcher to fetch a proxy, it performs several steps:\n1. Gather all the available proxies from a list of built-in providers (each provider gathers its own and returns it to the fetcher).\n\n - > Provider - any website that serves free proxy lists (e.g https://free-proxy-list.net).\n\n2. Filter all the gathered proxies by the given protocols and anonymities (if exist).\n3. Validate the filtered proxies and return them.\n\n<br>\n\n> **Note** <br>\n> You can write and append your own custom providers and pass them to the ProxyFetcher class as an attribute. <br>\n> Every custom proxy provider must implement the [IProxyProvider](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/providers/interface.py) base interface.\n\n<br>\n\n## Behind the scenes\nFetching a proxy is an [IO bound operation](https://en.wikipedia.org/wiki/I/O_bound) that depends on the network. A common approach for this problem is performing your network requests async. <br>\nAfter digging a bit, and testing Threads, Greenlets, and async operations, we decided to go the async way. <br>\nTo perform async HTTP requests, ballyregan uses [aiohttp](https://docs.aiohttp.org/en/stable/) and [asyncio](https://docs.python.org/3/library/asyncio.html),\nas <em>\"asyncio is often a perfect fit for IO-bound and high-level structured network code.\"</em> (from asyncio docs). <br>\nBy using the power of async HTTP requests, ballyregan can validate thousands of proxies really fast. <br>it to the ProxyFetcher class as an attribute. <br>\n> Every custom proxy provider must implement the [IProxyProvider](https://github.com/idandaniel/ballyregan/blob/main/src/ballyregan/providers/interface.py) base interface.\n\n---\n\n## Install\nAll you need to do is install the package from pypi, and it will automatically install the CLI for you.\n\n```sh\npip install ballyregan\n```\n\n## Usage\n\n### \ud83d\udce6 Package\n\n#### Create a fetcher instance\n```python\nfrom ballyregan import ProxyFetcher\n\n# Setting the debug mode to True, defaults to False\nfetcher = ProxyFetcher(debug=True)\n```\n\n#### Get one proxy\n```python\nproxy = fetcher.get_one()\nprint(proxy)\n```\n\n#### Get multiple proxies\n```python\nproxies = fetcher.get(limit=4)\nprint(proxies)\n```\n\n#### Get proxies by filters\n```python\nfrom ballyregan.models import Protocols, Anonymities\n\nproxies = fetcher.get(\n limit=4,\n protocols=[Protocols.HTTPS, Protocols.SOCKS5],\n anonymities=[Anonymities.ELITE]\n)\nprint(proxies)\n```\n\n### \ud83d\udcbb CLI\n\n#### Need some help?\n```sh\nballyregan get --help\n```\n\n#### Get one proxy\n```sh\nballyregan get\n```\n\n#### Get all proxies\n```sh\nballyregan get --all\n```\n\n#### Use debug mode\n```sh\nballyregan --debug get [OPTIONS]\n```\n\n#### Format output to json\n```sh\nballyregan get -o json\n```\n\n#### Get proxies by limit\n```sh\nballyregan get -l 4\n```\n\n#### Get proxies by filters\n```sh\nballyregan get -l 4 -p https -p socks5 -a elite\n```\n\n---\n\n## \ud83d\udcdd License\n\nCopyright \u00a9 2022 [Idan Daniel](https://github.com/idandaniel).<br />\nThis project is [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) licensed.\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Find fetch & validate free proxies fast.",
"version": "1.0.6",
"split_keywords": [
"python",
"proxy",
"http-proxy",
"https-proxy",
"socks-proxy",
"proxy-list",
"proxy-checker",
"python-proxy",
"proxy-fetcher",
"free-proxy",
"get-proxy",
"proxy-finder",
"find-proxy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "344e2b72708398d509457ed6e08783775d18ec2257afc6527c42b5982b2902ea",
"md5": "29d2028db4c3daec21985d098bf33073",
"sha256": "c7aa546ea99fc70b3457343f30327bc24d3c6c767e081e7e279c8e7fac2ed167"
},
"downloads": -1,
"filename": "ballyregan-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29d2028db4c3daec21985d098bf33073",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 20056,
"upload_time": "2023-03-23T07:10:21",
"upload_time_iso_8601": "2023-03-23T07:10:21.695818Z",
"url": "https://files.pythonhosted.org/packages/34/4e/2b72708398d509457ed6e08783775d18ec2257afc6527c42b5982b2902ea/ballyregan-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "36019f9f9b6e042cc7d0394b7856d15ec762534b076adb903dc47371c6879010",
"md5": "69365d2dd9139eedab129c1c56ee1008",
"sha256": "b850f8d0d733a28e11a938a188795698e625cf30986485f1661e83ef136eb65f"
},
"downloads": -1,
"filename": "ballyregan-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "69365d2dd9139eedab129c1c56ee1008",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 15528,
"upload_time": "2023-03-23T07:10:23",
"upload_time_iso_8601": "2023-03-23T07:10:23.377645Z",
"url": "https://files.pythonhosted.org/packages/36/01/9f9f9b6e042cc7d0394b7856d15ec762534b076adb903dc47371c6879010/ballyregan-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-23 07:10:23",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "ballyregan"
}
JSON