protox-gatekeeper 0.1.2__tar.gz → 0.2.1__tar.gz

{protox_gatekeeper-0.1.2 → protox_gatekeeper-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protox-gatekeeper
-Version: 0.1.2
+Version: 0.2.1
 Summary: Fail-closed Tor session enforcement for Python HTTP(S) traffic
 Author: Tom Erik Harnes
 License: MIT License
@@ -33,6 +33,7 @@ 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
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -46,25 +47,24 @@ Dynamic: license-file
 [![Python versions](https://img.shields.io/pypi/pyversions/protox-gatekeeper.svg)](https://pypi.org/project/protox-gatekeeper/)
 [![License](https://img.shields.io/pypi/l/protox-gatekeeper.svg)](https://pypi.org/project/protox-gatekeeper/)
 
-
 # ProtoX GateKeeper
 
 **ProtoX GateKeeper** is a small, opinionated Python library that enforces
-**fail‑closed Tor routing** for HTTP(S) traffic.
+**fail-closed Tor routing** for HTTP(S) traffic.
 
 The goal is simple:
 
 > If Tor is not active and verified, **nothing runs**.
 
-GateKeeper is designed to be *fire‑and‑forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
+GateKeeper is designed to be *fire-and-forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
 
 ---
 
 ## What GateKeeper Is
 
-- A **Tor‑verified HTTP client**
-- A thin wrapper around `requests.Session`
-- Fail‑closed by default (no silent clearnet fallback)
+- A **Tor-verified HTTP client**
+- A thin wrapper around `requests.Session` with safe helpers
+- Fail-closed by default (no silent clearnet fallback)
 - Observable (exit IP, optional geo info)
 - Suitable for scripts, tooling, and automation
 
@@ -92,6 +92,12 @@ On Windows this usually means **Tor Browser** running in the background.
 
 ## Installation
 
+### From PyPI
+
+```bash
+pip install protox-gatekeeper
+```
+
 ### From source (development)
 
 ```bash
@@ -136,6 +142,20 @@ This confirms:
 
 ---
 
+### HTTP requests
+
+GateKeeper can also be used as a Tor-verified HTTP client:
+
+```python
+with GateKeeper() as gk:
+    response = gk.get("https://httpbin.org/ip")
+    print(response.json())
+```
+
+All requests are guaranteed to use the verified Tor session.
+
+---
+
 ## API Overview
 
 ### `GateKeeper(...)`
@@ -149,7 +169,7 @@ gk = GateKeeper(
 
 **Parameters**:
 - `socks_port` *(int)* – Tor SOCKS port (default: `9150`)
-- `geo` *(bool)* – Enable best‑effort Tor exit geolocation (optional)
+- `geo` *(bool)* – Enable best-effort Tor exit geolocation (optional)
 
 Raises `RuntimeError` if Tor routing cannot be verified.
 
@@ -168,13 +188,37 @@ gk.download(url, target_path)
 
 ---
 
+### `get(url, **kwargs)`
+
+Performs a Tor-verified HTTP GET request.
+
+```python
+response = gk.get(url, timeout=10)
+```
+
+Returns a standard `requests.Response`.
+
+---
+
+### `post(url, data=None, json=None, **kwargs)`
+
+Performs a Tor-verified HTTP POST request.
+
+```python
+response = gk.post(url, json={"key": "value"})
+```
+
+Returns a standard `requests.Response`.
+
+---
+
 ## Design Principles
 
 - **Fail closed**: no Tor → no execution
 - **Single verification point** (during construction)
 - **No global state**
 - **No logging configuration inside the library**
-- **Session reuse without re‑verification**
+- **Session reuse without re-verification**
 
 Logging is emitted by the library, but **configured by the application**.
 
@@ -196,8 +240,8 @@ The library does **not** call `logging.basicConfig()` internally.
 ## Security Notes
 
 - Tor exit IPs may rotate over time
-- Geo information is best‑effort and may be unavailable (rate‑limits, CAPTCHAs)
-- GateKeeper guarantees routing, not anonymity
+- Geo information is best-effort and may be unavailable (rate-limits, CAPTCHAs)
+- GateKeeper guarantees transport routing, not anonymity
 
 ---
 
@@ -209,14 +253,13 @@ MIT License
 
 ## Status
 
-- Version: **v0.1.2**
-- Phase 1 complete
+- Version: **v0.2.1**
+- Phase 2 in progress
 - API intentionally minimal
 
 Future versions may add optional features such as:
 - circuit rotation
 - ControlPort support
-- higher‑level request helpers
+- higher-level request helpers
 
 Without breaking the core contract.
-

{protox_gatekeeper-0.1.2 → protox_gatekeeper-0.2.1}/README.md

@@ -2,25 +2,24 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/protox-gatekeeper.svg)](https://pypi.org/project/protox-gatekeeper/)
 [![License](https://img.shields.io/pypi/l/protox-gatekeeper.svg)](https://pypi.org/project/protox-gatekeeper/)
 
-
 # ProtoX GateKeeper
 
 **ProtoX GateKeeper** is a small, opinionated Python library that enforces
-**fail‑closed Tor routing** for HTTP(S) traffic.
+**fail-closed Tor routing** for HTTP(S) traffic.
 
 The goal is simple:
 
 > If Tor is not active and verified, **nothing runs**.
 
-GateKeeper is designed to be *fire‑and‑forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
+GateKeeper is designed to be *fire-and-forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
 
 ---
 
 ## What GateKeeper Is
 
-- A **Tor‑verified HTTP client**
-- A thin wrapper around `requests.Session`
-- Fail‑closed by default (no silent clearnet fallback)
+- A **Tor-verified HTTP client**
+- A thin wrapper around `requests.Session` with safe helpers
+- Fail-closed by default (no silent clearnet fallback)
 - Observable (exit IP, optional geo info)
 - Suitable for scripts, tooling, and automation
 
@@ -48,6 +47,12 @@ On Windows this usually means **Tor Browser** running in the background.
 
 ## Installation
 
+### From PyPI
+
+```bash
+pip install protox-gatekeeper
+```
+
 ### From source (development)
 
 ```bash
@@ -92,6 +97,20 @@ This confirms:
 
 ---
 
+### HTTP requests
+
+GateKeeper can also be used as a Tor-verified HTTP client:
+
+```python
+with GateKeeper() as gk:
+    response = gk.get("https://httpbin.org/ip")
+    print(response.json())
+```
+
+All requests are guaranteed to use the verified Tor session.
+
+---
+
 ## API Overview
 
 ### `GateKeeper(...)`
@@ -105,7 +124,7 @@ gk = GateKeeper(
 
 **Parameters**:
 - `socks_port` *(int)* – Tor SOCKS port (default: `9150`)
-- `geo` *(bool)* – Enable best‑effort Tor exit geolocation (optional)
+- `geo` *(bool)* – Enable best-effort Tor exit geolocation (optional)
 
 Raises `RuntimeError` if Tor routing cannot be verified.
 
@@ -124,13 +143,37 @@ gk.download(url, target_path)
 
 ---
 
+### `get(url, **kwargs)`
+
+Performs a Tor-verified HTTP GET request.
+
+```python
+response = gk.get(url, timeout=10)
+```
+
+Returns a standard `requests.Response`.
+
+---
+
+### `post(url, data=None, json=None, **kwargs)`
+
+Performs a Tor-verified HTTP POST request.
+
+```python
+response = gk.post(url, json={"key": "value"})
+```
+
+Returns a standard `requests.Response`.
+
+---
+
 ## Design Principles
 
 - **Fail closed**: no Tor → no execution
 - **Single verification point** (during construction)
 - **No global state**
 - **No logging configuration inside the library**
-- **Session reuse without re‑verification**
+- **Session reuse without re-verification**
 
 Logging is emitted by the library, but **configured by the application**.
 
@@ -152,8 +195,8 @@ The library does **not** call `logging.basicConfig()` internally.
 ## Security Notes
 
 - Tor exit IPs may rotate over time
-- Geo information is best‑effort and may be unavailable (rate‑limits, CAPTCHAs)
-- GateKeeper guarantees routing, not anonymity
+- Geo information is best-effort and may be unavailable (rate-limits, CAPTCHAs)
+- GateKeeper guarantees transport routing, not anonymity
 
 ---
 
@@ -165,14 +208,13 @@ MIT License
 
 ## Status
 
-- Version: **v0.1.2**
-- Phase 1 complete
+- Version: **v0.2.1**
+- Phase 2 in progress
 - API intentionally minimal
 
 Future versions may add optional features such as:
 - circuit rotation
 - ControlPort support
-- higher‑level request helpers
+- higher-level request helpers
 
 Without breaking the core contract.
-

{protox_gatekeeper-0.1.2 → protox_gatekeeper-0.2.1}/protox_gatekeeper/core.py

@@ -1,6 +1,7 @@
 import logging
 
 import requests
+from requests.exceptions import RequestException
 
 from protox_gatekeeper.session import make_tor_session
 from protox_gatekeeper.verify import is_tor_exit, get_public_ip
@@ -33,8 +34,16 @@ class GateKeeper:
         self._session = make_tor_session(port=socks_port)
 
         # 3) Verify Tor routing
-        if not is_tor_exit(session=self._session, timeout=timeout):
-            raise RuntimeError('Tor verification failed. Execution aborted.')
+        try:
+            if not is_tor_exit(session=self._session, timeout=timeout):
+                raise RuntimeError(
+                    'Tor verification failed. Execution aborted.')
+        except RequestException as e:
+            logger.debug('Underlying Tor connection error', exc_info=e)
+            raise RuntimeError(
+                f'Tor SOCKS proxy is not reachable on 127.0.0.1:{socks_port}. '
+                'Start Tor or Tor Browser and try again.'
+            ) from None
 
         # 4) Measure Tor exit IP
         self.exit_ip = get_public_ip(session=self._session, timeout=timeout)
@@ -69,6 +78,31 @@ class GateKeeper:
         """ Returns the Tor exit IP address. """
         return self.exit_ip
 
+    def get(self, url: str, **kwargs) -> requests.Response:
+        """
+        Passes a GET request to the Tor Gatekeeper.
+
+        Args:
+            url (str): The url to request.
+            **kwargs: Additional parameters to pass to the GET request.
+        """
+        logger.info(f'[Tor {self.tor_exit}] GET {url}')
+        return self._session.get(url=url, **kwargs)
+
+    def post(self, url: str, data=None, json=None,
+             **kwargs) -> requests.Response:
+        """
+        Passes a POST request to the Tor Gatekeeper.
+
+        Args:
+            url (str): The url to post to.
+            data (dict, optional): The data to post.
+            json (dict, optional): The json data to post.
+            **kwargs: Additional parameters to pass to the POST request.
+        """
+        logger.info(f'[Tor {self.tor_exit}] POST {url}')
+        return self._session.post(url=url, data=data, json=json, **kwargs)
+
     def download(self, url: str, target_path: str, timeout: int = 30,
                  chunk_size: int = 8192):
         """

{protox_gatekeeper-0.1.2 → protox_gatekeeper-0.2.1}/protox_gatekeeper/geo.py

@@ -10,7 +10,7 @@ def geo_lookup(ip: str) -> str | None:
         r = requests.get(
             url=f'https://ipapi.co/{ip}/json',
             timeout=10,
-            headers={'User-Agent': 'GateKeeper/0.1.0'}
+            headers={'User-Agent': 'GateKeeper/0.2.1'}
         )
         if r.status_code != 200:
             return None

{protox_gatekeeper-0.1.2 → protox_gatekeeper-0.2.1}/protox_gatekeeper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protox-gatekeeper
-Version: 0.1.2
+Version: 0.2.1
 Summary: Fail-closed Tor session enforcement for Python HTTP(S) traffic
 Author: Tom Erik Harnes
 License: MIT License
@@ -33,6 +33,7 @@ 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
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -46,25 +47,24 @@ Dynamic: license-file
 [![Python versions](https://img.shields.io/pypi/pyversions/protox-gatekeeper.svg)](https://pypi.org/project/protox-gatekeeper/)
 [![License](https://img.shields.io/pypi/l/protox-gatekeeper.svg)](https://pypi.org/project/protox-gatekeeper/)
 
-
 # ProtoX GateKeeper
 
 **ProtoX GateKeeper** is a small, opinionated Python library that enforces
-**fail‑closed Tor routing** for HTTP(S) traffic.
+**fail-closed Tor routing** for HTTP(S) traffic.
 
 The goal is simple:
 
 > If Tor is not active and verified, **nothing runs**.
 
-GateKeeper is designed to be *fire‑and‑forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
+GateKeeper is designed to be *fire-and-forget*: create a client once, then perform network operations with a hard guarantee that traffic exits through the Tor network.
 
 ---
 
 ## What GateKeeper Is
 
-- A **Tor‑verified HTTP client**
-- A thin wrapper around `requests.Session`
-- Fail‑closed by default (no silent clearnet fallback)
+- A **Tor-verified HTTP client**
+- A thin wrapper around `requests.Session` with safe helpers
+- Fail-closed by default (no silent clearnet fallback)
 - Observable (exit IP, optional geo info)
 - Suitable for scripts, tooling, and automation
 
@@ -92,6 +92,12 @@ On Windows this usually means **Tor Browser** running in the background.
 
 ## Installation
 
+### From PyPI
+
+```bash
+pip install protox-gatekeeper
+```
+
 ### From source (development)
 
 ```bash
@@ -136,6 +142,20 @@ This confirms:
 
 ---
 
+### HTTP requests
+
+GateKeeper can also be used as a Tor-verified HTTP client:
+
+```python
+with GateKeeper() as gk:
+    response = gk.get("https://httpbin.org/ip")
+    print(response.json())
+```
+
+All requests are guaranteed to use the verified Tor session.
+
+---
+
 ## API Overview
 
 ### `GateKeeper(...)`
@@ -149,7 +169,7 @@ gk = GateKeeper(
 
 **Parameters**:
 - `socks_port` *(int)* – Tor SOCKS port (default: `9150`)
-- `geo` *(bool)* – Enable best‑effort Tor exit geolocation (optional)
+- `geo` *(bool)* – Enable best-effort Tor exit geolocation (optional)
 
 Raises `RuntimeError` if Tor routing cannot be verified.
 
@@ -168,13 +188,37 @@ gk.download(url, target_path)
 
 ---
 
+### `get(url, **kwargs)`
+
+Performs a Tor-verified HTTP GET request.
+
+```python
+response = gk.get(url, timeout=10)
+```
+
+Returns a standard `requests.Response`.
+
+---
+
+### `post(url, data=None, json=None, **kwargs)`
+
+Performs a Tor-verified HTTP POST request.
+
+```python
+response = gk.post(url, json={"key": "value"})
+```
+
+Returns a standard `requests.Response`.
+
+---
+
 ## Design Principles
 
 - **Fail closed**: no Tor → no execution
 - **Single verification point** (during construction)
 - **No global state**
 - **No logging configuration inside the library**
-- **Session reuse without re‑verification**
+- **Session reuse without re-verification**
 
 Logging is emitted by the library, but **configured by the application**.
 
@@ -196,8 +240,8 @@ The library does **not** call `logging.basicConfig()` internally.
 ## Security Notes
 
 - Tor exit IPs may rotate over time
-- Geo information is best‑effort and may be unavailable (rate‑limits, CAPTCHAs)
-- GateKeeper guarantees routing, not anonymity
+- Geo information is best-effort and may be unavailable (rate-limits, CAPTCHAs)
+- GateKeeper guarantees transport routing, not anonymity
 
 ---
 
@@ -209,14 +253,13 @@ MIT License
 
 ## Status
 
-- Version: **v0.1.2**
-- Phase 1 complete
+- Version: **v0.2.1**
+- Phase 2 in progress
 - API intentionally minimal
 
 Future versions may add optional features such as:
 - circuit rotation
 - ControlPort support
-- higher‑level request helpers
+- higher-level request helpers
 
 Without breaking the core contract.
-

{protox_gatekeeper-0.1.2 → protox_gatekeeper-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "protox-gatekeeper"
-version = "0.1.2"
+version = "0.2.1"
 description = "Fail-closed Tor session enforcement for Python HTTP(S) traffic"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -20,6 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
@@ -34,3 +35,8 @@ authors = [
 Homepage = "https://github.com/ProtoXCode/protox-gatekeeper"
 Repository = "https://github.com/ProtoXCode/protox-gatekeeper"
 Issues = "https://github.com/ProtoXCode/protox-gatekeeper/issues"
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: requires Tor running locally"
+]