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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protox-gatekeeper
-Version: 0.1.2
+Version: 0.2.0
 Summary: Fail-closed Tor session enforcement for Python HTTP(S) traffic
 Author: Tom Erik Harnes
 License: MIT License
@@ -46,25 +46,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 +91,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 +141,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 +168,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 +187,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 +239,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 +252,13 @@ MIT License
 
 ## Status
 
-- Version: **v0.1.2**
-- Phase 1 complete
+- Version: **v0.2.0**
+- 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.0}/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.0**
+- 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.0}/protox_gatekeeper/core.py

@@ -69,6 +69,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.0}/protox_gatekeeper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: protox-gatekeeper
-Version: 0.1.2
+Version: 0.2.0
 Summary: Fail-closed Tor session enforcement for Python HTTP(S) traffic
 Author: Tom Erik Harnes
 License: MIT License
@@ -46,25 +46,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 +91,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 +141,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 +168,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 +187,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 +239,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 +252,13 @@ MIT License
 
 ## Status
 
-- Version: **v0.1.2**
-- Phase 1 complete
+- Version: **v0.2.0**
+- 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "protox-gatekeeper"
-version = "0.1.2"
+version = "0.2.0"
 description = "Fail-closed Tor session enforcement for Python HTTP(S) traffic"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -34,3 +34,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"
+]