quanticdata 0.1.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -32,3 +32,14 @@ scraper-service/.unlock-ca/
32
32
  # Stato runtime dei job/dataset del servizio
33
33
  scraper-service/.job-store/
34
34
  scraper-service/.dataset-files/
35
+
36
+ # Screenshot che l'agente Quantic Browser produce mentre lavora sugli ordini:
37
+ # 128 MB di PNG col nome del cliente nel filename. E' output runtime, non
38
+ # codice, e in git ci resterebbe per sempre.
39
+ scraper-service/agent-lab/order-screenshots/
40
+
41
+ # Il token di auth_request del Quantic Browser, in chiaro dentro un include
42
+ # nginx. E' una credenziale di produzione viva: in git ci resterebbe per sempre,
43
+ # anche dopo averla ruotata. Sul server sta in /etc/nginx/snippets/ (0640).
44
+ ops/nginx/snippets/quantic-browser-token.conf
45
+ quanticdata-claude-plugin/
@@ -1,14 +1,16 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quanticdata
3
- Version: 0.1.0
4
- Summary: Official Python SDK for the QuanticData API — web scraping to Markdown, SERP search, crawl/map, 74 ready-made Collectors and residential/mobile/datacenter proxy generation.
5
- Project-URL: Homepage, https://quanticdata.io
6
- Project-URL: Documentation, https://quanticdata.io/docs
7
- Project-URL: Repository, https://github.com/quanticdata/quanticdata-python
3
+ Version: 0.2.1
4
+ Summary: Official Python SDK for the QuanticData API: web pages to Markdown, SERP search, crawl/map, Web Unlocker, ready-made collectors and residential, mobile and datacenter proxy generation.
5
+ Project-URL: Homepage, https://quanticdata.io/
6
+ Project-URL: Documentation, https://quanticdata.io/docs/
7
+ Project-URL: Repository, https://github.com/quantumproxies/quanticdata-python
8
+ Project-URL: Issues, https://github.com/quantumproxies/quanticdata-python/issues
9
+ Project-URL: MCP server, https://quanticdata.io/mcp-server/
8
10
  Author-email: QuanticData <support@quanticdata.io>
9
11
  License: MIT
10
12
  License-File: LICENSE
11
- Keywords: ai-agents,crawler,data-extraction,google-search,proxy,quanticdata,residential-proxies,scraper,serp,web-scraping
13
+ Keywords: ai-agents,crawler,llm,markdown,mcp,proxy,quanticdata,rag,residential-proxies,scraper,serp,serp-api,web-scraping,web-unlocker
12
14
  Classifier: Development Status :: 4 - Beta
13
15
  Classifier: Intended Audience :: Developers
14
16
  Classifier: License :: OSI Approved :: MIT License
@@ -108,6 +110,32 @@ plans = client.list_proxies(active=True)
108
110
  proxies = client.generate_proxies(plans["proxies"][0]["orderId"], country="us", quantity=5)
109
111
  ```
110
112
 
113
+ ## Web Unlocker
114
+
115
+ `unlock()` replays any HTTP request — method, headers, body — through a
116
+ residential exit with a real browser TLS fingerprint, retries on a fresh IP
117
+ when the target blocks it, and escalates a blocked GET to a real browser.
118
+ You get the raw response back: `status`, `headers`, `body`, `finalUrl`.
119
+
120
+ ```python
121
+ r = client.unlock("https://www.example-shop.com/item/42", country="us")
122
+ if r["blocked"]:
123
+ print(r["blockClass"], r.get("vendor"), r.get("blockReason")) # e.g. "waf", "cloudflare"
124
+ else:
125
+ print(r["status"], r["body"][:200])
126
+
127
+ # Force a real browser render and wait for the price to appear
128
+ page = client.unlock(
129
+ "https://www.example-shop.com/item/42",
130
+ render="html", wait_for_selector=".price", wait_ms=1500,
131
+ )
132
+ ```
133
+
134
+ A still-blocked page is never returned as a silent 200: it comes flagged
135
+ with `blocked: true` (pass `fail_on_block=True` to get an error instead).
136
+ Interactive captchas are not solved — they arrive with `blockClass: "captcha"`.
137
+ Billed per GB of the tier's prepaid unlocker balance (`usage` in the response).
138
+
111
139
  ## Errors and retries
112
140
 
113
141
  Failures raise `QuanticDataError` with `.status`, `.message` and
@@ -82,6 +82,32 @@ plans = client.list_proxies(active=True)
82
82
  proxies = client.generate_proxies(plans["proxies"][0]["orderId"], country="us", quantity=5)
83
83
  ```
