browsa 0.3.1__tar.gz → 0.5.0__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.
- {browsa-0.3.1 → browsa-0.5.0}/PKG-INFO +76 -4
- {browsa-0.3.1 → browsa-0.5.0}/README.md +75 -3
- {browsa-0.3.1 → browsa-0.5.0}/browsa/__init__.py +10 -0
- browsa-0.5.0/browsa/_version.py +1 -0
- browsa-0.5.0/browsa/captcha/__init__.py +28 -0
- browsa-0.5.0/browsa/captcha/_client.py +194 -0
- browsa-0.5.0/browsa/captcha/compat.py +165 -0
- browsa-0.5.0/browsa/captcha/tasks.py +248 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa/client.py +329 -2
- {browsa-0.3.1 → browsa-0.5.0}/browsa/types.py +354 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa.egg-info/PKG-INFO +76 -4
- {browsa-0.3.1 → browsa-0.5.0}/browsa.egg-info/SOURCES.txt +7 -0
- browsa-0.5.0/tests/test_captcha.py +306 -0
- browsa-0.5.0/tests/test_recipes.py +153 -0
- browsa-0.5.0/tests/test_robots.py +212 -0
- browsa-0.3.1/browsa/_version.py +0 -1
- {browsa-0.3.1 → browsa-0.5.0}/LICENSE +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa/errors.py +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa/py.typed +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa/webhooks.py +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa.egg-info/dependency_links.txt +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa.egg-info/requires.txt +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/browsa.egg-info/top_level.txt +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/pyproject.toml +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/setup.cfg +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/tests/test_live.py +0 -0
- {browsa-0.3.1 → browsa-0.5.0}/tests/test_unit.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: browsa
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Official Python SDK for Browsa: real cloud browsers for AI agents (browsa.io)
|
|
5
5
|
Author-email: Browsa <support@browsa.io>
|
|
6
6
|
License: MIT
|
|
@@ -63,7 +63,7 @@ job = c.run_task(
|
|
|
63
63
|
print(job.outcome, job.final_result)
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
That runs Phantom, our
|
|
66
|
+
That runs Phantom, our own browser, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass `llm="anthropic:claude-sonnet-5-5"` with `llm_api_key`, or save the key once (below).
|
|
67
67
|
|
|
68
68
|
`job.status` says the run ended; `job.outcome` says how. `outcome == "failed"` with `status == "completed"` means the agent finished but could not do the task, and `final_result` says what stopped it.
|
|
69
69
|
|
|
@@ -137,6 +137,46 @@ print(job.llm_cost_usd) # None for hosted runs
|
|
|
137
137
|
|
|
138
138
|
A finished job has `usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `requests`), `llm_cost_usd`, `llm_tier` and `reasoning` (the level that was applied). `llm_cost_usd` is an estimate from public list prices for runs with your own key; it is `None` when unknown and always `None` for hosted runs, which are paid in credits. All four are `None` on jobs that do not have them, such as jobs run before these fields existed.
|
|
139
139
|
|
|
140
|
+
## Robots
|
|
141
|
+
|
|
142
|
+
A robot is a browser job you set up once: record a task, then run it on rows of input, on demand, on a schedule or from the API. Runs replay the recording on Phantom with no model.
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
BOOK = "https://books.toscrape.com/catalogue"
|
|
146
|
+
|
|
147
|
+
# 1. Record a task once
|
|
148
|
+
job = c.run_task(
|
|
149
|
+
task="Open the product page and return title, price and in_stock",
|
|
150
|
+
llm="browsa",
|
|
151
|
+
initial_url=f"{BOOK}/sharp-objects_997/index.html",
|
|
152
|
+
record_recipe=True,
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
# 2. Save it as a robot
|
|
156
|
+
robot = c.robots.create(
|
|
157
|
+
name="Book prices",
|
|
158
|
+
from_job_id=job.id,
|
|
159
|
+
inputs=[{"url": f"{BOOK}/sharp-objects_997/index.html"}, {"url": f"{BOOK}/soumission_998/index.html"}],
|
|
160
|
+
schedule={"interval_seconds": 86400, "at": "09:00", "tz": "UTC"},
|
|
161
|
+
monitors=[{"field": "price", "op": "changed"}],
|
|
162
|
+
settings={"proxy": {"network": "datacenter"}},
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
# 3. Run it and read the rows
|
|
166
|
+
run = c.robot_runs.wait(c.robots.run(robot.id).id)
|
|
167
|
+
for r in run.rows or []:
|
|
168
|
+
print(r.row, r.status, r.output or r.error_code)
|
|
169
|
+
csv_text = c.robot_runs.export(run.id) # or format="json"
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
| | |
|
|
173
|
+
|---|---|
|
|
174
|
+
| Price | `robot.health.price_credits` per successful row, the same as the agent task. Failed rows are free. |
|
|
175
|
+
| Settings | `model` (records and repairs), `proxy` (Browsa's network: datacenter 5, residential 50 credits/GB; or a saved `proxy_id`, free), `browser` (`os`, `screen`). Unset is Auto. |
|
|
176
|
+
| More | `list`, `get`, `update`, `delete`, `pause`, `resume`, `runs`, `alerts`, `mark_alerts_read`. `AsyncClient` has the same under `await`. Recipes alone: `create_recipe`, `run_recipe`, `get_recipe_run`. |
|
|
177
|
+
|
|
178
|
+
Guide: <https://browsa.io/guides/robots>.
|
|
179
|
+
|
|
140
180
|
## Async
|
|
141
181
|
|
|
142
182
|
```python
|
|
@@ -206,7 +246,7 @@ job = c.run_task(
|
|
|
206
246
|
|
|
207
247
|
### Interactive (input_required) tasks
|
|
208
248
|
|
|
209
|
-
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
249
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond. Hosted tasks solve reCAPTCHA v2 image grids (3 x 3, 4 x 4 and reloading tiles), image-text captchas, GeeTest slide puzzles (v3 and v4) and AWS WAF captchas in the browser's own session on workspaces that have bought a pack (fair use applies); the types and measured pass rates are at https://browsa.io/captcha. A type that is not supported yet, or a workspace on free credits only, may still need you here. Respond like this:
|
|
210
250
|
|
|
211
251
|
```python
|
|
212
252
|
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
@@ -222,7 +262,7 @@ while not job.is_terminal:
|
|
|
222
262
|
Start a task with `create_session` and the browser stays up after it ends (15 minutes by default, `browser_ttl_seconds` up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.
|
|
223
263
|
|
|
224
264
|
```python
|
|
225
|
-
s = c.create_session("Go to example.com and return the
|
|
265
|
+
s = c.create_session("Go to example.com and return the page title.", llm="browsa")
|
|
226
266
|
first = c.wait_for_job(s.id)
|
|
227
267
|
print(first.final_result)
|
|
228
268
|
|
|
@@ -284,6 +324,38 @@ print(link["live_url"]) # opens once; make one per p
|
|
|
284
324
|
|
|
285
325
|
`scope` is `"view"` (default) or `"control"`. Both calls are free.
|
|
286
326
|
|
|
327
|
+
## Captcha solving
|
|
328
|
+
|
|
329
|
+
`browsa.captcha` is a client for Browsa's captcha API: `createTask`, `getTaskResult` and `getBalance` in the format CapSolver, Anti-Captcha, CapMonster and 2Captcha's v2 API share. Same key and credits as the browser API. Failed and unsolvable tasks are not charged. Measured pass rates per type: <https://browsa.io/captcha>.
|
|
330
|
+
|
|
331
|
+
```python
|
|
332
|
+
from browsa.captcha import CaptchaClient, CaptchaError, tasks
|
|
333
|
+
|
|
334
|
+
cap = CaptchaClient() # BROWSA_API_KEY; https://captcha.browsa.io (or BROWSA_CAPTCHA_URL)
|
|
335
|
+
sol = cap.solve(tasks.recaptcha_v3("https://example.com/login", "6Lc...", page_action="login"))
|
|
336
|
+
token = sol["gRecaptchaResponse"] # sol.task_id is the task id
|
|
337
|
+
|
|
338
|
+
text = cap.solve(tasks.image_to_text(open("captcha.png", "rb").read()))["text"]
|
|
339
|
+
print(cap.get_balance()) # credits
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
Builders: `image_to_text`, `recaptcha_v2`, `recaptcha_v3`, `turnstile`, `recaptcha_v2_classification` (and `aws_waf_classification`, `slider`). Each takes `proxy=` (a URL string or `{"type", "host", "port", "username", "password"}`); without one the proxyless type is used. `AsyncCaptchaClient` has the same methods.
|
|
343
|
+
|
|
344
|
+
A task copied from code for another service works as it is: `RecaptchaV2TaskProxyless`, `TurnstileTask`, `NoCaptchaTaskProxyless` and the like are sent under Browsa's names. Errors raise `CaptchaError` with the API's `code` (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_ZERO_BALANCE`, ...).
|
|
345
|
+
|
|
346
|
+
Coming from a library that cannot be pointed at another server:
|
|
347
|
+
|
|
348
|
+
```python
|
|
349
|
+
from browsa.captcha.compat import TwoCaptcha # instead of: from twocaptcha import TwoCaptcha
|
|
350
|
+
solver = TwoCaptcha("agt_live_...")
|
|
351
|
+
solver.recaptcha(sitekey="6Le-...", url="https://example.com")["code"]
|
|
352
|
+
|
|
353
|
+
from browsa.captcha.compat import use_with_anticaptcha # anticaptchaofficial: its requests go to Browsa
|
|
354
|
+
use_with_anticaptcha()
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
CapSolver (`capsolver.api_base = ...`) and CapMonster (`ClientOptions(service_url=...)`) take a base URL as they are.
|
|
358
|
+
|
|
287
359
|
## Docs
|
|
288
360
|
|
|
289
361
|
- API reference: <https://browsa.io/docs>
|
|
@@ -31,7 +31,7 @@ job = c.run_task(
|
|
|
31
31
|
print(job.outcome, job.final_result)
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
That runs Phantom, our
|
|
34
|
+
That runs Phantom, our own browser, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass `llm="anthropic:claude-sonnet-5-5"` with `llm_api_key`, or save the key once (below).
|
|
35
35
|
|
|
36
36
|
`job.status` says the run ended; `job.outcome` says how. `outcome == "failed"` with `status == "completed"` means the agent finished but could not do the task, and `final_result` says what stopped it.
|
|
37
37
|
|
|
@@ -105,6 +105,46 @@ print(job.llm_cost_usd) # None for hosted runs
|
|
|
105
105
|
|
|
106
106
|
A finished job has `usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `requests`), `llm_cost_usd`, `llm_tier` and `reasoning` (the level that was applied). `llm_cost_usd` is an estimate from public list prices for runs with your own key; it is `None` when unknown and always `None` for hosted runs, which are paid in credits. All four are `None` on jobs that do not have them, such as jobs run before these fields existed.
|
|
107
107
|
|
|
108
|
+
## Robots
|
|
109
|
+
|
|
110
|
+
A robot is a browser job you set up once: record a task, then run it on rows of input, on demand, on a schedule or from the API. Runs replay the recording on Phantom with no model.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
BOOK = "https://books.toscrape.com/catalogue"
|
|
114
|
+
|
|
115
|
+
# 1. Record a task once
|
|
116
|
+
job = c.run_task(
|
|
117
|
+
task="Open the product page and return title, price and in_stock",
|
|
118
|
+
llm="browsa",
|
|
119
|
+
initial_url=f"{BOOK}/sharp-objects_997/index.html",
|
|
120
|
+
record_recipe=True,
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
# 2. Save it as a robot
|
|
124
|
+
robot = c.robots.create(
|
|
125
|
+
name="Book prices",
|
|
126
|
+
from_job_id=job.id,
|
|
127
|
+
inputs=[{"url": f"{BOOK}/sharp-objects_997/index.html"}, {"url": f"{BOOK}/soumission_998/index.html"}],
|
|
128
|
+
schedule={"interval_seconds": 86400, "at": "09:00", "tz": "UTC"},
|
|
129
|
+
monitors=[{"field": "price", "op": "changed"}],
|
|
130
|
+
settings={"proxy": {"network": "datacenter"}},
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
# 3. Run it and read the rows
|
|
134
|
+
run = c.robot_runs.wait(c.robots.run(robot.id).id)
|
|
135
|
+
for r in run.rows or []:
|
|
136
|
+
print(r.row, r.status, r.output or r.error_code)
|
|
137
|
+
csv_text = c.robot_runs.export(run.id) # or format="json"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
| | |
|
|
141
|
+
|---|---|
|
|
142
|
+
| Price | `robot.health.price_credits` per successful row, the same as the agent task. Failed rows are free. |
|
|
143
|
+
| Settings | `model` (records and repairs), `proxy` (Browsa's network: datacenter 5, residential 50 credits/GB; or a saved `proxy_id`, free), `browser` (`os`, `screen`). Unset is Auto. |
|
|
144
|
+
| More | `list`, `get`, `update`, `delete`, `pause`, `resume`, `runs`, `alerts`, `mark_alerts_read`. `AsyncClient` has the same under `await`. Recipes alone: `create_recipe`, `run_recipe`, `get_recipe_run`. |
|
|
145
|
+
|
|
146
|
+
Guide: <https://browsa.io/guides/robots>.
|
|
147
|
+
|
|
108
148
|
## Async
|
|
109
149
|
|
|
110
150
|
```python
|
|
@@ -174,7 +214,7 @@ job = c.run_task(
|
|
|
174
214
|
|
|
175
215
|
### Interactive (input_required) tasks
|
|
176
216
|
|
|
177
|
-
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
217
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond. Hosted tasks solve reCAPTCHA v2 image grids (3 x 3, 4 x 4 and reloading tiles), image-text captchas, GeeTest slide puzzles (v3 and v4) and AWS WAF captchas in the browser's own session on workspaces that have bought a pack (fair use applies); the types and measured pass rates are at https://browsa.io/captcha. A type that is not supported yet, or a workspace on free credits only, may still need you here. Respond like this:
|
|
178
218
|
|
|
179
219
|
```python
|
|
180
220
|
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
@@ -190,7 +230,7 @@ while not job.is_terminal:
|
|
|
190
230
|
Start a task with `create_session` and the browser stays up after it ends (15 minutes by default, `browser_ttl_seconds` up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.
|
|
191
231
|
|
|
192
232
|
```python
|
|
193
|
-
s = c.create_session("Go to example.com and return the
|
|
233
|
+
s = c.create_session("Go to example.com and return the page title.", llm="browsa")
|
|
194
234
|
first = c.wait_for_job(s.id)
|
|
195
235
|
print(first.final_result)
|
|
196
236
|
|
|
@@ -252,6 +292,38 @@ print(link["live_url"]) # opens once; make one per p
|
|
|
252
292
|
|
|
253
293
|
`scope` is `"view"` (default) or `"control"`. Both calls are free.
|
|
254
294
|
|
|
295
|
+
## Captcha solving
|
|
296
|
+
|
|
297
|
+
`browsa.captcha` is a client for Browsa's captcha API: `createTask`, `getTaskResult` and `getBalance` in the format CapSolver, Anti-Captcha, CapMonster and 2Captcha's v2 API share. Same key and credits as the browser API. Failed and unsolvable tasks are not charged. Measured pass rates per type: <https://browsa.io/captcha>.
|
|
298
|
+
|
|
299
|
+
```python
|
|
300
|
+
from browsa.captcha import CaptchaClient, CaptchaError, tasks
|
|
301
|
+
|
|
302
|
+
cap = CaptchaClient() # BROWSA_API_KEY; https://captcha.browsa.io (or BROWSA_CAPTCHA_URL)
|
|
303
|
+
sol = cap.solve(tasks.recaptcha_v3("https://example.com/login", "6Lc...", page_action="login"))
|
|
304
|
+
token = sol["gRecaptchaResponse"] # sol.task_id is the task id
|
|
305
|
+
|
|
306
|
+
text = cap.solve(tasks.image_to_text(open("captcha.png", "rb").read()))["text"]
|
|
307
|
+
print(cap.get_balance()) # credits
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Builders: `image_to_text`, `recaptcha_v2`, `recaptcha_v3`, `turnstile`, `recaptcha_v2_classification` (and `aws_waf_classification`, `slider`). Each takes `proxy=` (a URL string or `{"type", "host", "port", "username", "password"}`); without one the proxyless type is used. `AsyncCaptchaClient` has the same methods.
|
|
311
|
+
|
|
312
|
+
A task copied from code for another service works as it is: `RecaptchaV2TaskProxyless`, `TurnstileTask`, `NoCaptchaTaskProxyless` and the like are sent under Browsa's names. Errors raise `CaptchaError` with the API's `code` (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_ZERO_BALANCE`, ...).
|
|
313
|
+
|
|
314
|
+
Coming from a library that cannot be pointed at another server:
|
|
315
|
+
|
|
316
|
+
```python
|
|
317
|
+
from browsa.captcha.compat import TwoCaptcha # instead of: from twocaptcha import TwoCaptcha
|
|
318
|
+
solver = TwoCaptcha("agt_live_...")
|
|
319
|
+
solver.recaptcha(sitekey="6Le-...", url="https://example.com")["code"]
|
|
320
|
+
|
|
321
|
+
from browsa.captcha.compat import use_with_anticaptcha # anticaptchaofficial: its requests go to Browsa
|
|
322
|
+
use_with_anticaptcha()
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
CapSolver (`capsolver.api_base = ...`) and CapMonster (`ClientOptions(service_url=...)`) take a base URL as they are.
|
|
326
|
+
|
|
255
327
|
## Docs
|
|
256
328
|
|
|
257
329
|
- API reference: <https://browsa.io/docs>
|
|
@@ -29,6 +29,8 @@ For webhooks see browsa.webhooks.verify_signature.
|
|
|
29
29
|
from .client import Client, AsyncClient
|
|
30
30
|
from .types import (
|
|
31
31
|
HostedModel, Job, JobFile, JobStatus, LLMKey, Models, OwnKeyModels, Schedule,
|
|
32
|
+
Recipe, RecipeRun, RecipeVersion,
|
|
33
|
+
Robot, RobotAlert, RobotHealth, RobotRun, RobotRunRow,
|
|
32
34
|
Session, SessionBrowser, SessionTurn, Usage, Webhook,
|
|
33
35
|
NetworkProxy, Proxy, ProxyConfig, ProxyNetwork, ProxyNetworkTier,
|
|
34
36
|
)
|
|
@@ -56,6 +58,14 @@ __all__ = [
|
|
|
56
58
|
"Models",
|
|
57
59
|
"OwnKeyModels",
|
|
58
60
|
"Schedule",
|
|
61
|
+
"Recipe",
|
|
62
|
+
"RecipeRun",
|
|
63
|
+
"RecipeVersion",
|
|
64
|
+
"Robot",
|
|
65
|
+
"RobotAlert",
|
|
66
|
+
"RobotHealth",
|
|
67
|
+
"RobotRun",
|
|
68
|
+
"RobotRunRow",
|
|
59
69
|
"Session",
|
|
60
70
|
"SessionBrowser",
|
|
61
71
|
"SessionTurn",
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.5.0"
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Browsa's captcha-solving API, in the createTask / getTaskResult / getBalance format that
|
|
2
|
+
CapSolver, Anti-Captcha, CapMonster and 2Captcha's v2 API share. Same key and credits as the
|
|
3
|
+
browser API.
|
|
4
|
+
|
|
5
|
+
from browsa.captcha import CaptchaClient, tasks
|
|
6
|
+
|
|
7
|
+
cap = CaptchaClient() # BROWSA_API_KEY
|
|
8
|
+
sol = cap.solve(tasks.recaptcha_v3("https://example.com/login", "6Lc...", page_action="login"))
|
|
9
|
+
token = sol["gRecaptchaResponse"]
|
|
10
|
+
|
|
11
|
+
Coming from another service: ``browsa.captcha.compat`` (2Captcha and Anti-Captcha libraries).
|
|
12
|
+
Measured pass rates per type: https://browsa.io/captcha
|
|
13
|
+
"""
|
|
14
|
+
from . import compat, tasks
|
|
15
|
+
from ._client import (
|
|
16
|
+
DEFAULT_CAPTCHA_URL,
|
|
17
|
+
AsyncCaptchaClient,
|
|
18
|
+
CaptchaClient,
|
|
19
|
+
CaptchaError,
|
|
20
|
+
CaptchaTimeoutError,
|
|
21
|
+
Solution,
|
|
22
|
+
)
|
|
23
|
+
from .tasks import TASK_TYPES, normalize_task
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"CaptchaClient", "AsyncCaptchaClient", "CaptchaError", "CaptchaTimeoutError", "Solution",
|
|
27
|
+
"DEFAULT_CAPTCHA_URL", "TASK_TYPES", "normalize_task", "tasks", "compat",
|
|
28
|
+
]
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
"""Client for Browsa's captcha API: createTask, getTaskResult, getBalance.
|
|
2
|
+
|
|
3
|
+
Every answer is HTTP 200 with ``errorId`` 0 (ok) or 1 (error, with ``errorCode``), as at
|
|
4
|
+
CapSolver, Anti-Captcha and CapMonster. Recognition tasks are answered inside createTask;
|
|
5
|
+
token tasks return a ``taskId`` to poll. Stdlib only, like the rest of the SDK.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import asyncio
|
|
10
|
+
import json
|
|
11
|
+
import os
|
|
12
|
+
import socket
|
|
13
|
+
import time
|
|
14
|
+
import urllib.error
|
|
15
|
+
import urllib.request
|
|
16
|
+
from typing import Any, Callable, Dict, Mapping, Optional
|
|
17
|
+
|
|
18
|
+
from .. import errors
|
|
19
|
+
from .._version import __version__
|
|
20
|
+
from .tasks import normalize_task
|
|
21
|
+
|
|
22
|
+
DEFAULT_CAPTCHA_URL = "https://captcha.browsa.io"
|
|
23
|
+
DEFAULT_TIMEOUT = 30.0 # one HTTP request
|
|
24
|
+
DEFAULT_SOLVE_TIMEOUT = 180.0 # createTask to a ready token (a reCAPTCHA v2 puzzle can take 2 minutes)
|
|
25
|
+
DEFAULT_POLL_INTERVAL = 3.0
|
|
26
|
+
USER_AGENT = f"browsa-python/{__version__} (captcha)"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class CaptchaError(errors.BrowsaError):
|
|
30
|
+
"""The API answered ``errorId`` 1. ``code`` is the API's ``errorCode``
|
|
31
|
+
(``ERROR_CAPTCHA_UNSOLVABLE``, ``ERROR_ZERO_BALANCE``, ...); ``task_id`` is set when the
|
|
32
|
+
task exists. Failed and unsolvable tasks are not charged."""
|
|
33
|
+
|
|
34
|
+
def __init__(self, message: str, *, code: Optional[str] = None, task_id: Optional[str] = None,
|
|
35
|
+
status: Optional[int] = None, body: Any = None) -> None:
|
|
36
|
+
super().__init__(message, code=code, status=status, body=body)
|
|
37
|
+
self.task_id = task_id
|
|
38
|
+
self.description = message
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class CaptchaTimeoutError(CaptchaError, errors.TimeoutError):
|
|
42
|
+
"""Local: ``solve`` gave up waiting. The task may still finish; it is charged only if solved."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class Solution(dict): # type: ignore[type-arg]
|
|
46
|
+
"""The task's ``solution`` object, with the task id as ``.task_id``."""
|
|
47
|
+
|
|
48
|
+
task_id: str = ""
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _raise_for(body: Any, status: int) -> Dict[str, Any]:
|
|
52
|
+
if not isinstance(body, dict) or "errorId" not in body:
|
|
53
|
+
raise CaptchaError(f"unexpected answer (HTTP {status})", code=f"HTTP_{status}", status=status, body=body)
|
|
54
|
+
if body.get("errorId"):
|
|
55
|
+
raise CaptchaError(body.get("errorDescription") or body.get("errorCode") or "error",
|
|
56
|
+
code=body.get("errorCode") or None, task_id=body.get("taskId"), status=status, body=body)
|
|
57
|
+
return body
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class CaptchaClient:
|
|
61
|
+
"""Sync client.
|
|
62
|
+
|
|
63
|
+
from browsa.captcha import CaptchaClient, tasks
|
|
64
|
+
cap = CaptchaClient() # BROWSA_API_KEY from the environment
|
|
65
|
+
sol = cap.solve(tasks.turnstile("https://example.com", "0x4AAAA..."))
|
|
66
|
+
print(sol["token"])
|
|
67
|
+
|
|
68
|
+
Args:
|
|
69
|
+
api_key: your Browsa API key (the same key and credits as the browser API);
|
|
70
|
+
default ``BROWSA_API_KEY``.
|
|
71
|
+
base_url: default ``BROWSA_CAPTCHA_URL`` or ``https://captcha.browsa.io``.
|
|
72
|
+
normalize: map other services' task type names to Browsa's (default on).
|
|
73
|
+
opener: replaces ``urllib.request.urlopen`` (tests).
|
|
74
|
+
"""
|
|
75
|
+
|
|
76
|
+
def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None,
|
|
77
|
+
timeout: float = DEFAULT_TIMEOUT, poll_interval: float = DEFAULT_POLL_INTERVAL,
|
|
78
|
+
normalize: bool = True, opener: Optional[Callable[..., Any]] = None) -> None:
|
|
79
|
+
key = api_key or os.environ.get("BROWSA_API_KEY") or ""
|
|
80
|
+
if not key:
|
|
81
|
+
raise ValueError("api_key is required (or set BROWSA_API_KEY)")
|
|
82
|
+
self.api_key = key
|
|
83
|
+
self.base_url = (base_url or os.environ.get("BROWSA_CAPTCHA_URL") or DEFAULT_CAPTCHA_URL).rstrip("/")
|
|
84
|
+
self.timeout = timeout
|
|
85
|
+
self.poll_interval = poll_interval
|
|
86
|
+
self.normalize = normalize
|
|
87
|
+
self._open = opener or urllib.request.urlopen
|
|
88
|
+
|
|
89
|
+
# ── raw methods ──────────────────────────────────────────────────────
|
|
90
|
+
|
|
91
|
+
def call(self, method: str, payload: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
|
|
92
|
+
"""POST ``/{method}`` with ``clientKey`` added; returns the answer, raises CaptchaError."""
|
|
93
|
+
body = {"clientKey": self.api_key, **(payload or {})}
|
|
94
|
+
req = urllib.request.Request(
|
|
95
|
+
f"{self.base_url}/{method}", method="POST", data=json.dumps(body).encode("utf-8"),
|
|
96
|
+
headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": USER_AGENT},
|
|
97
|
+
)
|
|
98
|
+
try:
|
|
99
|
+
with self._open(req, timeout=self.timeout) as resp:
|
|
100
|
+
status, raw = getattr(resp, "status", 200), resp.read()
|
|
101
|
+
except urllib.error.HTTPError as e:
|
|
102
|
+
status, raw = e.code, e.read()
|
|
103
|
+
except urllib.error.URLError as e:
|
|
104
|
+
if isinstance(e.reason, (socket.timeout, TimeoutError)):
|
|
105
|
+
raise errors.TimeoutError(f"request timed out after {self.timeout}s") from e
|
|
106
|
+
raise errors.BrowsaError(f"network error: {e}") from e
|
|
107
|
+
except (socket.timeout, TimeoutError) as e:
|
|
108
|
+
raise errors.TimeoutError(f"request timed out after {self.timeout}s") from e
|
|
109
|
+
except OSError as e:
|
|
110
|
+
raise errors.BrowsaError(f"network error: {e}") from e
|
|
111
|
+
try:
|
|
112
|
+
parsed = json.loads(raw) if raw else None
|
|
113
|
+
except ValueError:
|
|
114
|
+
parsed = None
|
|
115
|
+
return _raise_for(parsed, status)
|
|
116
|
+
|
|
117
|
+
def create_task(self, task: Mapping[str, Any]) -> Dict[str, Any]:
|
|
118
|
+
"""``{"taskId", "status": "ready", "solution"}`` for recognition, ``{"taskId"}`` for tokens."""
|
|
119
|
+
return self.call("createTask", {"task": normalize_task(task) if self.normalize else dict(task)})
|
|
120
|
+
|
|
121
|
+
def get_task_result(self, task_id: str) -> Dict[str, Any]:
|
|
122
|
+
"""``{"status": "processing"}`` or ``{"status": "ready", "solution"}``; a failed task raises."""
|
|
123
|
+
return self.call("getTaskResult", {"taskId": task_id})
|
|
124
|
+
|
|
125
|
+
def get_balance(self) -> float:
|
|
126
|
+
"""Balance: credits with a Browsa key."""
|
|
127
|
+
return float(self.call("getBalance").get("balance") or 0.0)
|
|
128
|
+
|
|
129
|
+
# ── create and wait ──────────────────────────────────────────────────
|
|
130
|
+
|
|
131
|
+
def solve(self, task: Mapping[str, Any], *, timeout: float = DEFAULT_SOLVE_TIMEOUT,
|
|
132
|
+
poll_interval: Optional[float] = None) -> Solution:
|
|
133
|
+
"""Create the task and wait for its solution."""
|
|
134
|
+
created = self.create_task(task)
|
|
135
|
+
tid = str(created.get("taskId") or "")
|
|
136
|
+
if created.get("status") == "ready" and created.get("solution") is not None:
|
|
137
|
+
return _solution(created, tid)
|
|
138
|
+
if not tid:
|
|
139
|
+
raise CaptchaError("createTask returned no taskId", code="ERROR_NO_TASK_ID", body=created)
|
|
140
|
+
interval = self.poll_interval if poll_interval is None else poll_interval
|
|
141
|
+
deadline = time.monotonic() + timeout
|
|
142
|
+
while True:
|
|
143
|
+
time.sleep(min(interval, max(0.0, deadline - time.monotonic())))
|
|
144
|
+
r = self.get_task_result(tid)
|
|
145
|
+
if r.get("status") == "ready":
|
|
146
|
+
return _solution(r, tid)
|
|
147
|
+
if time.monotonic() >= deadline:
|
|
148
|
+
raise CaptchaTimeoutError(f"no solution after {timeout:.0f}s", code="TIMEOUT", task_id=tid)
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _solution(body: Mapping[str, Any], tid: str) -> Solution:
|
|
152
|
+
s = Solution(body.get("solution") or {})
|
|
153
|
+
s.task_id = tid
|
|
154
|
+
return s
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class AsyncCaptchaClient:
|
|
158
|
+
"""Async client: the sync client on a worker thread (``asyncio.to_thread``), like ``AsyncClient``."""
|
|
159
|
+
|
|
160
|
+
def __init__(self, api_key: Optional[str] = None, **kwargs: Any) -> None:
|
|
161
|
+
self._sync = CaptchaClient(api_key, **kwargs)
|
|
162
|
+
|
|
163
|
+
async def __aenter__(self) -> "AsyncCaptchaClient":
|
|
164
|
+
return self
|
|
165
|
+
|
|
166
|
+
async def __aexit__(self, *exc: Any) -> None:
|
|
167
|
+
return None
|
|
168
|
+
|
|
169
|
+
async def create_task(self, task: Mapping[str, Any]) -> Dict[str, Any]:
|
|
170
|
+
return await asyncio.to_thread(self._sync.create_task, task)
|
|
171
|
+
|
|
172
|
+
async def get_task_result(self, task_id: str) -> Dict[str, Any]:
|
|
173
|
+
return await asyncio.to_thread(self._sync.get_task_result, task_id)
|
|
174
|
+
|
|
175
|
+
async def get_balance(self) -> float:
|
|
176
|
+
return await asyncio.to_thread(self._sync.get_balance)
|
|
177
|
+
|
|
178
|
+
async def solve(self, task: Mapping[str, Any], *, timeout: float = DEFAULT_SOLVE_TIMEOUT,
|
|
179
|
+
poll_interval: Optional[float] = None) -> Solution:
|
|
180
|
+
created = await self.create_task(task)
|
|
181
|
+
tid = str(created.get("taskId") or "")
|
|
182
|
+
if created.get("status") == "ready" and created.get("solution") is not None:
|
|
183
|
+
return _solution(created, tid)
|
|
184
|
+
if not tid:
|
|
185
|
+
raise CaptchaError("createTask returned no taskId", code="ERROR_NO_TASK_ID", body=created)
|
|
186
|
+
interval = self._sync.poll_interval if poll_interval is None else poll_interval
|
|
187
|
+
deadline = time.monotonic() + timeout
|
|
188
|
+
while True:
|
|
189
|
+
await asyncio.sleep(min(interval, max(0.0, deadline - time.monotonic())))
|
|
190
|
+
r = await self.get_task_result(tid)
|
|
191
|
+
if r.get("status") == "ready":
|
|
192
|
+
return _solution(r, tid)
|
|
193
|
+
if time.monotonic() >= deadline:
|
|
194
|
+
raise CaptchaTimeoutError(f"no solution after {timeout:.0f}s", code="TIMEOUT", task_id=tid)
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""Shims for the client libraries that cannot be pointed at another server as they are.
|
|
2
|
+
|
|
3
|
+
- 2Captcha (``2captcha-python``) speaks 2Captcha's own ``in.php`` / ``res.php`` protocol.
|
|
4
|
+
``TwoCaptcha`` here has the same constructor and the same ``normal``, ``recaptcha``,
|
|
5
|
+
``turnstile`` and ``balance`` methods, returning ``{"captchaId", "code"}``; change the import.
|
|
6
|
+
- Anti-Captcha (``anticaptchaofficial``) has its host written in the code.
|
|
7
|
+
``use_with_anticaptcha()`` sends its requests to Browsa instead; the rest of your code stays.
|
|
8
|
+
|
|
9
|
+
CapSolver (``capsolver.api_base``) and CapMonster (``ClientOptions(service_url=...)``) take a
|
|
10
|
+
base URL and need nothing from here.
|
|
11
|
+
"""
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
import urllib.error
|
|
17
|
+
import urllib.request
|
|
18
|
+
from typing import Any, Callable, Dict, Mapping, Optional
|
|
19
|
+
|
|
20
|
+
from ._client import USER_AGENT, CaptchaClient, CaptchaError, CaptchaTimeoutError
|
|
21
|
+
from .tasks import normalize_task, recaptcha_v2, recaptcha_v3, turnstile as turnstile_task, image_to_text
|
|
22
|
+
|
|
23
|
+
# ── 2Captcha ─────────────────────────────────────────────────────────────
|
|
24
|
+
|
|
25
|
+
ApiException = CaptchaError # 2captcha-python's names, so `except` clauses keep working
|
|
26
|
+
TimeoutException = CaptchaTimeoutError
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class ValidationException(CaptchaError):
|
|
30
|
+
"""A required argument is missing (2captcha-python raises this name too)."""
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _twocaptcha_proxy(proxy: Any) -> Optional[str]:
|
|
34
|
+
"""2Captcha's ``{"type": "HTTPS", "uri": "login:password@1.2.3.4:3128"}`` -> ``https://login:...``."""
|
|
35
|
+
if not proxy:
|
|
36
|
+
return None
|
|
37
|
+
if isinstance(proxy, str):
|
|
38
|
+
return proxy if "://" in proxy else "http://" + proxy
|
|
39
|
+
typ = str(proxy.get("type") or "http").lower()
|
|
40
|
+
return f"{typ}://{proxy['uri']}"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class TwoCaptcha:
|
|
44
|
+
"""Drop-in for ``twocaptcha.TwoCaptcha`` on the task types Browsa solves.
|
|
45
|
+
|
|
46
|
+
# before: from twocaptcha import TwoCaptcha
|
|
47
|
+
from browsa.captcha.compat import TwoCaptcha
|
|
48
|
+
solver = TwoCaptcha("agt_live_...")
|
|
49
|
+
result = solver.recaptcha(sitekey="6Le-...", url="https://example.com/login")
|
|
50
|
+
token = result["code"]
|
|
51
|
+
|
|
52
|
+
``softId``, ``callback`` and ``server`` (unless it is a Browsa URL) are accepted and ignored.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
def __init__(self, apiKey: str, softId: Optional[int] = None, callback: Optional[str] = None,
|
|
56
|
+
defaultTimeout: int = 120, recaptchaTimeout: int = 600, pollingInterval: int = 10,
|
|
57
|
+
server: Optional[str] = None, extendedResponse: Optional[bool] = None,
|
|
58
|
+
*, base_url: Optional[str] = None, client: Optional[CaptchaClient] = None) -> None:
|
|
59
|
+
if server and "browsa" in server:
|
|
60
|
+
base_url = base_url or (server if "://" in server else "https://" + server)
|
|
61
|
+
self.API_KEY = apiKey
|
|
62
|
+
self.default_timeout = defaultTimeout
|
|
63
|
+
self.recaptcha_timeout = recaptchaTimeout
|
|
64
|
+
self.polling_interval = pollingInterval
|
|
65
|
+
self.extended_response = bool(extendedResponse)
|
|
66
|
+
self._client = client or CaptchaClient(apiKey, base_url=base_url, poll_interval=min(pollingInterval, 5))
|
|
67
|
+
|
|
68
|
+
def _run(self, task: Mapping[str, Any], timeout: float, pick: Callable[[Mapping[str, Any]], Any]) -> Dict[str, Any]:
|
|
69
|
+
sol = self._client.solve(task, timeout=timeout)
|
|
70
|
+
out: Dict[str, Any] = {"captchaId": sol.task_id, "code": pick(sol)}
|
|
71
|
+
if self.extended_response:
|
|
72
|
+
out["solution"] = dict(sol)
|
|
73
|
+
return out
|
|
74
|
+
|
|
75
|
+
def normal(self, file: Any, **kwargs: Any) -> Dict[str, Any]:
|
|
76
|
+
"""Image text. ``file``: a path, a base64 string, or bytes."""
|
|
77
|
+
if isinstance(file, (bytes, bytearray)):
|
|
78
|
+
body: Any = bytes(file)
|
|
79
|
+
elif isinstance(file, str) and os.path.isfile(file):
|
|
80
|
+
with open(file, "rb") as f:
|
|
81
|
+
body = f.read()
|
|
82
|
+
elif isinstance(file, str) and file:
|
|
83
|
+
body = file
|
|
84
|
+
else:
|
|
85
|
+
raise ValidationException("file must be a path, a base64 string or bytes", code="ERROR_INVALID_TASK_DATA")
|
|
86
|
+
sol_text = lambda s: s.get("text") if "text" in s else ",".join(s.get("answers") or []) # noqa: E731
|
|
87
|
+
return self._run(image_to_text(body), kwargs.get("timeout", self.default_timeout), sol_text)
|
|
88
|
+
|
|
89
|
+
def recaptcha(self, sitekey: str, url: str, version: str = "v2", enterprise: int = 0, **kwargs: Any) -> Dict[str, Any]:
|
|
90
|
+
"""reCAPTCHA v2 or v3 (``version="v3"``, ``action``, ``score``), ``invisible=1``, ``enterprise=1``."""
|
|
91
|
+
if not sitekey or not url:
|
|
92
|
+
raise ValidationException("sitekey and url are required", code="ERROR_INVALID_TASK_DATA")
|
|
93
|
+
proxy = _twocaptcha_proxy(kwargs.get("proxy"))
|
|
94
|
+
if str(version).lower() == "v3":
|
|
95
|
+
task = recaptcha_v3(url, sitekey, page_action=kwargs.get("action"), enterprise=bool(enterprise),
|
|
96
|
+
min_score=kwargs.get("score") or kwargs.get("min_score"), proxy=proxy)
|
|
97
|
+
else:
|
|
98
|
+
task = recaptcha_v2(url, sitekey, invisible=bool(int(kwargs.get("invisible") or 0)),
|
|
99
|
+
enterprise=bool(enterprise), api_domain=kwargs.get("domain"), proxy=proxy)
|
|
100
|
+
return self._run(task, kwargs.get("timeout", self.recaptcha_timeout), lambda s: s.get("gRecaptchaResponse"))
|
|
101
|
+
|
|
102
|
+
def turnstile(self, sitekey: str, url: str, **kwargs: Any) -> Dict[str, Any]:
|
|
103
|
+
"""Cloudflare Turnstile (``action``, ``data`` = cData)."""
|
|
104
|
+
if not sitekey or not url:
|
|
105
|
+
raise ValidationException("sitekey and url are required", code="ERROR_INVALID_TASK_DATA")
|
|
106
|
+
task = turnstile_task(url, sitekey, action=kwargs.get("action"), cdata=kwargs.get("data"),
|
|
107
|
+
proxy=_twocaptcha_proxy(kwargs.get("proxy")))
|
|
108
|
+
return self._run(task, kwargs.get("timeout", self.default_timeout), lambda s: s.get("token"))
|
|
109
|
+
|
|
110
|
+
def balance(self) -> float:
|
|
111
|
+
return self._client.get_balance()
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
# ── Anti-Captcha ─────────────────────────────────────────────────────────
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def use_with_anticaptcha(base_url: Optional[str] = None, *, opener: Optional[Callable[..., Any]] = None) -> Callable[[], None]:
|
|
118
|
+
"""Send ``anticaptchaofficial``'s requests to Browsa. Call once, before solving:
|
|
119
|
+
|
|
120
|
+
from anticaptchaofficial.recaptchav2proxyless import recaptchaV2Proxyless
|
|
121
|
+
from browsa.captcha.compat import use_with_anticaptcha
|
|
122
|
+
use_with_anticaptcha()
|
|
123
|
+
solver = recaptchaV2Proxyless()
|
|
124
|
+
solver.set_key("agt_live_...") # your Browsa key
|
|
125
|
+
...
|
|
126
|
+
|
|
127
|
+
Task type names are mapped to Browsa's on the way. Returns a function that undoes it.
|
|
128
|
+
"""
|
|
129
|
+
from anticaptchaofficial import antinetworking # the caller's own dependency
|
|
130
|
+
|
|
131
|
+
base = (base_url or os.environ.get("BROWSA_CAPTCHA_URL") or "https://captcha.browsa.io").rstrip("/")
|
|
132
|
+
open_ = opener or urllib.request.urlopen
|
|
133
|
+
cls = antinetworking.antiNetworking
|
|
134
|
+
original = cls.make_request
|
|
135
|
+
|
|
136
|
+
def make_request(self: Any, method: str, data: Dict[str, Any]) -> Any:
|
|
137
|
+
self.log("making request to " + method)
|
|
138
|
+
payload = dict(data)
|
|
139
|
+
if method == "createTask" and isinstance(payload.get("task"), dict):
|
|
140
|
+
payload["task"] = normalize_task({k: v for k, v in payload["task"].items() if v is not None})
|
|
141
|
+
req = urllib.request.Request(f"{base}/{method}", method="POST", data=json.dumps(payload).encode("utf-8"),
|
|
142
|
+
headers={"Content-Type": "application/json", "Accept": "application/json",
|
|
143
|
+
"User-Agent": USER_AGENT})
|
|
144
|
+
try:
|
|
145
|
+
with open_(req, timeout=30) as resp:
|
|
146
|
+
return json.loads(resp.read())
|
|
147
|
+
except urllib.error.HTTPError as e:
|
|
148
|
+
try:
|
|
149
|
+
return json.loads(e.read())
|
|
150
|
+
except ValueError:
|
|
151
|
+
self.err_string = f"http_error {e.code}"
|
|
152
|
+
return 0
|
|
153
|
+
except (urllib.error.URLError, OSError, ValueError) as e:
|
|
154
|
+
self.err_string = f"Connection error: {e}"
|
|
155
|
+
return 0
|
|
156
|
+
|
|
157
|
+
cls.make_request = make_request
|
|
158
|
+
|
|
159
|
+
def undo() -> None:
|
|
160
|
+
cls.make_request = original
|
|
161
|
+
|
|
162
|
+
return undo
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
__all__ = ["TwoCaptcha", "ApiException", "TimeoutException", "ValidationException", "use_with_anticaptcha"]
|