capturekitdev 0.1.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.
- capturekitdev-0.1.0/.gitignore +14 -0
- capturekitdev-0.1.0/LICENSE +21 -0
- capturekitdev-0.1.0/PKG-INFO +215 -0
- capturekitdev-0.1.0/README.md +184 -0
- capturekitdev-0.1.0/examples/README.md +13 -0
- capturekitdev-0.1.0/examples/any_endpoint.py +11 -0
- capturekitdev-0.1.0/examples/async_client.py +14 -0
- capturekitdev-0.1.0/examples/binary_response.py +14 -0
- capturekitdev-0.1.0/examples/json_response.py +10 -0
- capturekitdev-0.1.0/examples/wait_for_job.py +11 -0
- capturekitdev-0.1.0/pyproject.toml +79 -0
- capturekitdev-0.1.0/src/capturekit/__init__.py +61 -0
- capturekitdev-0.1.0/src/capturekit/_endpoints.py +62 -0
- capturekitdev-0.1.0/src/capturekit/_operations.py +791 -0
- capturekitdev-0.1.0/src/capturekit/_response.py +82 -0
- capturekitdev-0.1.0/src/capturekit/_serialization.py +109 -0
- capturekitdev-0.1.0/src/capturekit/_version.py +1 -0
- capturekitdev-0.1.0/src/capturekit/client.py +533 -0
- capturekitdev-0.1.0/src/capturekit/errors.py +85 -0
- capturekitdev-0.1.0/src/capturekit/models.py +81 -0
- capturekitdev-0.1.0/src/capturekit/py.typed +1 -0
- capturekitdev-0.1.0/tests/__init__.py +1 -0
- capturekitdev-0.1.0/tests/test_client.py +381 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 CaptureKit
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: capturekitdev
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Official Python SDK for the CaptureKit screenshot API.
|
|
5
|
+
Project-URL: Homepage, https://www.capturekit.dev
|
|
6
|
+
Project-URL: Documentation, https://app.capturekit.dev/openapi
|
|
7
|
+
Project-URL: Repository, https://github.com/capturekitdev/capturekit-python
|
|
8
|
+
Project-URL: Issues, https://github.com/capturekitdev/capturekit-python/issues
|
|
9
|
+
Author-email: CaptureKit <contact@capturekit.dev>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: api,capturekit,screenshot-api,sdk,url-to-pdf,web-content,website-screenshot
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: httpx<1,>=0.27
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: build<2,>=1.2; extra == 'dev'
|
|
26
|
+
Requires-Dist: mypy>=1.13; extra == 'dev'
|
|
27
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest>=8.3; extra == 'dev'
|
|
29
|
+
Requires-Dist: ruff<1,>=0.8; extra == 'dev'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# CaptureKit Python SDK
|
|
33
|
+
|
|
34
|
+
The official Python SDK for the [CaptureKit](https://www.capturekit.dev) screenshot API.
|
|
35
|
+
|
|
36
|
+
Capture websites as PNG, JPEG, WebP or PDF, extract their content, or analyse them with AI.
|
|
37
|
+
|
|
38
|
+
The SDK exposes **7 typed methods**, one per documented endpoint, with blocking and `asyncio` clients built on [HTTPX](https://www.python-httpx.org/), plus a generic `request()`.
|
|
39
|
+
|
|
40
|
+
## Requirements
|
|
41
|
+
|
|
42
|
+
- Python 3.11 or newer
|
|
43
|
+
|
|
44
|
+
## Installation
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
pip install capturekitdev
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Get your API key
|
|
51
|
+
|
|
52
|
+
[Sign up for CaptureKit](https://app.capturekit.dev/register) or sign in, then copy your API key from the [dashboard](https://app.capturekit.dev). The client reads the `CAPTUREKIT_API_KEY` environment variable when no key is passed.
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
import os
|
|
58
|
+
|
|
59
|
+
from capturekit import CaptureKitClient
|
|
60
|
+
|
|
61
|
+
with CaptureKitClient(os.environ["CAPTUREKIT_API_KEY"]) as client:
|
|
62
|
+
response = client.content(url="https://example.com")
|
|
63
|
+
print(response.data)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Keyword arguments mirror the [API reference](https://app.capturekit.dev/openapi). Python keywords get a trailing underscore (`from_=`), and the wire name is used on the request.
|
|
67
|
+
|
|
68
|
+
## Binary responses
|
|
69
|
+
|
|
70
|
+
Endpoints that can return a file (image, PDF…) return a `JsonResponse` or a `BinaryResponse`:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from capturekit import BinaryResponse
|
|
74
|
+
|
|
75
|
+
response = client.capture(url="https://example.com", format="png")
|
|
76
|
+
if isinstance(response, BinaryResponse):
|
|
77
|
+
with open("screenshot.png", "wb") as file:
|
|
78
|
+
file.write(response.bytes)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Async jobs
|
|
82
|
+
|
|
83
|
+
Any call accepts `is_async: true` (useful past the 60-second server limit): the response is then a `job_id`. `wait_for_job()` polls `GET /v1/jobs/{id}` until the job reaches a terminal status (`CompletedJob`, `Error`, `NotFound`, `BadRequest`):
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
submitted = client.content(url="https://example.com", is_async=True)
|
|
87
|
+
job = client.wait_for_job(
|
|
88
|
+
submitted.data["job_id"],
|
|
89
|
+
on_progress=lambda j: print(j["status"], j.get("progress")),
|
|
90
|
+
)
|
|
91
|
+
print(job.data)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Async I/O
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
import asyncio
|
|
98
|
+
|
|
99
|
+
from capturekit import AsyncCaptureKitClient
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
async def main() -> None:
|
|
103
|
+
async with AsyncCaptureKitClient() as client:
|
|
104
|
+
response = await client.content(url="https://example.com")
|
|
105
|
+
print(response.data)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
asyncio.run(main())
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## GET or POST
|
|
112
|
+
|
|
113
|
+
Methods use GET when the endpoint supports it (parameters in the query string). POST sends the same parameters as a JSON body:
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from capturekit import RequestOptions
|
|
117
|
+
|
|
118
|
+
client.analyze(url="test", request_options=RequestOptions(method="POST"))
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`None` values are omitted, `False` and `0` are sent, and sequences repeat the parameter name.
|
|
122
|
+
|
|
123
|
+
## Any endpoint
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
response = client.request("GET", "/v1/usage")
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Errors
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from capturekit import CaptureKitAPIError
|
|
133
|
+
|
|
134
|
+
try:
|
|
135
|
+
client.content(url="https://example.com")
|
|
136
|
+
except CaptureKitAPIError as error:
|
|
137
|
+
print(error.status, error, error.response_body)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
| Error | When |
|
|
141
|
+
| --- | --- |
|
|
142
|
+
| `CaptureKitConfigurationError` | Missing API key, invalid options, unsupported method, closed client. |
|
|
143
|
+
| `CaptureKitSerializationError` | A required parameter is missing or a value can't be sent. |
|
|
144
|
+
| `CaptureKitTransportError` | Network failure or timeout. |
|
|
145
|
+
| `CaptureKitAPIError` | Non-2xx status (`status`, `error_message`, `response_body`, `raw_response`). |
|
|
146
|
+
| `CaptureKitResponseDecodingError` | A success response could not be decoded. |
|
|
147
|
+
|
|
148
|
+
All of them extend `CaptureKitError`.
|
|
149
|
+
|
|
150
|
+
## Retries
|
|
151
|
+
|
|
152
|
+
Requests are retried up to 3 times after a network error, a `408`, `500`, `502`, `503` or `504`, or a rate limit — which the API returns as `401` (or `429`) with a `Rate limit exceeded` message. Per-key quota errors (`…: quota daily`) are not retried, nor are `400`, `402`, `404` or client-side timeouts. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a `Retry-After` header wins.
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
client = CaptureKitClient(max_retries=5, retry_delay=0.5)
|
|
156
|
+
|
|
157
|
+
# or for one request
|
|
158
|
+
client.content(url="https://example.com", request_options=RequestOptions(max_retries=0))
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## Batch requests
|
|
162
|
+
|
|
163
|
+
`batch()` runs a function per item on 10 threads (`concurrency`) and returns one `BatchResult` per item, in input order. A failing item never stops the others. `AsyncCaptureKitClient.batch()` does the same with `asyncio`.
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
inputs = ["https://example.com", "https://www.capturekit.dev", "https://github.com"]
|
|
167
|
+
results = client.batch(inputs, lambda url: client.content(url=url), concurrency=5)
|
|
168
|
+
|
|
169
|
+
for result in results:
|
|
170
|
+
if result.ok:
|
|
171
|
+
print(result.value.data)
|
|
172
|
+
else:
|
|
173
|
+
print(inputs[result.index], result.error)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
| Constant | Default | Description |
|
|
177
|
+
| --- | --- | --- |
|
|
178
|
+
| `DEFAULT_CONCURRENCY` | `10` | Tasks run at the same time by batch |
|
|
179
|
+
| `DEFAULT_TIMEOUT` | `120.0` | Request timeout (seconds) |
|
|
180
|
+
| `MAX_RETRIES` | `3` | Retry attempts after a network error, a 408/5xx or a rate limit |
|
|
181
|
+
| `RETRY_BACKOFF_FACTOR` | `1.5` | Exponential backoff multiplier |
|
|
182
|
+
| `DEFAULT_RETRY_DELAY` | `1.0` | Delay before the first retry (seconds) |
|
|
183
|
+
|
|
184
|
+
## Timeouts and custom HTTPX clients
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
import httpx
|
|
188
|
+
|
|
189
|
+
from capturekit import CaptureKitClient, RequestOptions
|
|
190
|
+
|
|
191
|
+
client = CaptureKitClient(timeout=60) # seconds, default 120, None disables
|
|
192
|
+
client.content(url="https://example.com", request_options=RequestOptions(timeout=30))
|
|
193
|
+
|
|
194
|
+
# Bring your own HTTPX client (proxies, limits, event hooks…). You keep ownership of it.
|
|
195
|
+
http_client = httpx.Client(proxy="http://localhost:8080")
|
|
196
|
+
client = CaptureKitClient(http_client=http_client)
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## Endpoints
|
|
200
|
+
|
|
201
|
+
7 methods, generated from the [OpenAPI document](https://app.capturekit.dev/openapi).
|
|
202
|
+
|
|
203
|
+
| Method | HTTP | Description |
|
|
204
|
+
| --- | --- | --- |
|
|
205
|
+
| `analyze()` | GET / POST `/v1/analyze` | AI Content API analyzes any webpage and returns AI insights summary, value proposition, features, categories, use cases, and optional conta… |
|
|
206
|
+
| `capture()` | GET / POST `/v1/capture` | Browser-like Screenshot API that captures webpages as PNG/JPEG/WebP or PDF for previews, QA, reporting, monitoring, and archiving no headle… |
|
|
207
|
+
| `content()` | GET / POST `/v1/content` | CaptureKit Content API extracts structured webpage data, metadata, links, HTML/Markdown: in one request for SEO, monitoring, indexing and a… |
|
|
208
|
+
| `jobs()` | GET `/v1/jobs/{id}` | Poll the status, progress (0–100) and result of a job started with is_async=true. Polling is free. Poll until status is terminal: Completed… |
|
|
209
|
+
| `stats()` | GET `/v1/stats` | Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 mea… |
|
|
210
|
+
| `usage()` | GET `/v1/usage` | Retrieve real-time usage statistics and credit balance for your CaptureKit account. |
|
|
211
|
+
| `website_crawler()` | GET / POST `/v1/website/crawler` | Website Crawler API fetches raw HTML from any webpage in request mode (no rendering) for fast scraping, audits, monitoring, and link/metada… |
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# CaptureKit Python SDK
|
|
2
|
+
|
|
3
|
+
The official Python SDK for the [CaptureKit](https://www.capturekit.dev) screenshot API.
|
|
4
|
+
|
|
5
|
+
Capture websites as PNG, JPEG, WebP or PDF, extract their content, or analyse them with AI.
|
|
6
|
+
|
|
7
|
+
The SDK exposes **7 typed methods**, one per documented endpoint, with blocking and `asyncio` clients built on [HTTPX](https://www.python-httpx.org/), plus a generic `request()`.
|
|
8
|
+
|
|
9
|
+
## Requirements
|
|
10
|
+
|
|
11
|
+
- Python 3.11 or newer
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pip install capturekitdev
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Get your API key
|
|
20
|
+
|
|
21
|
+
[Sign up for CaptureKit](https://app.capturekit.dev/register) or sign in, then copy your API key from the [dashboard](https://app.capturekit.dev). The client reads the `CAPTUREKIT_API_KEY` environment variable when no key is passed.
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
import os
|
|
27
|
+
|
|
28
|
+
from capturekit import CaptureKitClient
|
|
29
|
+
|
|
30
|
+
with CaptureKitClient(os.environ["CAPTUREKIT_API_KEY"]) as client:
|
|
31
|
+
response = client.content(url="https://example.com")
|
|
32
|
+
print(response.data)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Keyword arguments mirror the [API reference](https://app.capturekit.dev/openapi). Python keywords get a trailing underscore (`from_=`), and the wire name is used on the request.
|
|
36
|
+
|
|
37
|
+
## Binary responses
|
|
38
|
+
|
|
39
|
+
Endpoints that can return a file (image, PDF…) return a `JsonResponse` or a `BinaryResponse`:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from capturekit import BinaryResponse
|
|
43
|
+
|
|
44
|
+
response = client.capture(url="https://example.com", format="png")
|
|
45
|
+
if isinstance(response, BinaryResponse):
|
|
46
|
+
with open("screenshot.png", "wb") as file:
|
|
47
|
+
file.write(response.bytes)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Async jobs
|
|
51
|
+
|
|
52
|
+
Any call accepts `is_async: true` (useful past the 60-second server limit): the response is then a `job_id`. `wait_for_job()` polls `GET /v1/jobs/{id}` until the job reaches a terminal status (`CompletedJob`, `Error`, `NotFound`, `BadRequest`):
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
submitted = client.content(url="https://example.com", is_async=True)
|
|
56
|
+
job = client.wait_for_job(
|
|
57
|
+
submitted.data["job_id"],
|
|
58
|
+
on_progress=lambda j: print(j["status"], j.get("progress")),
|
|
59
|
+
)
|
|
60
|
+
print(job.data)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Async I/O
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import asyncio
|
|
67
|
+
|
|
68
|
+
from capturekit import AsyncCaptureKitClient
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
async def main() -> None:
|
|
72
|
+
async with AsyncCaptureKitClient() as client:
|
|
73
|
+
response = await client.content(url="https://example.com")
|
|
74
|
+
print(response.data)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
asyncio.run(main())
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## GET or POST
|
|
81
|
+
|
|
82
|
+
Methods use GET when the endpoint supports it (parameters in the query string). POST sends the same parameters as a JSON body:
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from capturekit import RequestOptions
|
|
86
|
+
|
|
87
|
+
client.analyze(url="test", request_options=RequestOptions(method="POST"))
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`None` values are omitted, `False` and `0` are sent, and sequences repeat the parameter name.
|
|
91
|
+
|
|
92
|
+
## Any endpoint
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
response = client.request("GET", "/v1/usage")
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Errors
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from capturekit import CaptureKitAPIError
|
|
102
|
+
|
|
103
|
+
try:
|
|
104
|
+
client.content(url="https://example.com")
|
|
105
|
+
except CaptureKitAPIError as error:
|
|
106
|
+
print(error.status, error, error.response_body)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
| Error | When |
|
|
110
|
+
| --- | --- |
|
|
111
|
+
| `CaptureKitConfigurationError` | Missing API key, invalid options, unsupported method, closed client. |
|
|
112
|
+
| `CaptureKitSerializationError` | A required parameter is missing or a value can't be sent. |
|
|
113
|
+
| `CaptureKitTransportError` | Network failure or timeout. |
|
|
114
|
+
| `CaptureKitAPIError` | Non-2xx status (`status`, `error_message`, `response_body`, `raw_response`). |
|
|
115
|
+
| `CaptureKitResponseDecodingError` | A success response could not be decoded. |
|
|
116
|
+
|
|
117
|
+
All of them extend `CaptureKitError`.
|
|
118
|
+
|
|
119
|
+
## Retries
|
|
120
|
+
|
|
121
|
+
Requests are retried up to 3 times after a network error, a `408`, `500`, `502`, `503` or `504`, or a rate limit — which the API returns as `401` (or `429`) with a `Rate limit exceeded` message. Per-key quota errors (`…: quota daily`) are not retried, nor are `400`, `402`, `404` or client-side timeouts. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a `Retry-After` header wins.
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
client = CaptureKitClient(max_retries=5, retry_delay=0.5)
|
|
125
|
+
|
|
126
|
+
# or for one request
|
|
127
|
+
client.content(url="https://example.com", request_options=RequestOptions(max_retries=0))
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Batch requests
|
|
131
|
+
|
|
132
|
+
`batch()` runs a function per item on 10 threads (`concurrency`) and returns one `BatchResult` per item, in input order. A failing item never stops the others. `AsyncCaptureKitClient.batch()` does the same with `asyncio`.
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
inputs = ["https://example.com", "https://www.capturekit.dev", "https://github.com"]
|
|
136
|
+
results = client.batch(inputs, lambda url: client.content(url=url), concurrency=5)
|
|
137
|
+
|
|
138
|
+
for result in results:
|
|
139
|
+
if result.ok:
|
|
140
|
+
print(result.value.data)
|
|
141
|
+
else:
|
|
142
|
+
print(inputs[result.index], result.error)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
| Constant | Default | Description |
|
|
146
|
+
| --- | --- | --- |
|
|
147
|
+
| `DEFAULT_CONCURRENCY` | `10` | Tasks run at the same time by batch |
|
|
148
|
+
| `DEFAULT_TIMEOUT` | `120.0` | Request timeout (seconds) |
|
|
149
|
+
| `MAX_RETRIES` | `3` | Retry attempts after a network error, a 408/5xx or a rate limit |
|
|
150
|
+
| `RETRY_BACKOFF_FACTOR` | `1.5` | Exponential backoff multiplier |
|
|
151
|
+
| `DEFAULT_RETRY_DELAY` | `1.0` | Delay before the first retry (seconds) |
|
|
152
|
+
|
|
153
|
+
## Timeouts and custom HTTPX clients
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
import httpx
|
|
157
|
+
|
|
158
|
+
from capturekit import CaptureKitClient, RequestOptions
|
|
159
|
+
|
|
160
|
+
client = CaptureKitClient(timeout=60) # seconds, default 120, None disables
|
|
161
|
+
client.content(url="https://example.com", request_options=RequestOptions(timeout=30))
|
|
162
|
+
|
|
163
|
+
# Bring your own HTTPX client (proxies, limits, event hooks…). You keep ownership of it.
|
|
164
|
+
http_client = httpx.Client(proxy="http://localhost:8080")
|
|
165
|
+
client = CaptureKitClient(http_client=http_client)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## Endpoints
|
|
169
|
+
|
|
170
|
+
7 methods, generated from the [OpenAPI document](https://app.capturekit.dev/openapi).
|
|
171
|
+
|
|
172
|
+
| Method | HTTP | Description |
|
|
173
|
+
| --- | --- | --- |
|
|
174
|
+
| `analyze()` | GET / POST `/v1/analyze` | AI Content API analyzes any webpage and returns AI insights summary, value proposition, features, categories, use cases, and optional conta… |
|
|
175
|
+
| `capture()` | GET / POST `/v1/capture` | Browser-like Screenshot API that captures webpages as PNG/JPEG/WebP or PDF for previews, QA, reporting, monitoring, and archiving no headle… |
|
|
176
|
+
| `content()` | GET / POST `/v1/content` | CaptureKit Content API extracts structured webpage data, metadata, links, HTML/Markdown: in one request for SEO, monitoring, indexing and a… |
|
|
177
|
+
| `jobs()` | GET `/v1/jobs/{id}` | Poll the status, progress (0–100) and result of a job started with is_async=true. Polling is free. Poll until status is terminal: Completed… |
|
|
178
|
+
| `stats()` | GET `/v1/stats` | Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 mea… |
|
|
179
|
+
| `usage()` | GET `/v1/usage` | Retrieve real-time usage statistics and credit balance for your CaptureKit account. |
|
|
180
|
+
| `website_crawler()` | GET / POST `/v1/website/crawler` | Website Crawler API fetches raw HTML from any webpage in request mode (no rendering) for fast scraping, audits, monitoring, and link/metada… |
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
```sh
|
|
4
|
+
pip install capturekitdev
|
|
5
|
+
export CAPTUREKIT_API_KEY="YOUR_API_KEY"
|
|
6
|
+
python examples/json_response.py
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
- `json_response.py` — call the featured endpoint and print the JSON result.
|
|
10
|
+
- `binary_response.py` — save a binary response to a file.
|
|
11
|
+
- `async_client.py` — use `AsyncCaptureKitClient`.
|
|
12
|
+
- `any_endpoint.py` — call any path with `request()` and handle API errors.
|
|
13
|
+
- `wait_for_job.py` — start an async job and wait for its result.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Call any path with request() and handle API errors."""
|
|
2
|
+
|
|
3
|
+
from capturekit import CaptureKitAPIError, CaptureKitClient, JsonResponse
|
|
4
|
+
|
|
5
|
+
with CaptureKitClient() as client: # reads CAPTUREKIT_API_KEY
|
|
6
|
+
try:
|
|
7
|
+
response = client.request("GET", "/v1/usage")
|
|
8
|
+
if isinstance(response, JsonResponse):
|
|
9
|
+
print(response.data)
|
|
10
|
+
except CaptureKitAPIError as error:
|
|
11
|
+
print(f"HTTP {error.status}: {error}")
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""Use the asyncio client."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
|
|
5
|
+
from capturekit import AsyncCaptureKitClient
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
async def main() -> None:
|
|
9
|
+
async with AsyncCaptureKitClient() as client: # reads CAPTUREKIT_API_KEY
|
|
10
|
+
response = await client.content(url="https://example.com")
|
|
11
|
+
print(response.data)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
asyncio.run(main())
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""Save a binary response to a file."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
|
|
5
|
+
from capturekit import BinaryResponse, CaptureKitClient
|
|
6
|
+
|
|
7
|
+
with CaptureKitClient(os.environ["CAPTUREKIT_API_KEY"]) as client:
|
|
8
|
+
response = client.capture(url="https://example.com", format="png")
|
|
9
|
+
if isinstance(response, BinaryResponse):
|
|
10
|
+
with open("screenshot.png", "wb") as file:
|
|
11
|
+
file.write(response.bytes)
|
|
12
|
+
print(f"Saved screenshot.png ({response.content_type}, {len(response.bytes)} bytes)")
|
|
13
|
+
else:
|
|
14
|
+
print(response.data)
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Call the featured endpoint and print the JSON result."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
from capturekit import CaptureKitClient
|
|
7
|
+
|
|
8
|
+
with CaptureKitClient(os.environ["CAPTUREKIT_API_KEY"]) as client:
|
|
9
|
+
response = client.content(url="https://example.com")
|
|
10
|
+
print(json.dumps(response.data, indent=2))
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Start an async job and wait for its result."""
|
|
2
|
+
|
|
3
|
+
from capturekit import CaptureKitClient
|
|
4
|
+
|
|
5
|
+
with CaptureKitClient() as client: # reads CAPTUREKIT_API_KEY
|
|
6
|
+
submitted = client.content(url="https://example.com", is_async=True)
|
|
7
|
+
job = client.wait_for_job(
|
|
8
|
+
submitted.data["job_id"],
|
|
9
|
+
on_progress=lambda j: print(j["status"], j.get("progress")),
|
|
10
|
+
)
|
|
11
|
+
print(job.data)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.26,<2"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "capturekitdev"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Official Python SDK for the CaptureKit screenshot API."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "CaptureKit", email = "contact@capturekit.dev" },
|
|
15
|
+
]
|
|
16
|
+
keywords = [
|
|
17
|
+
"screenshot-api",
|
|
18
|
+
"website-screenshot",
|
|
19
|
+
"url-to-pdf",
|
|
20
|
+
"web-content",
|
|
21
|
+
"api",
|
|
22
|
+
"sdk",
|
|
23
|
+
"capturekit",
|
|
24
|
+
]
|
|
25
|
+
classifiers = [
|
|
26
|
+
"Intended Audience :: Developers",
|
|
27
|
+
"Operating System :: OS Independent",
|
|
28
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
29
|
+
"Programming Language :: Python :: 3.11",
|
|
30
|
+
"Programming Language :: Python :: 3.12",
|
|
31
|
+
"Programming Language :: Python :: 3.13",
|
|
32
|
+
"Programming Language :: Python :: 3.14",
|
|
33
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
34
|
+
"Typing :: Typed",
|
|
35
|
+
]
|
|
36
|
+
dependencies = [
|
|
37
|
+
"httpx>=0.27,<1",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.optional-dependencies]
|
|
41
|
+
dev = [
|
|
42
|
+
"build>=1.2,<2",
|
|
43
|
+
"mypy>=1.13",
|
|
44
|
+
"pytest>=8.3",
|
|
45
|
+
"pytest-asyncio>=0.24",
|
|
46
|
+
"ruff>=0.8,<1",
|
|
47
|
+
]
|
|
48
|
+
|
|
49
|
+
[project.urls]
|
|
50
|
+
Homepage = "https://www.capturekit.dev"
|
|
51
|
+
Documentation = "https://app.capturekit.dev/openapi"
|
|
52
|
+
Repository = "https://github.com/capturekitdev/capturekit-python"
|
|
53
|
+
Issues = "https://github.com/capturekitdev/capturekit-python/issues"
|
|
54
|
+
|
|
55
|
+
[tool.hatch.build.targets.sdist]
|
|
56
|
+
include = ["/examples", "/src", "/tests", "/LICENSE", "/README.md", "/pyproject.toml"]
|
|
57
|
+
|
|
58
|
+
[tool.hatch.build.targets.wheel]
|
|
59
|
+
packages = ["src/capturekit"]
|
|
60
|
+
|
|
61
|
+
[tool.mypy]
|
|
62
|
+
python_version = "3.11"
|
|
63
|
+
strict = true
|
|
64
|
+
files = ["src", "tests", "examples"]
|
|
65
|
+
|
|
66
|
+
[tool.pytest.ini_options]
|
|
67
|
+
addopts = "-ra"
|
|
68
|
+
asyncio_mode = "strict"
|
|
69
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
70
|
+
testpaths = ["tests"]
|
|
71
|
+
|
|
72
|
+
[tool.ruff]
|
|
73
|
+
target-version = "py311"
|
|
74
|
+
line-length = 100
|
|
75
|
+
src = ["src", "tests", "examples"]
|
|
76
|
+
extend-exclude = ["*.md"]
|
|
77
|
+
|
|
78
|
+
[tool.ruff.lint]
|
|
79
|
+
select = ["E4", "E7", "E9", "F", "I", "UP", "B"]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""Official Python SDK for the CaptureKit API."""
|
|
2
|
+
|
|
3
|
+
from ._endpoints import ENDPOINTS
|
|
4
|
+
from ._version import __version__
|
|
5
|
+
from .client import (
|
|
6
|
+
DEFAULT_BASE_URL,
|
|
7
|
+
DEFAULT_CONCURRENCY,
|
|
8
|
+
DEFAULT_RETRY_DELAY,
|
|
9
|
+
DEFAULT_TIMEOUT,
|
|
10
|
+
MAX_RETRIES,
|
|
11
|
+
RETRY_BACKOFF_FACTOR,
|
|
12
|
+
AsyncCaptureKitClient,
|
|
13
|
+
CaptureKitClient,
|
|
14
|
+
)
|
|
15
|
+
from .errors import (
|
|
16
|
+
CaptureKitAPIError,
|
|
17
|
+
CaptureKitConfigurationError,
|
|
18
|
+
CaptureKitError,
|
|
19
|
+
CaptureKitJobTimeoutError,
|
|
20
|
+
CaptureKitResponseDecodingError,
|
|
21
|
+
CaptureKitSerializationError,
|
|
22
|
+
CaptureKitTransportError,
|
|
23
|
+
)
|
|
24
|
+
from .models import (
|
|
25
|
+
APIResponse,
|
|
26
|
+
BatchResult,
|
|
27
|
+
BinaryResponse,
|
|
28
|
+
EndpointDefinition,
|
|
29
|
+
HTTPMethod,
|
|
30
|
+
JsonResponse,
|
|
31
|
+
RawResponse,
|
|
32
|
+
RequestOptions,
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"APIResponse",
|
|
37
|
+
"AsyncCaptureKitClient",
|
|
38
|
+
"BatchResult",
|
|
39
|
+
"BinaryResponse",
|
|
40
|
+
"DEFAULT_BASE_URL",
|
|
41
|
+
"DEFAULT_CONCURRENCY",
|
|
42
|
+
"DEFAULT_RETRY_DELAY",
|
|
43
|
+
"DEFAULT_TIMEOUT",
|
|
44
|
+
"MAX_RETRIES",
|
|
45
|
+
"RETRY_BACKOFF_FACTOR",
|
|
46
|
+
"ENDPOINTS",
|
|
47
|
+
"EndpointDefinition",
|
|
48
|
+
"HTTPMethod",
|
|
49
|
+
"JsonResponse",
|
|
50
|
+
"RawResponse",
|
|
51
|
+
"RequestOptions",
|
|
52
|
+
"CaptureKitAPIError",
|
|
53
|
+
"CaptureKitClient",
|
|
54
|
+
"CaptureKitConfigurationError",
|
|
55
|
+
"CaptureKitError",
|
|
56
|
+
"CaptureKitJobTimeoutError",
|
|
57
|
+
"CaptureKitResponseDecodingError",
|
|
58
|
+
"CaptureKitSerializationError",
|
|
59
|
+
"CaptureKitTransportError",
|
|
60
|
+
"__version__",
|
|
61
|
+
]
|