proxyjar 0.1.0

A library to acquire proxies, written in Python.

🍯 ProxyJar

ProxyJar is a tool for automatically collecting and verifying proxies from across the web. It saves you the hassle of manual searching by scraping fresh HTTP, HTTPS, and SOCKS proxies from multiple public sources and consolidating them into a single, clean list. Designed for simplicity and speed, it includes a built-in checker to filter out dead links, ensuring you only use active, high-quality connections. Whether you are web scraping or performing network tests, you can get a reliable proxy pool up and running with just a few lines of code.

---

📦 Installation

Install the package directly via pip:

pip install proxyjar

Note: Ensure you have Python 3.7 or higher installed.

---

🛠 Usage

Basic Collection

Get a list of verified proxies with default settings:

>>> from proxyjar import acquireProxies
>>> acquireProxies(1)
{'xxx.160.215.xxx:xxxx': {'protocol': 'https'}}
>>> acquireProxies(2)
{'xxx.96.240.xxx:xxxx': {'protocol': 'https'}, 'xxx.191.xxx.1xx:1080': {'protocol': 'https'}}

Command line

Export your freshly harvested list for use in other tools (like Curl or Scrapy):

$ proxyjar -h
Usage: proxyjar [-h] [-V] [-v] [-n COUNT] [-t MAXTIMEOUT] [-f FILENAME] [-r TYPE] [--bottleneck] [-p PROTOCOLS] [--ip IPv4] [URLs]

Description:
A Command-line tool to acquire proxies, written in Python.

Positional Arguments:
  URLs           URL(s) of sites, for request attempts. (Optional)

Options:
  -h, --help     Display information, options and usage.
  -V, --version  Display proxyjar version.
  -v, --verbose  Display progess and information.
  -n COUNT       Maximum number of proxies to fetch.
  -t MAXTIMEOUT  Maximum response time in seconds for each proxy.
                 Range: [1, 10]; Default: 3 seconds.
  -f FILENAME    Redirect standard output to file.
                 Filename supports strftime formatting.
  -r TYPE        Type of output formatting.
                 Options: tabular (default), list, dict, less.
                 list & dict follow JSON syntax.
  --bottleneck   Bottleneck process, limiting the number of threads.
                 Use it for slow devices or network.
  -p PROTOCOLS   Types of proxies to fetch.
                 Options: http, https, socks (socks4, socks5)
                 Default: all.
  --ip IPv4      Use it when prompted to.

Report Issues at 
$ py -m proxyjar -n 10

---

📋 Configuration Options

Parameter / Option	Default	Type	Description
protocol	all	str / list[str]	Proxy protocol: http, https, socks4, socks5.
maximum	—	int	Maximum number of proxies to return.
sites	—	str / list[str]	Websites to test proxies against.
returnType	dict	str / type	Return format: dict (default) or list.
maxTimeout	3	int	Timeout per proxy (range: 1–10 seconds).
verbose	—	bool	Display progress and debug information.
bottleneck	—	bool	Limit number of concurrent threads.
ipv4	—	str	Host IPv4 address (used for fail-safe).

---

Return Type

Item	Description
return	Proxies
rtype	dict[str, dict[str, str]] OR list[dict[str, str]]

---

Notes

Feature	Description
Flexible Parameters	Accepts up to 4 positional arguments: maximum, sites, protocol, returnType
Order	These parameters can be passed in any order

---

📜 License

This project is licensed under the GNU General Public License v3.0 (GPLv3). This means:

• You may use, modify, and distribute this software.
• Any derivative work must also be licensed under GPLv3 and remain open source.

---

⚠️ Ethical & Legal Disclaimer

ProxyJar is intended for educational and ethical research purposes only.

• The author is not responsible for any misuse of this tool.
• Scraping websites may violate their Terms of Service.
• Public proxies are inherently insecure; never use them for sensitive data (banking, logins, etc.).

---

🤝 Contributing

Contributions make the open-source community an amazing place to learn and create!

Author: @iamokish
Project Link: https://github.com/iamokish/proxyjar