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.
@@ -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
+ ![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)
42
+ ![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)
43
+ ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
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
+ ![readwebform demo](demo.gif)
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)