readwebform 0.4.0__py3-none-any.whl
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.
- readwebform/__init__.py +63 -0
- readwebform/__main__.py +10 -0
- readwebform/api.py +335 -0
- readwebform/browser.py +115 -0
- readwebform/cli.py +267 -0
- readwebform/core.py +241 -0
- readwebform/forms.py +408 -0
- readwebform/multipart.py +399 -0
- readwebform/output.py +171 -0
- readwebform/parser.py +285 -0
- readwebform/py.typed +0 -0
- readwebform/server.py +690 -0
- readwebform-0.4.0.dist-info/METADATA +710 -0
- readwebform-0.4.0.dist-info/RECORD +18 -0
- readwebform-0.4.0.dist-info/WHEEL +5 -0
- readwebform-0.4.0.dist-info/entry_points.txt +2 -0
- readwebform-0.4.0.dist-info/licenses/LICENSE +21 -0
- readwebform-0.4.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,710 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: readwebform
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: A command-line utility for gathering structured user input through temporary web forms
|
|
5
|
+
Author-email: Vlad Lasky <github@vladlasky.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/vlasky/readwebform
|
|
8
|
+
Project-URL: Repository, https://github.com/vlasky/readwebform
|
|
9
|
+
Project-URL: Issues, https://github.com/vlasky/readwebform/issues
|
|
10
|
+
Keywords: cli,form,web,input,automation,scripting
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: System Administrators
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
24
|
+
Classifier: Topic :: System :: Systems Administration
|
|
25
|
+
Classifier: Topic :: Utilities
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Provides-Extra: test
|
|
30
|
+
Requires-Dist: pytest; extra == "test"
|
|
31
|
+
Requires-Dist: cryptography>=41.0.0; extra == "test"
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: pytest; extra == "dev"
|
|
34
|
+
Requires-Dist: cryptography>=41.0.0; extra == "dev"
|
|
35
|
+
Requires-Dist: ruff; extra == "dev"
|
|
36
|
+
Requires-Dist: pyright; extra == "dev"
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# readwebform
|
|
40
|
+
|
|
41
|
+

|
|
42
|
+

|
|
43
|
+

|
|
44
|
+
|
|
45
|
+
**Collect user input through a web form instead of the terminal.**
|
|
46
|
+
|
|
47
|
+
Interactive shell scripts are clunky. Prompting users with `read` or `readline` means no validation, no structure, and an ugly experience. What if you could pop open a real form in the browser instead?
|
|
48
|
+
|
|
49
|
+
`readwebform` launches a temporary local web server, serves a one-time form, waits for submission, then returns the data as JSON. The server shuts down automatically. Zero runtime dependencies, one command.
|
|
50
|
+
|
|
51
|
+

