pharox 0.3.0__tar.gz

pharox-0.3.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 José Zacarías Flores
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pharox-0.3.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.3
+Name: pharox
+Version: 0.3.0
+Summary: A modern library for managing, leasing, and monitoring proxy pools.
+License: MIT
+Author: fzaca zaca03zaca@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: socks
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.11.7,<3.0.0)
+Project-URL: Repository, https://github.com/fzaca/pharox
+Description-Content-Type: text/markdown
+
+# Pharox Core
+
+[![Python Versions](https://img.shields.io/pypi/pyversions/pharox.svg)](https://pypi.org/project/pharox/)
+[![PyPI Version](https://img.shields.io/pypi/v/pharox.svg)](https://pypi.org/project/pharox/)
+[![CI Status](https://github.com/fzaca/pharox/actions/workflows/test.yml/badge.svg)](https://github.com/fzaca/pharox/actions/workflows/test.yml)
+[![License](https://img.shields.io/pypi/l/pharox.svg)](https://github.com/fzaca/pharox/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Docs](https://img.shields.io/badge/docs-shadcn-blue?logo=mkdocs&logoColor=white)](https://fzaca.github.io/pharox/)
+
+The foundational Python toolkit for building robust proxy management systems.
+
+`pharox` provides pure, domain-agnostic business logic for managing the
+entire lifecycle of network proxies. The library is designed as a reusable
+dependency for any Python application that needs to acquire, lease, and monitor
+proxies without inheriting opinionated service architecture.
+
+- 📚 Documentation: <https://fzaca.github.io/pharox/>
+
+---
+
+## Key Features
+
+*   **Proxy Leasing System:** A powerful system to "lease" proxies to consumers, with support for exclusive, shared (concurrent), and unlimited usage.
+*   **Pluggable Storage:** A clean interface (`IStorage`) that decouples the core logic from the database, allowing you to "plug in" any storage backend (e.g., in-memory, PostgreSQL, MongoDB).
+*   **Health Checking Toolkit:** A protocol-aware `HealthChecker` with configurable options for HTTP, HTTPS, and SOCKS proxies.
+*   **Modern & Type-Safe:** Built with Python 3.10+, Pydantic v2, and a 100% type-annotated codebase.
+*   **Toolkit, Not a Framework:** Provides focused utilities that can be embedded inside your own scripts, workers, or services without imposing a runtime.
+
+## Installation
+
+You can install `pharox` directly from PyPI:
+
+```bash
+pip install pharox
+```
+
+## Quickstart Example
+
+Here is a simple example of how to use `pharox` with the default `InMemoryStorage` to acquire and release a proxy.
+
+```python
+from pharox import (
+    InMemoryStorage,
+    Proxy,
+    ProxyManager,
+    ProxyPool,
+    ProxyStatus,
+)
+
+# 1. Setup the storage and manager
+storage = InMemoryStorage()
+manager = ProxyManager(storage=storage)
+
+# 2. Seed the storage with necessary data for the example
+# In a real application, you would load this from your database.
+
+# The manager uses a "default" consumer if none is specified and will
+# auto-register it in the storage when first needed.
+
+# Create a pool and a proxy
+pool = ProxyPool(name="latam-residential")
+storage.add_pool(pool)
+
+proxy = Proxy(
+    host="1.1.1.1",
+    port=8080,
+    protocol="http",
+    pool_id=pool.id,
+    status=ProxyStatus.ACTIVE,
+)
+storage.add_proxy(proxy)
+
+# 3. Acquire a proxy from the pool (without specifying a consumer)
+print(f"Attempting to acquire a proxy from pool '{pool.name}'...")
+lease = manager.acquire_proxy(pool_name=pool.name, duration_seconds=60)
+
+if lease:
+    leased_proxy = storage.get_proxy_by_id(lease.proxy_id)
+    print(f"Success! Leased proxy: {leased_proxy.host}:{leased_proxy.port}")
+    print(f"Lease acquired by consumer ID: {lease.consumer_id}")
+
+    # ... do some work with the proxy ...
+
+    # 4. Release the lease when done
+    print("\nReleasing the lease...")
+    manager.release_proxy(lease)
+    print("Lease released.")
+
+    proxy_after_release = storage.get_proxy_by_id(lease.proxy_id)
+    print(f"Proxy lease count after release: {proxy_after_release.current_leases}")
+else:
+    print("Failed to acquire a proxy. None available.")
+```
+
+### Filtering and Geospatial Matching
+
+`ProxyFilters` let you target proxies by provider metadata or geographic
+proximity. The storage layer handles the matching logic, including radius-based
+searches using latitude and longitude.
+
+```python
+from pharox import ProxyFilters
+
+filters = ProxyFilters(
+    country="AR",
+    source="fast-provider",
+    latitude=-34.6,
+    longitude=-58.38,
+    radius_km=50,
+)
+
+lease = manager.acquire_proxy(
+    pool_name="latam-residential",
+    consumer_name="team-madrid",
+    filters=filters,
+)
+
+if lease:
+    print("Got a proxy close to Buenos Aires!")
+```
+
+### Health Checks Across Protocols
+
+Use `HealthChecker` to verify connectivity through HTTP, HTTPS, or SOCKS proxies.
+Health checks are configurable via `HealthCheckOptions`, letting you define
+target URLs, expected status codes, retry counts, and latency thresholds.
+
+```python
+from pharox import HealthCheckOptions, HealthChecker, ProxyStatus
+
+checker = HealthChecker()
+options = HealthCheckOptions(
+    target_url="https://example.com/status/204",
+    expected_status_codes=[204],
+    attempts=2,
+    slow_threshold_ms=1500,
+)
+
+proxy = storage.get_proxy_by_id(lease.proxy_id)
+health = await checker.check_proxy(proxy, options=options)
+
+if health.status in {ProxyStatus.ACTIVE, ProxyStatus.SLOW}:
+    print("Proxy ready for workloads")
+else:
+    print(f"Proxy inactive: {health.error_message}")
+```
+
+## Embedding the Toolkit
+
+`pharox` is intentionally agnostic about where it runs. Typical usage
+includes:
+
+* **Automation scripts and workers** leasing proxies with `ProxyManager` and
+  performing health probes before dispatching workloads.
+* **Custom services** that provide APIs or dashboards on top of the toolkit by
+  implementing the `IStorage` contract for their own databases.
+* **Standalone applications** that rely on the in-memory storage adapter for
+  quick tasks or testing harnesses.
+
+The in-memory adapter included with the package is great for development. For
+production, implement `IStorage` to connect the toolkit to your own persistence
+layer.
+
+## Contributing
+
+Contributions are welcome! Please see the `CONTRIBUTING.md` file for details on how to set up your development environment, run tests, and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.
+

pharox-0.3.0/README.md

@@ -0,0 +1,170 @@
+# Pharox Core
+
+[![Python Versions](https://img.shields.io/pypi/pyversions/pharox.svg)](https://pypi.org/project/pharox/)
+[![PyPI Version](https://img.shields.io/pypi/v/pharox.svg)](https://pypi.org/project/pharox/)
+[![CI Status](https://github.com/fzaca/pharox/actions/workflows/test.yml/badge.svg)](https://github.com/fzaca/pharox/actions/workflows/test.yml)
+[![License](https://img.shields.io/pypi/l/pharox.svg)](https://github.com/fzaca/pharox/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Docs](https://img.shields.io/badge/docs-shadcn-blue?logo=mkdocs&logoColor=white)](https://fzaca.github.io/pharox/)
+
+The foundational Python toolkit for building robust proxy management systems.
+
+`pharox` provides pure, domain-agnostic business logic for managing the
+entire lifecycle of network proxies. The library is designed as a reusable
+dependency for any Python application that needs to acquire, lease, and monitor
+proxies without inheriting opinionated service architecture.
+
+- 📚 Documentation: <https://fzaca.github.io/pharox/>
+
+---
+
+## Key Features
+
+*   **Proxy Leasing System:** A powerful system to "lease" proxies to consumers, with support for exclusive, shared (concurrent), and unlimited usage.
+*   **Pluggable Storage:** A clean interface (`IStorage`) that decouples the core logic from the database, allowing you to "plug in" any storage backend (e.g., in-memory, PostgreSQL, MongoDB).
+*   **Health Checking Toolkit:** A protocol-aware `HealthChecker` with configurable options for HTTP, HTTPS, and SOCKS proxies.
+*   **Modern & Type-Safe:** Built with Python 3.10+, Pydantic v2, and a 100% type-annotated codebase.
+*   **Toolkit, Not a Framework:** Provides focused utilities that can be embedded inside your own scripts, workers, or services without imposing a runtime.
+
+## Installation
+
+You can install `pharox` directly from PyPI:
+
+```bash
+pip install pharox
+```
+
+## Quickstart Example
+
+Here is a simple example of how to use `pharox` with the default `InMemoryStorage` to acquire and release a proxy.
+
+```python
+from pharox import (
+    InMemoryStorage,
+    Proxy,
+    ProxyManager,
+    ProxyPool,
+    ProxyStatus,
+)
+
+# 1. Setup the storage and manager
+storage = InMemoryStorage()
+manager = ProxyManager(storage=storage)
+
+# 2. Seed the storage with necessary data for the example
+# In a real application, you would load this from your database.
+
+# The manager uses a "default" consumer if none is specified and will
+# auto-register it in the storage when first needed.
+
+# Create a pool and a proxy
+pool = ProxyPool(name="latam-residential")
+storage.add_pool(pool)
+
+proxy = Proxy(
+    host="1.1.1.1",
+    port=8080,
+    protocol="http",
+    pool_id=pool.id,
+    status=ProxyStatus.ACTIVE,
+)
+storage.add_proxy(proxy)
+
+# 3. Acquire a proxy from the pool (without specifying a consumer)
+print(f"Attempting to acquire a proxy from pool '{pool.name}'...")
+lease = manager.acquire_proxy(pool_name=pool.name, duration_seconds=60)
+
+if lease:
+    leased_proxy = storage.get_proxy_by_id(lease.proxy_id)
+    print(f"Success! Leased proxy: {leased_proxy.host}:{leased_proxy.port}")
+    print(f"Lease acquired by consumer ID: {lease.consumer_id}")
+
+    # ... do some work with the proxy ...
+
+    # 4. Release the lease when done
+    print("\nReleasing the lease...")
+    manager.release_proxy(lease)
+    print("Lease released.")
+
+    proxy_after_release = storage.get_proxy_by_id(lease.proxy_id)
+    print(f"Proxy lease count after release: {proxy_after_release.current_leases}")
+else:
+    print("Failed to acquire a proxy. None available.")
+```
+
+### Filtering and Geospatial Matching
+
+`ProxyFilters` let you target proxies by provider metadata or geographic
+proximity. The storage layer handles the matching logic, including radius-based
+searches using latitude and longitude.
+
+```python
+from pharox import ProxyFilters
+
+filters = ProxyFilters(
+    country="AR",
+    source="fast-provider",
+    latitude=-34.6,
+    longitude=-58.38,
+    radius_km=50,
+)
+
+lease = manager.acquire_proxy(
+    pool_name="latam-residential",
+    consumer_name="team-madrid",
+    filters=filters,
+)
+
+if lease:
+    print("Got a proxy close to Buenos Aires!")
+```
+
+### Health Checks Across Protocols
+
+Use `HealthChecker` to verify connectivity through HTTP, HTTPS, or SOCKS proxies.
+Health checks are configurable via `HealthCheckOptions`, letting you define
+target URLs, expected status codes, retry counts, and latency thresholds.
+
+```python
+from pharox import HealthCheckOptions, HealthChecker, ProxyStatus
+
+checker = HealthChecker()
+options = HealthCheckOptions(
+    target_url="https://example.com/status/204",
+    expected_status_codes=[204],
+    attempts=2,
+    slow_threshold_ms=1500,
+)
+
+proxy = storage.get_proxy_by_id(lease.proxy_id)
+health = await checker.check_proxy(proxy, options=options)
+
+if health.status in {ProxyStatus.ACTIVE, ProxyStatus.SLOW}:
+    print("Proxy ready for workloads")
+else:
+    print(f"Proxy inactive: {health.error_message}")
+```
+
+## Embedding the Toolkit
+
+`pharox` is intentionally agnostic about where it runs. Typical usage
+includes:
+
+* **Automation scripts and workers** leasing proxies with `ProxyManager` and
+  performing health probes before dispatching workloads.
+* **Custom services** that provide APIs or dashboards on top of the toolkit by
+  implementing the `IStorage` contract for their own databases.
+* **Standalone applications** that rely on the in-memory storage adapter for
+  quick tasks or testing harnesses.
+
+The in-memory adapter included with the package is great for development. For
+production, implement `IStorage` to connect the toolkit to your own persistence
+layer.
+
+## Contributing
+
+Contributions are welcome! Please see the `CONTRIBUTING.md` file for details on how to set up your development environment, run tests, and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the `LICENSE` file for details.

pharox-0.3.0/pyproject.toml

@@ -0,0 +1,73 @@
+[tool.poetry]
+name = "pharox"
+version = "0.3.0"
+description = "A modern library for managing, leasing, and monitoring proxy pools."
+readme = "README.md"
+license = "MIT"
+repository = "https://github.com/fzaca/pharox"
+packages = [{ include = "pharox", from = "src" }]
+authors = ["fzaca zaca03zaca@gmail.com"]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+pydantic = "^2.11.7"
+httpx = "^0.28.1"
+
+[tool.poetry.extras]
+socks = ["httpx-socks"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4"
+pytest-mock = "^3.10.0"
+pytest-asyncio = "^0.21.0"
+pytest-cov = "^4.1"
+ruff = "^0.1.6"
+pre-commit = "^3.5"
+mypy = "^1.7"
+commitizen = "^4.8.3"
+ipdb = "^0.13.10"
+mkdocs = "^1.6.1"
+mkdocs-shadcn = "^0.5.1"
+
+[tool.ruff]
+line-length = 88
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "D",  # pydocstyle
+]
+ignore = [
+    "D203", # Conflicts with D211
+    "D212", # Conflicts with D213
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D107", # Missing docstring in __init__
+]
+[tool.ruff.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.isort]
+known-first-party = ["pharox"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --cov=src/pharox --cov-report=term-missing"
+testpaths = ["tests"]
+
+[tool.mypy]
+ignore_missing_imports = true
+disallow_untyped_defs = true
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "poetry"
+update_changelog_on_bump = true
+major_version_zero = true

pharox-0.3.0/src/pharox/__init__.py

@@ -0,0 +1,45 @@
+"""Public exports for the Pharox proxy management toolkit."""
+
+from .health import HealthChecker, HealthCheckOrchestrator
+from .manager import ProxyManager
+from .models import (
+    Consumer,
+    HealthCheckOptions,
+    HealthCheckResult,
+    Lease,
+    LeaseStatus,
+    Proxy,
+    ProxyCredentials,
+    ProxyFilters,
+    ProxyPool,
+    ProxyProtocol,
+    ProxyStatus,
+)
+from .storage import InMemoryStorage, IStorage
+from .utils import (
+    bootstrap_consumer,
+    bootstrap_pool,
+    bootstrap_proxy,
+)
+
+__all__ = [
+    "Consumer",
+    "HealthCheckOrchestrator",
+    "HealthChecker",
+    "HealthCheckOptions",
+    "HealthCheckResult",
+    "IStorage",
+    "InMemoryStorage",
+    "Lease",
+    "LeaseStatus",
+    "Proxy",
+    "ProxyCredentials",
+    "ProxyFilters",
+    "ProxyManager",
+    "ProxyPool",
+    "ProxyProtocol",
+    "ProxyStatus",
+    "bootstrap_consumer",
+    "bootstrap_pool",
+    "bootstrap_proxy",
+]