protox-gatekeeper 0.1.2__py3-none-any.whl → 0.2.1__py3-none-any.whl

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/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.dist-info → protox_gatekeeper-0.2.1.dist-info}/METADATA

@@ -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.2.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+protox_gatekeeper/__init__.py,sha256=HisDC-NCbMlkrNkrLRdANILoBqw03ssqFp6BTsXm6Us,75
+protox_gatekeeper/core.py,sha256=oMTTlSbzZ3OxpJ7DFY5sKjbIsffeQhV2bzjt5KLArAM,4414
+protox_gatekeeper/geo.py,sha256=j1TY88OavTx5rqhWd-3hbhZzD51Gjtl726bqvnApA1Q,641
+protox_gatekeeper/ops.py,sha256=Kmr8lU8Ohe81URHHNUlUJ0S71aZ1uGgyiztLBPsOUO4,690
+protox_gatekeeper/session.py,sha256=0qGZF44EHr7CP-bSM0awtq4F-5LWiIb4w87mV7Yocfk,235
+protox_gatekeeper/verify.py,sha256=bsHK3f16sRV8cHo30AY82SB1vb_Svu-US7IhghTSQ6E,452
+protox_gatekeeper-0.2.1.dist-info/licenses/LICENSE,sha256=EE75Vy9_csDDBRXBF4uVQWxYu1YpzXTcmaeuVcPOjl4,1093
+protox_gatekeeper-0.2.1.dist-info/METADATA,sha256=Is8hyTIs6kRhGdhLsRrw86rxI9PCtxMu6ZUetxVNZ6s,6942
+protox_gatekeeper-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+protox_gatekeeper-0.2.1.dist-info/top_level.txt,sha256=KOVL4YUpiWQLGjCvx2SmP8VSsA6hPcEvKCd4k6kPl8s,18
+protox_gatekeeper-0.2.1.dist-info/RECORD,,

{protox_gatekeeper-0.1.2.dist-info → protox_gatekeeper-0.2.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

protox_gatekeeper-0.1.2.dist-info/RECORD

@@ -1,11 +0,0 @@
-protox_gatekeeper/__init__.py,sha256=HisDC-NCbMlkrNkrLRdANILoBqw03ssqFp6BTsXm6Us,75
-protox_gatekeeper/core.py,sha256=Z4LEY1WcSbjMDU3OS1rf7kPOTry9NJq5-quzACxPvKg,3062
-protox_gatekeeper/geo.py,sha256=AdjHfZqjP0w5ujHFI_WV7c5XWnDTzqkVL32KeJQojYo,641
-protox_gatekeeper/ops.py,sha256=Kmr8lU8Ohe81URHHNUlUJ0S71aZ1uGgyiztLBPsOUO4,690
-protox_gatekeeper/session.py,sha256=0qGZF44EHr7CP-bSM0awtq4F-5LWiIb4w87mV7Yocfk,235
-protox_gatekeeper/verify.py,sha256=bsHK3f16sRV8cHo30AY82SB1vb_Svu-US7IhghTSQ6E,452
-protox_gatekeeper-0.1.2.dist-info/licenses/LICENSE,sha256=EE75Vy9_csDDBRXBF4uVQWxYu1YpzXTcmaeuVcPOjl4,1093
-protox_gatekeeper-0.1.2.dist-info/METADATA,sha256=MmHERPyR-Jx8UnAM8BhmpIe6IKrgk7-k_44fN7l8Jh8,6154
-protox_gatekeeper-0.1.2.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-protox_gatekeeper-0.1.2.dist-info/top_level.txt,sha256=KOVL4YUpiWQLGjCvx2SmP8VSsA6hPcEvKCd4k6kPl8s,18
-protox_gatekeeper-0.1.2.dist-info/RECORD,,