html-css-to-image 0.2.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.
- html_css_to_image-0.2.0/.github/workflows/ci.yml +43 -0
- html_css_to_image-0.2.0/.github/workflows/publish.yml +147 -0
- html_css_to_image-0.2.0/.gitignore +10 -0
- html_css_to_image-0.2.0/LICENSE +21 -0
- html_css_to_image-0.2.0/PKG-INFO +300 -0
- html_css_to_image-0.2.0/README.md +270 -0
- html_css_to_image-0.2.0/pyproject.toml +58 -0
- html_css_to_image-0.2.0/src/html_css_to_image/__init__.py +75 -0
- html_css_to_image-0.2.0/src/html_css_to_image/_request_mapper.py +198 -0
- html_css_to_image-0.2.0/src/html_css_to_image/_response_mapper.py +168 -0
- html_css_to_image-0.2.0/src/html_css_to_image/_transport.py +71 -0
- html_css_to_image-0.2.0/src/html_css_to_image/_url_builder.py +269 -0
- html_css_to_image-0.2.0/src/html_css_to_image/_version.py +8 -0
- html_css_to_image-0.2.0/src/html_css_to_image/client.py +317 -0
- html_css_to_image-0.2.0/src/html_css_to_image/exceptions.py +21 -0
- html_css_to_image-0.2.0/src/html_css_to_image/models.py +600 -0
- html_css_to_image-0.2.0/src/html_css_to_image/py.typed +1 -0
- html_css_to_image-0.2.0/tests/test_client.py +589 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
branches: [main]
|
|
6
|
+
push:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
|
|
15
|
+
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v6
|
|
18
|
+
|
|
19
|
+
- uses: actions/setup-python@v6
|
|
20
|
+
with:
|
|
21
|
+
python-version: ${{ matrix.python-version }}
|
|
22
|
+
cache: pip
|
|
23
|
+
|
|
24
|
+
- run: python -m pip install --upgrade pip
|
|
25
|
+
- run: python -m pip install -e ".[dev]"
|
|
26
|
+
- run: ruff check .
|
|
27
|
+
- run: mypy
|
|
28
|
+
- run: python -m unittest discover -s tests
|
|
29
|
+
- run: python -m build
|
|
30
|
+
|
|
31
|
+
minimum-httpx:
|
|
32
|
+
runs-on: ubuntu-latest
|
|
33
|
+
steps:
|
|
34
|
+
- uses: actions/checkout@v6
|
|
35
|
+
|
|
36
|
+
- uses: actions/setup-python@v6
|
|
37
|
+
with:
|
|
38
|
+
python-version: "3.10"
|
|
39
|
+
cache: pip
|
|
40
|
+
|
|
41
|
+
- run: python -m pip install --upgrade pip
|
|
42
|
+
- run: python -m pip install -e ".[dev]" "httpx==0.27.0"
|
|
43
|
+
- run: python -m unittest discover -s tests
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# After CI succeeds for a push to main, publishes the declared package version
|
|
2
|
+
# when it does not yet exist on PyPI. A successful publication creates the
|
|
3
|
+
# matching GitHub Release and attaches the wheel and source distribution.
|
|
4
|
+
#
|
|
5
|
+
# PyPI Trusted Publishing is configured for:
|
|
6
|
+
# Owner: htmlcsstoimage
|
|
7
|
+
# Repository: python-client
|
|
8
|
+
# Workflow: publish.yml
|
|
9
|
+
# Environment: blank
|
|
10
|
+
#
|
|
11
|
+
# No PyPI token or GitHub Actions secret is required.
|
|
12
|
+
|
|
13
|
+
name: Publish to PyPI
|
|
14
|
+
|
|
15
|
+
on:
|
|
16
|
+
workflow_run:
|
|
17
|
+
workflows:
|
|
18
|
+
- CI
|
|
19
|
+
types:
|
|
20
|
+
- completed
|
|
21
|
+
branches:
|
|
22
|
+
- main
|
|
23
|
+
|
|
24
|
+
concurrency:
|
|
25
|
+
group: publish
|
|
26
|
+
cancel-in-progress: false
|
|
27
|
+
|
|
28
|
+
jobs:
|
|
29
|
+
version:
|
|
30
|
+
name: Check package version
|
|
31
|
+
if: >-
|
|
32
|
+
github.event.workflow_run.conclusion == 'success' &&
|
|
33
|
+
github.event.workflow_run.event == 'push'
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
permissions:
|
|
36
|
+
contents: read
|
|
37
|
+
outputs:
|
|
38
|
+
publish: ${{ steps.version.outputs.publish }}
|
|
39
|
+
package_name: ${{ steps.version.outputs.package_name }}
|
|
40
|
+
package_version: ${{ steps.version.outputs.package_version }}
|
|
41
|
+
tag: ${{ steps.version.outputs.tag }}
|
|
42
|
+
|
|
43
|
+
steps:
|
|
44
|
+
- uses: actions/checkout@v6
|
|
45
|
+
with:
|
|
46
|
+
ref: ${{ github.event.workflow_run.head_sha }}
|
|
47
|
+
|
|
48
|
+
- uses: actions/setup-python@v6
|
|
49
|
+
with:
|
|
50
|
+
python-version: "3.14"
|
|
51
|
+
|
|
52
|
+
- name: Check PyPI for the declared version
|
|
53
|
+
id: version
|
|
54
|
+
shell: bash
|
|
55
|
+
run: |
|
|
56
|
+
set -euo pipefail
|
|
57
|
+
|
|
58
|
+
package_name="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["name"])')"
|
|
59
|
+
package_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
|
|
60
|
+
tag="v${package_version}"
|
|
61
|
+
|
|
62
|
+
echo "package_name=${package_name}" >> "$GITHUB_OUTPUT"
|
|
63
|
+
echo "package_version=${package_version}" >> "$GITHUB_OUTPUT"
|
|
64
|
+
echo "tag=${tag}" >> "$GITHUB_OUTPUT"
|
|
65
|
+
|
|
66
|
+
status_code="$(curl --silent --show-error --output /dev/null --write-out "%{http_code}" "https://pypi.org/pypi/${package_name}/${package_version}/json")"
|
|
67
|
+
case "$status_code" in
|
|
68
|
+
200)
|
|
69
|
+
echo "publish=false" >> "$GITHUB_OUTPUT"
|
|
70
|
+
echo "${package_name} ${package_version} already exists on PyPI."
|
|
71
|
+
;;
|
|
72
|
+
404)
|
|
73
|
+
echo "publish=true" >> "$GITHUB_OUTPUT"
|
|
74
|
+
echo "${package_name} ${package_version} is new and will be published."
|
|
75
|
+
;;
|
|
76
|
+
*)
|
|
77
|
+
echo "PyPI returned unexpected HTTP status ${status_code}." >&2
|
|
78
|
+
exit 1
|
|
79
|
+
;;
|
|
80
|
+
esac
|
|
81
|
+
|
|
82
|
+
build:
|
|
83
|
+
name: Build distributions
|
|
84
|
+
needs: version
|
|
85
|
+
if: needs.version.outputs.publish == 'true'
|
|
86
|
+
runs-on: ubuntu-latest
|
|
87
|
+
permissions:
|
|
88
|
+
contents: read
|
|
89
|
+
|
|
90
|
+
steps:
|
|
91
|
+
- uses: actions/checkout@v6
|
|
92
|
+
with:
|
|
93
|
+
ref: ${{ github.event.workflow_run.head_sha }}
|
|
94
|
+
|
|
95
|
+
- uses: actions/setup-python@v6
|
|
96
|
+
with:
|
|
97
|
+
python-version: "3.14"
|
|
98
|
+
|
|
99
|
+
- run: python -m pip install --upgrade pip build
|
|
100
|
+
- run: python -m build
|
|
101
|
+
|
|
102
|
+
- uses: actions/upload-artifact@v4
|
|
103
|
+
with:
|
|
104
|
+
name: python-package-${{ needs.version.outputs.package_version }}
|
|
105
|
+
path: dist/
|
|
106
|
+
if-no-files-found: error
|
|
107
|
+
|
|
108
|
+
publish:
|
|
109
|
+
name: Publish distributions
|
|
110
|
+
needs: [version, build]
|
|
111
|
+
if: needs.version.outputs.publish == 'true'
|
|
112
|
+
runs-on: ubuntu-latest
|
|
113
|
+
permissions:
|
|
114
|
+
contents: read
|
|
115
|
+
id-token: write
|
|
116
|
+
|
|
117
|
+
steps:
|
|
118
|
+
- uses: actions/download-artifact@v4
|
|
119
|
+
with:
|
|
120
|
+
name: python-package-${{ needs.version.outputs.package_version }}
|
|
121
|
+
path: dist/
|
|
122
|
+
|
|
123
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
124
|
+
|
|
125
|
+
release:
|
|
126
|
+
name: Create GitHub Release
|
|
127
|
+
needs: [version, build, publish]
|
|
128
|
+
if: needs.version.outputs.publish == 'true'
|
|
129
|
+
runs-on: ubuntu-latest
|
|
130
|
+
permissions:
|
|
131
|
+
contents: write
|
|
132
|
+
|
|
133
|
+
steps:
|
|
134
|
+
- uses: actions/download-artifact@v4
|
|
135
|
+
with:
|
|
136
|
+
name: python-package-${{ needs.version.outputs.package_version }}
|
|
137
|
+
path: dist/
|
|
138
|
+
|
|
139
|
+
- uses: softprops/action-gh-release@v3
|
|
140
|
+
with:
|
|
141
|
+
tag_name: ${{ needs.version.outputs.tag }}
|
|
142
|
+
name: ${{ needs.version.outputs.tag }}
|
|
143
|
+
target_commitish: ${{ github.event.workflow_run.head_sha }}
|
|
144
|
+
files: dist/*
|
|
145
|
+
generate_release_notes: true
|
|
146
|
+
draft: false
|
|
147
|
+
prerelease: false
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HTML/CSS to Image API
|
|
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,300 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: html-css-to-image
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Official Python client for the HTML/CSS to Image API
|
|
5
|
+
Project-URL: Homepage, https://htmlcsstoimage.com
|
|
6
|
+
Project-URL: Documentation, https://docs.htmlcsstoimage.com
|
|
7
|
+
Project-URL: Repository, https://github.com/htmlcsstoimage/python-client
|
|
8
|
+
Project-URL: Issues, https://github.com/htmlcsstoimage/python-client/issues
|
|
9
|
+
Author-email: HTML/CSS to Image API <support@htmlcsstoimage.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: hcti,html-to-image,htmlcsstoimage,screenshot
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Requires-Dist: httpx<1,>=0.27
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
27
|
+
Requires-Dist: mypy>=1.16; extra == 'dev'
|
|
28
|
+
Requires-Dist: ruff>=0.12; extra == 'dev'
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# HTML/CSS to Image Python Client
|
|
32
|
+
|
|
33
|
+
The official Python client for the [HTML/CSS to Image API](https://htmlcsstoimage.com). It provides typed request and response models, signed URL helpers, and an injectable HTTPX transport.
|
|
34
|
+
|
|
35
|
+
This README documents how the client behaves. The central [API documentation](https://docs.htmlcsstoimage.com) is the source of truth for rendering features, parameter meanings, supported values, plan availability, and API limits. See the [parameter reference](https://docs.htmlcsstoimage.com/parameters/) when configuring a request.
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install html-css-to-image
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Python 3.10 or newer is required.
|
|
44
|
+
|
|
45
|
+
## Quick start
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from html_css_to_image import (
|
|
49
|
+
CreateHtmlCssImageRequest,
|
|
50
|
+
HtmlCssToImageClient,
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
with HtmlCssToImageClient("your-api-id", "your-api-key") as client:
|
|
54
|
+
result = client.create_image(
|
|
55
|
+
CreateHtmlCssImageRequest(
|
|
56
|
+
html="<h1>Hello, world!</h1>",
|
|
57
|
+
css="h1 { color: royalblue; }",
|
|
58
|
+
)
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
if result.success:
|
|
62
|
+
print(result.id, result.url)
|
|
63
|
+
else:
|
|
64
|
+
print(result.status_code, result.error, result.message)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Credentials are available in the [HCTI dashboard](https://htmlcsstoimage.com/dashboard). Keep the API key on a trusted server; never embed it in browser, desktop, or mobile application code.
|
|
68
|
+
|
|
69
|
+
### Environment credentials
|
|
70
|
+
|
|
71
|
+
Set `HCTI_API_ID` and `HCTI_API_KEY`, then use:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
client = HtmlCssToImageClient.from_env()
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`from_env()` raises `ValueError` when either variable is missing.
|
|
78
|
+
|
|
79
|
+
## Requests and responses
|
|
80
|
+
|
|
81
|
+
Request fields use the API's `snake_case` names and are available as typed keyword arguments. `None` fields are omitted from JSON payloads; an explicit `False` is preserved for normal POST requests. Collection fields such as `google_fonts` and `additional_header_origins` accept lists or tuples of strings and reject a plain string rather than treating it as a sequence of characters.
|
|
82
|
+
|
|
83
|
+
| Request class | Use |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `CreateHtmlCssImageRequest` | Create an image from HTML and CSS. |
|
|
86
|
+
| `CreateUrlImageRequest` | Capture a URL. |
|
|
87
|
+
| `CreateTemplatedImageRequest` | Render a saved template with values. |
|
|
88
|
+
|
|
89
|
+
All supported fields are documented by type hints and class docstrings. Their API behavior is documented in the [parameter reference](https://docs.htmlcsstoimage.com/parameters/), [URL screenshot guide](https://docs.htmlcsstoimage.com/getting-started/url-to-image/), and [template guide](https://docs.htmlcsstoimage.com/getting-started/templates/).
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from html_css_to_image import (
|
|
93
|
+
CreateTemplatedImageRequest,
|
|
94
|
+
CreateUrlImageRequest,
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
url_result = client.create_image(
|
|
98
|
+
CreateUrlImageRequest(
|
|
99
|
+
url="https://example.com",
|
|
100
|
+
viewport_width=1200,
|
|
101
|
+
viewport_height=630,
|
|
102
|
+
transparent_background=True,
|
|
103
|
+
format="webp",
|
|
104
|
+
)
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
template_result = client.create_image(
|
|
108
|
+
CreateTemplatedImageRequest(
|
|
109
|
+
template_id="your-template-id",
|
|
110
|
+
template_version=3,
|
|
111
|
+
template_values={"title": "Hello from Python"},
|
|
112
|
+
)
|
|
113
|
+
)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`create_image()` returns either `CreateImageSuccessResponse` or `ApiErrorResponse`, discriminated by `result.success`. API errors include the HTTP `status_code`. HTTP transport failures are raised by HTTPX rather than converted into API responses, while malformed successful responses raise `UnexpectedResponseError` instead of producing an incomplete success object.
|
|
117
|
+
|
|
118
|
+
### Batch requests
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
result = client.create_image_batch(
|
|
122
|
+
variations=[
|
|
123
|
+
CreateHtmlCssImageRequest(css="h1 { color: crimson; }"),
|
|
124
|
+
CreateHtmlCssImageRequest(css="h1 { color: royalblue; }"),
|
|
125
|
+
],
|
|
126
|
+
default_options=CreateHtmlCssImageRequest(
|
|
127
|
+
html="<h1>Shared HTML</h1>",
|
|
128
|
+
viewport_width=600,
|
|
129
|
+
viewport_height=315,
|
|
130
|
+
),
|
|
131
|
+
)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Only HTML/CSS and URL requests can be batched. Empty `html` or `url` values in variations are omitted so they can inherit from `default_options`. An empty variation list returns a successful empty result without sending an HTTP request. Options unsupported by the batch API, such as `dedupe_duration_s`, are not serialized. See the [batch API documentation](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#batch-image-creation).
|
|
135
|
+
|
|
136
|
+
## Signed URLs
|
|
137
|
+
|
|
138
|
+
The signed URL helpers perform no network request. They create the exact query string, sign it with HMAC-SHA256 using the API key, and return a URL that can be shared without exposing that key.
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
template_url = client.generate_templated_image_url_from_values(
|
|
142
|
+
"your-template-id",
|
|
143
|
+
{"title": "Rendered on demand"},
|
|
144
|
+
template_version=2,
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
render_url = client.generate_create_and_render_url(
|
|
148
|
+
CreateUrlImageRequest(
|
|
149
|
+
url="https://example.com/card/42",
|
|
150
|
+
viewport_width=1200,
|
|
151
|
+
viewport_height=630,
|
|
152
|
+
)
|
|
153
|
+
)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Use `generate_templated_image_url()` with a complete `CreateTemplatedImageRequest`, or `generate_templated_image_url_from_values()` when starting with separate values. Both methods accept `render_options`.
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from html_css_to_image import CreateTemplatedImageRequest, RenderImageOptions
|
|
160
|
+
|
|
161
|
+
options = RenderImageOptions(format="webp", width=1200, height=630)
|
|
162
|
+
|
|
163
|
+
template_url = client.generate_templated_image_url(
|
|
164
|
+
CreateTemplatedImageRequest(
|
|
165
|
+
template_id="your-template-id",
|
|
166
|
+
template_values={"title": "Rendered on demand"},
|
|
167
|
+
),
|
|
168
|
+
render_options=options,
|
|
169
|
+
)
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Client behavior worth knowing:
|
|
173
|
+
|
|
174
|
+
- Render options are added before signing, so the signature covers the final query string.
|
|
175
|
+
- Template fields that collide with render-option query names are assigned the API's reserved `__ro_` names automatically.
|
|
176
|
+
- PDF layout options and deduplication options are omitted from create-and-render URLs because that endpoint does not support them.
|
|
177
|
+
- Custom URL headers become visible query parameters in a signed URL. Do not put secrets in them.
|
|
178
|
+
|
|
179
|
+
See the [signed URL documentation](https://docs.htmlcsstoimage.com/getting-started/create-and-render/) for endpoint behavior and security considerations.
|
|
180
|
+
|
|
181
|
+
## Image URLs and render options
|
|
182
|
+
|
|
183
|
+
`format` accepts `"png"`, `"jpg"`, `"webp"`, or `"pdf"` on creation requests and render options. `image_url()` builds a URL for an existing image without making a request:
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
url = client.image_url(
|
|
187
|
+
"image-id",
|
|
188
|
+
RenderImageOptions(format="jpg", dpi=96, width=1200),
|
|
189
|
+
)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Cropping uses immutable value objects and explicit factory methods:
|
|
193
|
+
|
|
194
|
+
```python
|
|
195
|
+
from html_css_to_image import (
|
|
196
|
+
RenderImageCrop,
|
|
197
|
+
RenderImageCropPosition,
|
|
198
|
+
RenderImageCropSpan,
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
crop = RenderImageCrop.rectangle(
|
|
202
|
+
horizontal=RenderImageCropSpan.between(
|
|
203
|
+
RenderImageCropPosition.percent(10),
|
|
204
|
+
RenderImageCropPosition.percent(90),
|
|
205
|
+
)
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
url = client.image_url("image-id", RenderImageOptions(crop=crop))
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
The crop factories validate their inputs before generating a URL. Refer to the [image URL and cropping documentation](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#cropping-parameters) for transformation semantics and limits.
|
|
212
|
+
|
|
213
|
+
## Deleting images
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
single = client.delete_image("image-id")
|
|
217
|
+
batch = client.delete_image_batch(["image-id-1", "image-id-2"])
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Every successful `2xx` response maps to `DeleteImageSuccessResponse`. API errors use `ApiErrorResponse`, while network failures remain HTTPX exceptions.
|
|
221
|
+
|
|
222
|
+
## HTTP configuration
|
|
223
|
+
|
|
224
|
+
The default transport is a persistent `httpx.Client` with a 30-second timeout and no automatic retries. Inject a client to configure timeouts, retries, proxies, certificates, connection limits, or test transports:
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
import httpx
|
|
228
|
+
|
|
229
|
+
http_client = httpx.Client(
|
|
230
|
+
transport=httpx.HTTPTransport(retries=2),
|
|
231
|
+
timeout=httpx.Timeout(90),
|
|
232
|
+
)
|
|
233
|
+
|
|
234
|
+
client = HtmlCssToImageClient(
|
|
235
|
+
"your-api-id",
|
|
236
|
+
"your-api-key",
|
|
237
|
+
http_client=http_client,
|
|
238
|
+
)
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
An injected HTTP client remains caller-owned and is never closed or reconfigured by this package. Every API request includes `HCTIPython/<version>` as its `User-Agent`, including requests sent through an injected client. When the SDK creates the HTTP client, call `close()` or use `HtmlCssToImageClient` as a context manager.
|
|
242
|
+
|
|
243
|
+
Retry policy intentionally belongs to the application. HTTPX transport retries cover connection failures; status-code retries and backoff can be implemented around the injected transport or client call.
|
|
244
|
+
|
|
245
|
+
## Error handling
|
|
246
|
+
|
|
247
|
+
```python
|
|
248
|
+
import httpx
|
|
249
|
+
|
|
250
|
+
from html_css_to_image import UnexpectedResponseError
|
|
251
|
+
|
|
252
|
+
try:
|
|
253
|
+
result = client.create_image(request)
|
|
254
|
+
except httpx.TimeoutException:
|
|
255
|
+
# Apply application-specific policy.
|
|
256
|
+
...
|
|
257
|
+
except httpx.NetworkError:
|
|
258
|
+
...
|
|
259
|
+
except UnexpectedResponseError as error:
|
|
260
|
+
# A 2xx response did not match the documented API shape.
|
|
261
|
+
print(error.status_code, error)
|
|
262
|
+
else:
|
|
263
|
+
if not result.success:
|
|
264
|
+
print(result.status_code, result.error, result.message)
|
|
265
|
+
for error in result.validation_errors or ():
|
|
266
|
+
print(error.path, error.message)
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
## Client API
|
|
270
|
+
|
|
271
|
+
| Method | Returns | Interaction |
|
|
272
|
+
| --- | --- | --- |
|
|
273
|
+
| `from_env(...)` | `HtmlCssToImageClient` | Reads credentials from the environment. |
|
|
274
|
+
| `create_image(request)` | `CreateImageResponse` | Sends `POST /v1/image`. |
|
|
275
|
+
| `create_image_batch(variations, default_options=None)` | `CreateImageBatchResponse` | Sends `POST /v1/image/batch`, unless the list is empty. |
|
|
276
|
+
| `delete_image(image_id)` | `DeleteImageResponse` | Sends `DELETE /v1/image/{id}`. |
|
|
277
|
+
| `delete_image_batch(image_ids)` | `DeleteImageResponse` | Sends `DELETE /v1/image/batch`. |
|
|
278
|
+
| `image_url(image_id, render_options=None)` | `str` | Builds an existing-image URL locally. |
|
|
279
|
+
| `generate_templated_image_url(request, render_options=None)` | `str` | Builds and signs a template URL from a request locally. |
|
|
280
|
+
| `generate_templated_image_url_from_values(...)` | `str` | Builds and signs a template URL from separate values locally. |
|
|
281
|
+
| `generate_create_and_render_url(...)` | `str` | Builds and signs a URL screenshot locally. |
|
|
282
|
+
| `close()` | `None` | Closes only an SDK-owned HTTP client. |
|
|
283
|
+
|
|
284
|
+
The package exports typed request, response, PDF, and render/crop models from `html_css_to_image`. Public classes, constructor parameters, attributes, and methods include docstrings for IDE help and generated API documentation.
|
|
285
|
+
|
|
286
|
+
## Development
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
python -m venv .venv
|
|
290
|
+
source .venv/bin/activate
|
|
291
|
+
pip install -e ".[dev]"
|
|
292
|
+
ruff check .
|
|
293
|
+
mypy
|
|
294
|
+
python -m unittest discover -s tests
|
|
295
|
+
python -m build
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## License
|
|
299
|
+
|
|
300
|
+
MIT
|