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.
@@ -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,10 @@
1
+ .DS_Store
2
+ __pycache__/
3
+ *.py[cod]
4
+ .coverage
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .venv/
8
+ build/
9
+ dist/
10
+ *.egg-info/
@@ -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