84
84
 
85
+ ## Web Unlocker
86
+
87
+ `unlock()` replays any HTTP request — method, headers, body — through a
88
+ residential exit with a real browser TLS fingerprint, retries on a fresh IP
89
+ when the target blocks it, and escalates a blocked GET to a real browser.
90
+ You get the raw response back: `status`, `headers`, `body`, `finalUrl`.
91
+
92
+ ```python
93
+ r = client.unlock("https://www.example-shop.com/item/42", country="us")
94
+ if r["blocked"]:
95
+ print(r["blockClass"], r.get("vendor"), r.get("blockReason")) # e.g. "waf", "cloudflare"
96
+ else:
97
+ print(r["status"], r["body"][:200])
98
+
99
+ # Force a real browser render and wait for the price to appear
100
+ page = client.unlock(
101
+ "https://www.example-shop.com/item/42",
102
+ render="html", wait_for_selector=".price", wait_ms=1500,
103
+ )
104
+ ```
105
+
106
+ A still-blocked page is never returned as a silent 200: it comes flagged
107
+ with `blocked: true` (pass `fail_on_block=True` to get an error instead).
108
+ Interactive captchas are not solved — they arrive with `blockClass: "captcha"`.
109
+ Billed per GB of the tier's prepaid unlocker balance (`usage` in the response).
110
+
85
111
  ## Errors and retries
86
112
 
87
113
  Failures raise `QuanticDataError` with `.status`, `.message` and
@@ -4,25 +4,14 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "quanticdata"
7
- version = "0.1.0"
8
- description = "Official Python SDK for the QuanticData API — web scraping to Markdown, SERP search, crawl/map, 74 ready-made Collectors and residential/mobile/datacenter proxy generation."
7
+ version = "0.2.1"
8
+ description = "Official Python SDK for the QuanticData API: web pages to Markdown, SERP search, crawl/map, Web Unlocker, ready-made collectors and residential, mobile and datacenter proxy generation."
9
9
  readme = "README.md"
10
10
  license = { text = "MIT" }
11
11
  authors = [{ name = "QuanticData", email = "support@quanticdata.io" }]
12
12
  requires-python = ">=3.9"
13
13
  dependencies = ["requests>=2.25"]