|
|
52
|
+
|
|
53
|
+
## Use Cases
|
|
54
|
+
|
|
55
|
+
- **Replace clunky terminal prompts** - Get structured input with validation, dropdowns, checkboxes, and file uploads instead of endless `read -p` calls
|
|
56
|
+
- **Collect sensitive input securely** - Passwords and API keys without terminal echo or shell history
|
|
57
|
+
- **Gather data from others on your network** - Send the temporary URL to a colleague; HTTPS supported for encryption
|
|
58
|
+
- **Human-in-the-loop for AI agents** - Provide a clean input mechanism for tools like Claude Code that need to pause and ask for user input
|
|
59
|
+
|
|
60
|
+
## Quick Start
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
readwebform --field name:text:Name:required --field email:email:Email:required
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Your browser opens the form. The command **blocks** until the form is submitted or the timeout expires, then outputs:
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"success": true,
|
|
71
|
+
"fields": {
|
|
72
|
+
"name": "Joe Smith",
|
|
73
|
+
"email": "jsmith@example.com"
|
|
74
|
+
},
|
|
75
|
+
"files": {},
|
|
76
|
+
"error": null
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
> **Tip:** Run `readwebform --help` to see all available options. Note that running `readwebform` with no arguments will wait for HTML input on stdin.
|
|
81
|
+
|
|
82
|
+
The browser is not launched, and only the URL is printed, when no desktop is detected (CI, an SSH session, no `DISPLAY`), when `--host` is not a loopback address (the URL is for someone else), or when `--url-file` is used (you are handling the URL yourself). `--no-launch-browser` always suppresses it, `READWEBFORM_NO_BROWSER=1` disables the automatic launch, and `--launch-browser` always forces it. Launch reporting is best effort: a browser that fails after it has been handed the URL is not detected. The Python API never opens a browser unless you pass `launch_browser=True`.
|
|
83
|
+
|
|
84
|
+
## Table of Contents
|
|
85
|
+
|
|
86
|
+
- [Features](#features)
|
|
87
|
+
- [Requirements](#requirements)
|
|
88
|
+
- [Installation](#installation)
|
|
89
|
+
- [Usage](#usage)
|
|
90
|
+
- [Input Modes](#input-modes)
|
|
91
|
+
- [Key Options](#key-options)
|
|
92
|
+
- [Declarative Field Syntax](#declarative-field-syntax)
|
|
93
|
+
- [Output Formats](#output-formats)
|
|
94
|
+
- [Exit Codes](#exit-codes)
|
|
95
|
+
- [HTTPS Support](#https-support)
|
|
96
|
+
- [Security](#security)
|
|
97
|
+
- [Python API](#python-api)
|
|
98
|
+
- [Examples](#examples)
|
|
99
|
+
- [Development](#development)
|
|
100
|
+
- [Status](#status)
|
|
101
|
+
- [License](#license)
|
|
102
|
+
- [Contributing](#contributing)
|
|
103
|
+
- [Author](#author)
|
|
104
|
+
|
|
105
|
+
## Features
|
|
106
|
+
|
|
107
|
+
- **Ephemeral & Secure** - One-shot browser-based prompt with CSRF protection
|
|
108
|
+
- **Multiple Input Modes** - Inline HTML, HTML file, stdin, or declarative fields
|
|
109
|
+
- **Cross-Platform** - Works on Linux, macOS, and Windows
|
|
110
|
+
- **Zero Runtime Dependencies** - Uses only Python 3.9+ standard library
|
|
111
|
+
- **Flexible Output** - JSON or sanitized environment variables
|
|
112
|
+
- **File Upload Support** - With configurable size limits
|
|
113
|
+
- **Timeout Management** - Configurable timeouts with optional reset on validation errors
|
|
114
|
+
- **HTTPS Support** - Optional TLS encryption for remote access scenarios
|
|
115
|
+
|
|
116
|
+
## Requirements
|
|
117
|
+
|
|
118
|
+
- Python 3.9 or higher
|
|
119
|
+
- No external dependencies required at runtime
|
|
120
|
+
|
|
121
|
+
## Installation
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
# Run it without installing anything (uv)
|
|
125
|
+
uvx readwebform --field name:text:Name:required
|
|
126
|
+
|
|
127
|
+
# Or install the command
|
|
128
|
+
pipx install readwebform # isolated, recommended
|
|
129
|
+
pip install readwebform # into the current environment
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
For development, clone the repository and run `pip install -e ".[dev]"`.
|
|
133
|
+
|
|
134
|
+
> **Tip:** On Linux/macOS, pip may install the `readwebform` command to `~/.local/bin`. Ensure this directory is in your `PATH`.
|
|
135
|
+
|
|
136
|
+
## Usage
|
|
137
|
+
|
|
138
|
+
```
|
|
139
|
+
readwebform [options]
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The command blocks until the form is submitted or the timeout expires. Only one submission is accepted per invocation.
|
|
143
|
+
|
|
144
|
+
### Input Modes
|
|
145
|
+
|
|
146
|
+
**Inline HTML:**
|
|
147
|
+
```bash
|
|
148
|
+
readwebform --html '<form><input name="name" required><input type="submit"></form>'
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
**Declarative fields:**
|
|
152
|
+
```bash
|
|
153
|
+
readwebform \
|
|
154
|
+
--field name:text:Name:required \
|
|
155
|
+
--field email:email:Email:required \
|
|
156
|
+
--field comments:textarea:Comments:rows=4
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**HTML file:**
|
|
160
|
+
```bash
|
|
161
|
+
readwebform --htmlfile ./form.html
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**From stdin:**
|
|
165
|
+
```bash
|
|
166
|
+
cat form.html | readwebform
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Key Options
|
|
170
|
+
|
|
171
|
+
| Option | Description |
|
|
172
|
+
|--------|-------------|
|
|
173
|
+
| `--html "<string>"` | Inline HTML fragment or document containing one `<form>` element |
|
|
174
|
+
| `--htmlfile <path>` | Path to an HTML file containing a form |
|
|
175
|
+
| `--field <spec>` | Declaratively define form fields (repeatable) |
|
|
176
|
+
| `--title <string>` | Page title, shown as a heading above the form and in the browser tab (an existing `<title>` in a complete document is kept) |
|
|
177
|
+
| `--text <string>` | Instructional text shown above the form |
|
|
178
|
+
| `--host <ip>` | IPv4 or IPv6 address to bind to (default: `127.0.0.1`). With `0.0.0.0` or `::` the printed URL uses a best-effort guess of your machine's network address |
|
|
179
|
+
| `--url-host <host>` | Host name or address to put in the printed URL, for when the guess is wrong (VPNs, several interfaces) or you want a DNS name |
|
|
180
|
+
| `--port <int>` | TCP port (default: random available port) |
|
|
181
|
+
| `--cert <path>` | SSL certificate file (PEM) for HTTPS |
|
|
182
|
+
| `--key <path>` | SSL private key file (PEM) for HTTPS |
|
|
183
|
+
| `--max-file-size <limit>` | Maximum individual upload size (e.g., `5M`, `200K`) |
|
|
184
|
+
| `--max-total-size <limit>` | Maximum total request size (e.g., `20M`, `1G`; default `20M`) |
|
|
185
|
+
| `--upload-dir <path>` | Directory for uploaded files (default: a new temporary directory) |
|
|
186
|
+
| `--timeout <seconds>` | Max time to wait for submission, fractional allowed (default: `300`) |
|
|
187
|
+
| `--reset-timeout-on-error <bool>` | Reset timeout on recoverable errors (default: true) |
|
|
188
|
+
| `--json` | Output result as JSON (default; accepted for compatibility) |
|
|
189
|
+
| `--envfile <path>` | Write sanitized `export` statements to a file (mode `0600`) |
|
|
190
|
+
| `--print-env` | Print sanitized `export` statements to stdout instead of JSON |
|
|
191
|
+
| `--env-prefix <prefix>` | Prefix for environment variable names (default: `WEBFORM_`) |
|
|
192
|
+
| `--url-file <path>` | Write the form URL to this file |
|
|
193
|
+
| `--launch-browser [path]` | Open the form in a browser even when no desktop is detected, optionally with a specific browser executable |
|
|
194
|
+
| `--no-launch-browser` | Never open a browser; just print the URL. The environment variable `READWEBFORM_NO_BROWSER=1` disables the automatic launch for every run (an explicit `--launch-browser` still opens one) |
|
|
195
|
+
| `--no-submit-button` | Disable automatic submit button in declarative mode |
|
|
196
|
+
| `--no-cancel-button` | Disable cancel button in declarative mode |
|
|
197
|
+
| `--submit-label <text>` | Label for the submit button (default: "Submit") |
|
|
198
|
+
| `--cancel-label <text>` | Label for the cancel button (default: "Cancel") |
|
|
199
|
+
| `--version` | Print the version and exit |
|
|
200
|
+
|
|
201
|
+
### Declarative Field Syntax
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
--field name:type[:label][:options]
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Quote a spec when it contains spaces or shell characters such as `|` and `*`:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
--field "name:text:Full name:required"
|
|
211
|
+
--field "country:select:Country:options=US|UK|CA"
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Labels and option values are always URL-decoded, quoted or not: `+` becomes a space (`Full+Name`), `%2C` a literal comma, `%3A` a literal colon, and a literal plus sign must be written `%2B` (`"lang:text:C%2B%2B"`).
|
|
215
|
+
|
|
216
|
+
**Supported types:** `text`, `email`, `password`, `number`, `date`, `time`, `datetime-local`, `month`, `week`, `url`, `tel`, `search`, `range`, `color`, `hidden`, `textarea`, `select`, `radio`, `checkbox`, `file`
|
|
217
|
+
|
|
218
|
+
**Options** (comma-separated; flags take no value):
|
|
219
|
+
|
|
220
|
+
| Option | Applies to | Meaning |
|
|
221
|
+
|--------|------------|---------|
|
|
222
|
+
| `required`, `readonly`, `disabled`, `autofocus` | most | HTML attributes of the same name |
|
|
223
|
+
| `placeholder=hint` | text-like, textarea | Placeholder text |
|
|
224
|
+
| `value=...` | all except file | Default value: the input text, the selected option(s), the checked radio, or the submitted value of a checkbox |
|
|
225
|
+
| `checked` | checkbox | Tick the box initially |
|
|
226
|
+
| `min=`, `max=`, `step=` | number, range, date/time | Range constraints |
|
|
227
|
+
| `minlength=`, `maxlength=`, `pattern=` | text-like, textarea | Length and regex constraints |
|
|
228
|
+
| `rows=`, `cols=` | textarea | Size |
|
|
229
|
+
| `options=a\|b\|c` | select, radio | Choices, separated by `\|` |
|
|
230
|
+
| `multiple` | select, file, email | Allow several values; for `select`, `value=a\|c` preselects several |
|
|
231
|
+
| `accept=.pdf,.docx` | file | Accepted file types (a literal comma is fine here) |
|
|
232
|
+
|
|
233
|
+
**Examples:**
|
|
234
|
+
```bash
|
|
235
|
+
--field "name:text:Full name:required,placeholder=Your name"
|
|
236
|
+
--field age:number:Age:min=0,max=120
|
|
237
|
+
--field "resume:file:Upload resume:accept=.pdf,.docx"
|
|
238
|
+
--field "country:select:Country:options=US|UK|CA,value=UK,required"
|
|
239
|
+
--field "plan:radio:Plan:options=free|pro,value=free"
|
|
240
|
+
--field "notify:checkbox:Email me updates:checked"
|
|
241
|
+
--field "photos:file:Photos:multiple,accept=image/*"
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
## Output Formats
|
|
245
|
+
|
|
246
|
+
### JSON (Default)
|
|
247
|
+
|
|
248
|
+
The JSON output always includes all four keys for consistent parsing:
|
|
249
|
+
|
|
250
|
+
```json
|
|
251
|
+
{
|
|
252
|
+
"success": true,
|
|
253
|
+
"fields": {
|
|
254
|
+
"name": "Alice",
|
|
255
|
+
"email": "alice@example.com"
|
|
256
|
+
},
|
|
257
|
+
"files": {
|
|
258
|
+
"resume": {
|
|
259
|
+
"filename": "cv.pdf",
|
|
260
|
+
"path": "/tmp/readwebform_b73j3d/cv.pdf",
|
|
261
|
+
"size": 48213,
|
|
262
|
+
"content_type": "application/pdf"
|
|
263
|
+
}
|
|
264
|
+
},
|
|
265
|
+
"error": null
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
A field that is submitted more than once (a checkbox group, a `select` with `multiple`) is a list of strings, and a file input with `multiple` is a list of file objects:
|
|
270
|
+
|
|
271
|
+
```json
|
|
272
|
+
{
|
|
273
|
+
"fields": { "colours": ["red", "blue"] },
|
|
274
|
+
"files": { "photos": [ { "filename": "a.jpg", "path": "..." }, { "filename": "b.jpg", "path": "..." } ] }
|
|
275
|
+
}
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
On timeout:
|
|
279
|
+
```json
|
|
280
|
+
{
|
|
281
|
+
"success": false,
|
|
282
|
+
"fields": {},
|
|
283
|
+
"files": {},
|
|
284
|
+
"error": "timeout"
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
On cancellation (user clicks Cancel button):
|
|
289
|
+
```json
|
|
290
|
+
{
|
|
291
|
+
"success": false,
|
|
292
|
+
"fields": {},
|
|
293
|
+
"files": {},
|
|
294
|
+
"error": "cancelled"
|
|
295
|
+
}
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
> **Note:** Timeout and cancellation are normal outcomes, not exceptions. `success: false` does not necessarily indicate an error condition.
|
|
299
|
+
|
|
300
|
+
### Environment Variables
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
readwebform --print-env --field name:text:Name --field email:email:Email
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Output:
|
|
307
|
+
```bash
|
|
308
|
+
# WARNING: Environment files are for trusted local use only.
|
|
309
|
+
# Do not source envfiles generated from untrusted form data.
|
|
310
|
+
export WEBFORM_NAME=Alice
|
|
311
|
+
export WEBFORM_EMAIL=alice@example.com
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Field names are upper-cased, prefixed with `WEBFORM_` (change it with `--env-prefix`), and any character that is not a letter, digit or underscore becomes an underscore, so `first-name` is `WEBFORM_FIRST_NAME`.
|
|
315
|
+
|
|
316
|
+
A repeated field such as a checkbox group produces the values joined by newlines (written as the literal two characters `\n`), plus a count and indexed variables:
|
|
317
|
+
|
|
318
|
+
```bash
|
|
319
|
+
export WEBFORM_COLOURS='red\nblue'
|
|
320
|
+
export WEBFORM_COLOURS_COUNT=2
|
|
321
|
+
export WEBFORM_COLOURS_1=red
|
|
322
|
+
export WEBFORM_COLOURS_2=blue
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Uploaded files produce `WEBFORM_<NAME>_PATH` and `WEBFORM_<NAME>_FILENAME` (indexed as `_1_PATH`, `_2_PATH`... for a `multiple` file input). Envfiles are created with mode `0600` because they may contain submitted secrets.
|
|
326
|
+
|
|
327
|
+
### File Upload Cleanup
|
|
328
|
+
|
|
329
|
+
Uploaded files are stored in a temporary directory (e.g., `/tmp/readwebform_XXXX/`) created when the first file is saved, or in the directory given with `--upload-dir`. They are **not automatically deleted**. Your script is responsible for cleaning up these files after processing to avoid leaving sensitive data on disk.
|
|
330
|
+
|
|
331
|
+
## Exit Codes
|
|
332
|
+
|
|
333
|
+
| Code | Meaning |
|
|
334
|
+
|------|---------|
|
|
335
|
+
| 0 | Successful submission (valid JSON on stdout) |
|
|
336
|
+
| 1 | Internal error |
|
|
337
|
+
| 2 | Invalid HTML or missing form |
|
|
338
|
+
| 3 | Could not read input file |
|
|
339
|
+
| 5 | Timeout waiting for submission |
|
|
340
|
+
| 7 | User cancelled the form |
|
|
341
|
+
| 8 | Invalid argument |
|
|
342
|
+
| 130 | Interrupted (Ctrl+C) |
|
|
343
|
+
|
|
344
|
+
Codes 4 and 6 are reserved and never returned: a browser that fails to launch only produces a warning (the URL is still printed), and an upload over the size limit is rejected with HTTP 413 so the user can try again.
|
|
345
|
+
|
|
346
|
+
Exit code 0 with default output mode (`--json`) guarantees valid JSON on stdout. Timeout, cancellation and interruption also print the JSON envelope (with `"success": false`) unless `--print-env` is used.
|
|
347
|
+
|
|
348
|
+
## HTTPS Support
|
|
349
|
+
|
|
350
|
+
For remote access scenarios where data needs to be encrypted in transit, `readwebform` supports HTTPS with user-provided certificates.
|
|
351
|
+
|
|
352
|
+
> **Note:** For typical local usage on `127.0.0.1`, HTTP is fine. HTTPS is only needed when serving forms to other machines.
|
|
353
|
+
|
|
354
|
+
### Basic HTTPS Usage
|
|
355
|
+
|
|
356
|
+
```bash
|
|
357
|
+
readwebform --host 0.0.0.0 --port 8443 \
|
|
358
|
+
--cert server.pem --key server-key.pem \
|
|
359
|
+
--field password:password:Password
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
<details>
|
|
363
|
+
<summary><strong>Generating Certificates</strong></summary>
|
|
364
|
+
|
|
365
|
+
**For local development (recommended): [mkcert](https://github.com/FiloSottile/mkcert)**
|
|
366
|
+
|
|
367
|
+
Creates locally-trusted certificates with no browser warnings:
|
|
368
|
+
|
|
369
|
+
```bash
|
|
370
|
+
# One-time setup - installs local CA
|
|
371
|
+
mkcert -install
|
|
372
|
+
|
|
373
|
+
# Generate certificate
|
|
374
|
+
mkcert localhost 127.0.0.1
|
|
375
|
+
|
|
376
|
+
# Use with readwebform
|
|
377
|
+
readwebform --cert localhost+1.pem --key localhost+1-key.pem --port 8443 ...
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
**Quick self-signed certificate: openssl**
|
|
381
|
+
|
|
382
|
+
Browsers will show a security warning you must click through:
|
|
383
|
+
|
|
384
|
+
```bash
|
|
385
|
+
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
|
|
386
|
+
-days 365 -nodes -subj '/CN=localhost'
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
**For production servers: [Let's Encrypt](https://letsencrypt.org/)**
|
|
390
|
+
|
|
391
|
+
Use [Certbot](https://certbot.eff.org/) to obtain free trusted certificates for public domains.
|
|
392
|
+
|
|
393
|
+
</details>
|
|
394
|
+
|
|
395
|
+
### Tips
|
|
396
|
+
|
|
397
|
+
- Use a fixed `--port` (e.g., 8443) with HTTPS so browsers remember the security exception
|
|
398
|
+
- Self-signed certificates require clicking through browser warnings each session
|
|
399
|
+
- For local development, `mkcert` provides the smoothest experience
|
|
400
|
+
|
|
401
|
+
## Security
|
|
402
|
+
|
|
403
|
+
The server automatically shuts down after a single form submission.
|
|
404
|
+
|
|
405
|
+
**Security features:**
|
|
406
|
+
|
|
407
|
+
- Defaults to `127.0.0.1` (localhost only)
|
|
408
|
+
- HTTPS support
|
|
409
|
+
- CSRF token protection for each session, and the form lives at a random URL path
|
|
410
|
+
- Exactly one submission is accepted; any later submission receives HTTP 410 and its files are discarded
|
|
411
|
+
- Every connection is handled on its own thread with a socket timeout, so an idle or half-open connection cannot stall the server
|
|
412
|
+
- Request bodies are capped (`--max-total-size`, default 20 MB) before they are read
|
|
413
|
+
- Uploaded filenames are reduced to a safe basename; files and envfiles are created with mode `0600`
|
|
414
|
+
- User-provided HTML is served as-is; generated forms (`--field`) contain no external resources or scripts
|
|
415
|
+
- Stateless and ephemeral by design
|
|
416
|
+
|
|
417
|
+
## Python API
|
|
418
|
+
|
|
419
|
+
> **Note:** The Python API was added as a convenience for those who prefer to integrate `readwebform` directly into Python scripts. The primary interface is the CLI.
|
|
420
|
+
|
|
421
|
+
You can use `readwebform` as a Python library:
|
|
422
|
+
|
|
423
|
+
### Basic Usage
|
|
424
|
+
|
|
425
|
+
```python
|
|
426
|
+
from readwebform import read_webform
|
|
427
|
+
|
|
428
|
+
# Pass any HTML form - URL printed to stderr
|
|
429
|
+
result = read_webform(
|
|
430
|
+
'<form><input name="email" type="email" required><button>Submit</button></form>'
|
|
431
|
+
)
|
|
432
|
+
|
|
433
|
+
if result.success:
|
|
434
|
+
email = result.fields['email']
|
|
435
|
+
print(f"User entered: {email}")
|
|
436
|
+
elif result.error == 'cancelled':
|
|
437
|
+
print("User cancelled the form")
|
|
438
|
+
else:
|
|
439
|
+
print(f"Form failed: {result.error}") # e.g., 'timeout'
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
**What happens:**
|
|
443
|
+
1. A local web server starts on `http://127.0.0.1:<random-port>`
|
|
444
|
+
2. The URL is printed to stderr (open manually, or use `launch_browser=True`)
|
|
445
|
+
3. The function **blocks** until the user submits the form or timeout expires
|
|
446
|
+
4. Returns a `FormResult` with the submitted data
|
|
447
|
+
|
|
448
|
+
### Declarative Forms
|
|
449
|
+
|
|
450
|
+
```python
|
|
451
|
+
from readwebform import read_webform_fields
|
|
452
|
+
|
|
453
|
+
result = read_webform_fields([
|
|
454
|
+
{'name': 'name', 'type': 'text', 'label': 'Full Name', 'required': True},
|
|
455
|
+
{'name': 'email', 'type': 'email', 'label': 'Email', 'required': True},
|
|
456
|
+
{'name': 'age', 'type': 'number', 'label': 'Age', 'min': 0, 'max': 120}
|
|
457
|
+
], title="User Information", timeout=120, launch_browser=True)
|
|
458
|
+
|
|
459
|
+
if result.success:
|
|
460
|
+
print(f"Name: {result.fields['name']}")
|
|
461
|
+
print(f"Email: {result.fields['email']}")
|
|
462
|
+
print(f"Age: {result.fields['age']}")
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
### File Uploads
|
|
466
|
+
|
|
467
|
+
```python
|
|
468
|
+
from readwebform import read_webform
|
|
469
|
+
import os
|
|
470
|
+
|
|
471
|
+
html = '''
|
|
472
|
+
<form enctype="multipart/form-data">
|
|
473
|
+
<input type="file" name="document" accept=".pdf,.txt" required>
|
|
474
|
+
<button>Upload</button>
|
|
475
|
+
</form>
|
|
476
|
+
'''
|
|
477
|
+
|
|
478
|
+
result = read_webform(html, max_file_size=10*1024*1024) # 10 MB limit
|
|
479
|
+
|
|
480
|
+
if result.success and result.files and 'document' in result.files:
|
|
481
|
+
doc = result.files['document'] # an UploadedFile
|
|
482
|
+
print(f"{doc.filename} ({doc.size} bytes, {doc.content_type}) saved to {doc.path}")
|
|
483
|
+
filepath = doc.path
|
|
484
|
+
|
|
485
|
+
# Process the uploaded file
|
|
486
|
+
with open(filepath, 'rb') as f:
|
|
487
|
+
content = f.read()
|
|
488
|
+
|
|
489
|
+
# IMPORTANT: Clean up uploaded files when done
|
|
490
|
+
os.remove(filepath)
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
### Available Parameters
|
|
494
|
+
|
|
495
|
+
#### `read_webform(html, **kwargs)`
|
|
496
|
+
|
|
497
|
+
| Parameter | Default | Description |
|
|
498
|
+
|-----------|---------|-------------|
|
|
499
|
+
| `html` | (required) | HTML form content (fragment or complete document) |
|
|
500
|
+
| `timeout` | `300` | Maximum seconds to wait for submission |
|
|
501
|
+
| `launch_browser` | `False` | Open the browser. Unlike the CLI, the API never launches one unless asked |
|
|
502
|
+
| `browser_path` | `None` | Path to specific browser executable |
|
|
503
|
+
| `max_file_size` | `None` | Maximum individual file size in bytes |
|
|
504
|
+
| `max_total_size` | `None` | Maximum total upload size in bytes |
|
|
505
|
+
| `reset_timeout_on_error` | `True` | Reset timeout on validation errors |
|
|
506
|
+
| `host` | `'127.0.0.1'` | IPv4 or IPv6 address to bind to |
|
|
507
|
+
| `port` | `None` | Port to bind to (default: auto-select) |
|
|
508
|
+
| `cert_file`, `key_file` | `None` | PEM certificate and key to serve HTTPS |
|
|
509
|
+
| `url_file` | `None` | Write the form URL to this file once listening |
|
|
510
|
+
| `upload_dir` | `None` | Directory for uploads (default: temporary directory created on first upload) |
|
|
511
|
+
|
|
512
|
+
#### `read_webform_fields(fields, title=None, text=None, **kwargs)`
|
|
513
|
+
|
|
514
|
+
| Parameter | Default | Description |
|
|
515
|
+
|-----------|---------|-------------|
|
|
516
|
+
| `fields` | (required) | List of field specifications |
|
|
517
|
+
| `title` | `None` | Page title, shown as a heading above the form |
|
|
518
|
+
| `text` | `None` | Instructional text above form |
|
|
519
|
+
| `add_cancel_button` | `True` | Add a Cancel button |
|
|
520
|
+
| `cancel_label` | `'Cancel'` | Label for the Cancel button |
|
|
521
|
+
| `submit_label` | `'Submit'` | Label for the Submit button |
|
|
522
|
+
|
|
523
|
+
All other parameters same as `read_webform()`.
|
|
524
|
+
|
|
525
|
+
#### Field Specification
|
|
526
|
+
|
|
527
|
+
Each field is a `Field` dataclass (recommended, gives IDE completion) or a dict with the same keys:
|
|
528
|
+
|
|
529
|
+
```python
|
|
530
|
+
from readwebform import Field
|
|
531
|
+
|
|
532
|
+
Field(
|
|
533
|
+
name='field_name', # Required: field name
|
|
534
|
+
type='text', # Required: any type listed under "Declarative Field Syntax"
|
|
535
|
+
label='Display Label', # Optional: label shown to user
|
|
536
|
+
required=True, # Optional: whether field is required
|
|
537
|
+
placeholder='hint', # Optional: placeholder text
|
|
538
|
+
value='default', # Optional: default value (text, selected option(s), checked radio)
|
|
539
|
+
checked=True, # Optional: tick a checkbox initially
|
|
540
|
+
min=0, max=100, step=1, # Optional: for number/range/date fields
|
|
541
|
+
minlength=2, maxlength=40, # Optional: for text-like fields
|
|
542
|
+
pattern=r'[a-z]+', # Optional: regex constraint
|
|
543
|
+
rows=4, cols=50, # Optional: for textarea
|
|
544
|
+
options=['A', 'B'], # Required for select/radio: list of choices
|
|
545
|
+
multiple=True, # Optional: select/file/email accept several values
|
|
546
|
+
accept='.pdf,.txt', # Optional: for file input
|
|
547
|
+
)
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
### Return Value: `FormResult`
|
|
551
|
+
|
|
552
|
+
```python
|
|
553
|
+
class FormResult:
|
|
554
|
+
success: bool # True if form submitted, False if timeout/cancel
|
|
555
|
+
fields: Optional[Dict[str, Union[str, List[str]]]] # Field name -> value; repeated fields are lists (None if not success)
|
|
556
|
+
files: Optional[Dict[str, Union[UploadedFile, List[UploadedFile]]]] # None if no files
|
|
557
|
+
error: Optional[str] # 'timeout', 'cancelled', or other error
|
|
558
|
+
|
|
559
|
+
class UploadedFile:
|
|
560
|
+
filename: str # Name supplied by the browser
|
|
561
|
+
path: str # Where the file was saved
|
|
562
|
+
size: int # Bytes
|
|
563
|
+
content_type: str # MIME type supplied by the browser
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
## Examples
|
|
567
|
+
|
|
568
|
+
### Simple Contact Form
|
|
569
|
+
|
|
570
|
+
```bash
|
|
571
|
+
readwebform \
|
|
572
|
+
--title "Contact Information" \
|
|
573
|
+
--submit-label "Send" \
|
|
574
|
+
--field name:text:Name:required \
|
|
575
|
+
--field email:email:Email:required \
|
|
576
|
+
--field message:textarea:Message:rows=5,required
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
### File Upload with Limits
|
|
580
|
+
|
|
581
|
+
```bash
|
|
582
|
+
readwebform \
|
|
583
|
+
--html '<form enctype="multipart/form-data"><input type="file" name="doc" accept=".pdf"><button>Submit</button></form>' \
|
|
584
|
+
--max-file-size 5M \
|
|
585
|
+
--timeout 600
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
### Output to Environment File
|
|
589
|
+
|
|
590
|
+
```bash
|
|
591
|
+
readwebform --htmlfile form.html --envfile vars.env
|
|
592
|
+
source vars.env
|
|
593
|
+
echo "User entered: $WEBFORM_NAME"
|
|
594
|
+
```
|
|
595
|
+
|
|
596
|
+
### Use in Shell Script
|
|
597
|
+
|
|
598
|
+
```bash
|
|
599
|
+
#!/bin/bash
|
|
600
|
+
# Requires jq for JSON parsing: https://jqlang.github.io/jq/
|
|
601
|
+
result=$(readwebform --field name:text:Name:required --field age:number:Age)
|
|
602
|
+
name=$(echo "$result" | jq -r '.fields.name')
|
|
603
|
+
age=$(echo "$result" | jq -r '.fields.age')
|
|
604
|
+
echo "Hello $name, you are $age years old"
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
### Python: Complete Registration Form
|
|
608
|
+
|
|
609
|
+
```python
|
|
610
|
+
from readwebform import read_webform_fields
|
|
611
|
+
|
|
612
|
+
def get_user_registration():
|
|
613
|
+
"""Collect user registration data interactively."""
|
|
614
|
+
|
|
615
|
+
fields = [
|
|
616
|
+
{'name': 'username', 'type': 'text', 'label': 'Username',
|
|
617
|
+
'required': True, 'placeholder': 'Choose a username'},
|
|
618
|
+
{'name': 'email', 'type': 'email', 'label': 'Email Address',
|
|
619
|
+
'required': True},
|
|
620
|
+
{'name': 'password', 'type': 'password', 'label': 'Password',
|
|
621
|
+
'required': True},
|
|
622
|
+
{'name': 'age', 'type': 'number', 'label': 'Age',
|
|
623
|
+
'min': 13, 'max': 120, 'required': True},
|
|
624
|
+
{'name': 'country', 'type': 'select', 'label': 'Country',
|
|
625
|
+
'options': ['USA', 'UK', 'Canada', 'Other'], 'required': True},
|
|
626
|
+
{'name': 'bio', 'type': 'textarea', 'label': 'Bio',
|
|
627
|
+
'rows': 4, 'placeholder': 'Tell us about yourself'},
|
|
628
|
+
{'name': 'newsletter', 'type': 'checkbox', 'label': 'Subscribe to newsletter'},
|
|
629
|
+
]
|
|
630
|
+
|
|
631
|
+
result = read_webform_fields(
|
|
632
|
+
fields,
|
|
633
|
+
title="User Registration",
|
|
634
|
+
text="Please fill out the form below to register",
|
|
635
|
+
timeout=300
|
|
636
|
+
)
|
|
637
|
+
|
|
638
|
+
if result.success:
|
|
639
|
+
return {
|
|
640
|
+
'username': result.fields['username'],
|
|
641
|
+
'email': result.fields['email'],
|
|
642
|
+
'password': result.fields['password'],
|
|
643
|
+
'age': int(result.fields['age']),
|
|
644
|
+
'country': result.fields['country'],
|
|
645
|
+
'bio': result.fields.get('bio', ''),
|
|
646
|
+
'newsletter': result.fields.get('newsletter') == 'on'
|
|
647
|
+
}
|
|
648
|
+
else:
|
|
649
|
+
raise TimeoutError("User did not complete registration in time")
|
|
650
|
+
|
|
651
|
+
# Usage
|
|
652
|
+
try:
|
|
653
|
+
user_data = get_user_registration()
|
|
654
|
+
print(f"Registered user: {user_data['username']}")
|
|
655
|
+
except TimeoutError as e:
|
|
656
|
+
print(f"Registration failed: {e}")
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
## Development
|
|
660
|
+
|
|
661
|
+
```bash
|
|
662
|
+
# Install in development mode with test and lint dependencies
|
|
663
|
+
pip install -e ".[test,dev]"
|
|
664
|
+
|
|
665
|
+
# Run all tests
|
|
666
|
+
python -m pytest tests/ -v
|
|
667
|
+
|
|
668
|
+
# Lint and type-check
|
|
669
|
+
ruff check src tests
|
|
670
|
+
pyright src
|
|
671
|
+
|
|
672
|
+
# Run only unit tests
|
|
673
|
+
python -m pytest tests/ -v --ignore=tests/test_integration.py
|
|
674
|
+
|
|
675
|
+
# Run only integration tests
|
|
676
|
+
python -m pytest tests/test_integration.py -v
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
### Demo GIF
|
|
680
|
+
|
|
681
|
+
`demo.gif` is generated, not screen-recorded: `demo/record_demo.py` runs a real `readwebform` process, drives Chromium through the form with Playwright, and records both panes in one page. See [demo/README.md](demo/README.md).
|
|
682
|
+
|
|
683
|
+
### Design Document
|
|
684
|
+
|
|
685
|
+
See [SPEC.md](SPEC.md) for the full design specification. This document covers architecture, security model, validation rules, and implementation details. It's intended for contributors and anyone wanting to implement `readwebform` in another programming language.
|
|
686
|
+
|
|
687
|
+
### Test Coverage
|
|
688
|
+
|
|
689
|
+
- **307 tests** across 12 files
|
|
690
|
+
- Unit tests for the multipart parser, HTML rewriting, declarative forms, output formatting, CLI parsing and the Python API
|
|
691
|
+
- Integration tests that run a real server on a random port: submissions, uploads, CSRF, size limits, timeouts, the CLI as a subprocess (exit codes 2, 5 and 130)
|
|
692
|
+
- Hardening regressions: byte-exact uploads, UTF-8 filenames, repeated file fields, negative Content-Length, HTTP 410 on a second submission, listener release, concurrent servers, IPv6, idle HTTP and TLS connections
|
|
693
|
+
- Threading, timeout, HTTPS (ephemeral certificates via `cryptography`, test dependency only) and browser-launch isolation tests
|
|
694
|
+
- CI runs the suite on Python 3.9 to 3.14 on Linux, plus macOS and Windows, and runs `ruff` and `pyright`
|
|
695
|
+
|
|
696
|
+
## Status
|
|
697
|
+
|
|
698
|
+
This is an **initial proof of concept**. The API and CLI interface may change based on user feedback. If you have suggestions or run into issues, please open an issue on GitHub.
|
|
699
|
+
|
|
700
|
+
## License
|
|
701
|
+
|
|
702
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
703
|
+
|
|
704
|
+
## Contributing
|
|
705
|
+
|
|
706
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
707
|
+
|
|
708
|
+
## Author
|
|
709
|
+
|
|
710
|
+
**Vlad Lasky** - [https://github.com/vlasky](https://github.com/vlasky)
|