14
- keywords = [
15
- "web-scraping",
16
- "scraper",
17
- "serp",
18
- "proxy",
19
- "residential-proxies",
20
- "crawler",
21
- "google-search",
22
- "quanticdata",
23
- "data-extraction",
24
- "ai-agents",
25
- ]
14
+ keywords = ["quanticdata", "web-scraping", "scraper", "serp", "serp-api", "markdown", "crawler", "web-unlocker", "proxy", "residential-proxies", "mcp", "ai-agents", "llm", "rag"]
26
15
  classifiers = [
27
16
  "Development Status :: 4 - Beta",
28
17
  "Intended Audience :: Developers",
@@ -38,9 +27,11 @@ classifiers = [
38
27
  ]
39
28
 
40
29
  [project.urls]
41
- Homepage = "https://quanticdata.io"
42
- Documentation = "https://quanticdata.io/docs"
43
- Repository = "https://github.com/quanticdata/quanticdata-python"
30
+ Homepage = "https://quanticdata.io/"
31
+ Documentation = "https://quanticdata.io/docs/"
32
+ Repository = "https://github.com/quantumproxies/quanticdata-python"
33
+ Issues = "https://github.com/quantumproxies/quanticdata-python/issues"
34
+ "MCP server" = "https://quanticdata.io/mcp-server/"
44
35
 
45
36
  [tool.hatch.build.targets.wheel]
46
37
  packages = ["src/quanticdata"]
@@ -11,7 +11,7 @@ Quickstart::
11
11
  print(page["content"])
12
12
  """
13
13
 
14
- __version__ = "0.1.0"
14
+ __version__ = "0.2.1"
15
15
 
16
16
  from ._client import ( # noqa: E402
17
17
  DEFAULT_BASE_URL,
@@ -26,6 +26,21 @@ _TERMINAL_STATUSES = {"done", "completed", "failed", "error", "cancelled"}
26
26
 
27
27
  _JOB_ID_FIELDS = ("jobId", "job_id", "run_id", "runId", "id")
28
28
 
29
+ # unlock(): snake_case keyword → the API's camelCase field.
30
+ _UNLOCK_ALIASES = {
31
+ "session_id": "sessionId",
32
+ "tls_profile": "tlsProfile",
33
+ "auto_render": "autoRender",
34
+ "keep_headers": "keepHeaders",
35
+ "success_status_codes": "successStatusCodes",
36
+ "timeout_ms": "timeoutMs",
37
+ "fail_on_block": "failOnBlock",
38
+ "wait_for_selector": "waitForSelector",
39
+ "wait_ms": "waitMs",
40
+ "return_cookies": "returnCookies",
41
+ "body_base64": "bodyBase64",
42
+ }
43
+
29
44
 
30
45
  class QuanticDataError(Exception):
31
46
  """Raised when the API answers with the error envelope or transport fails.
@@ -109,7 +124,7 @@ class QuanticData:
109
124
  attempt += 1
110
125
  time.sleep(min(2**attempt, 8))
111
126
  continue
112
- raise QuanticDataError(f"Cannot reach the QuanticData API at {url}: {exc}") from exc
127
+ raise QuanticDataError(f"Cannot reach the QuanticData API ({exc})\nEndpoint: {url}") from exc
113
128
 
114
129
  if resp.status_code == 429 and attempt < self.max_retries:
115
130
  attempt += 1
@@ -200,6 +215,39 @@ class QuanticData:
200
215
  body["actions"] = actions
201
216
  return self._request("POST", "/scraper/extract", body)
202
217
 
218
+ def unlock(self, url: str, **options: Any) -> Any:
219
+ """Replay an HTTP request through the Web Unlocker (``POST /scraper/unlock``).
220
+
221
+ Send the request the way your own client would make it — ``url``,
222
+ ``method``, ``headers``, ``body`` (or ``body_base64``) — and it comes
223
+ back replayed through a residential exit under a real browser TLS
224
+ fingerprint, retried on a fresh IP if the target blocks it, and (for a
225
+ GET) escalated to a real browser. A page that is still blocked comes
226
+ back flagged (``blocked``, ``blockClass``, ``vendor``), never as a
227
+ silent 200. Interactive captchas are not solved: they arrive with
228
+ ``blockClass: "captcha"``.
229
+
230
+ Options (snake_case aliases are mapped to the API's camelCase):
231
+ ``method``, ``headers``, ``body``, ``body_base64``, ``country``,
232
+ ``state``, ``city``, ``rotation`` (``"rotating"``|``"sticky"``),
233
+ ``session_id``, ``tls_profile`` (chrome|firefox|safari|safari_ios|
234
+ edge|brave|mobile), ``mobile``, ``tier`` (``"premium"``|``"mobile"``),
235
+ ``render`` (``"html"``|``"png"``|bool), ``auto_render``,
236
+ ``keep_headers``, ``success_status_codes``, ``timeout_ms``,
237
+ ``fail_on_block`` (HTTP 502 instead of a 200 with ``blocked``),
238
+ ``wait_for_selector``, ``wait_ms``, ``return_cookies``, ``cookies``.
239
+
240
+ Returns the raw response: ``status``, ``headers``, ``body`` (text when
241
+ textual), ``bodyBase64``, ``finalUrl``, ``contentType``, ``blocked``,
242
+ ``blockReason``, ``blockClass``, ``vendor``, ``attempts``,
243
+ ``rendered``, ``escalated``, ``cookies``, ``usage`` …
244
+ """
245
+ body = self._clean({"url": url, **options})
246
+ for snake, camel in _UNLOCK_ALIASES.items():
247
+ if snake in body:
248
+ body[camel] = body.pop(snake)
249
+ return self._request("POST", "/scraper/unlock", body)
250
+
203
251
  def batch(
204
252
  self,
205
253
  urls: List[str],
File without changes