readwebform 0.4.0__tar.gz → 0.4.1__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.
Files changed (38) hide show
  1. {readwebform-0.4.0/src/readwebform.egg-info → readwebform-0.4.1}/PKG-INFO +16 -7
  2. {readwebform-0.4.0 → readwebform-0.4.1}/README.md +12 -6
  3. {readwebform-0.4.0 → readwebform-0.4.1}/pyproject.toml +2 -1
  4. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/__init__.py +8 -8
  5. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/cli.py +39 -0
  6. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/core.py +135 -2
  7. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/forms.py +10 -0
  8. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/multipart.py +9 -2
  9. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/server.py +137 -45
  10. {readwebform-0.4.0 → readwebform-0.4.1/src/readwebform.egg-info}/PKG-INFO +16 -7
  11. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform.egg-info/SOURCES.txt +2 -0
  12. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform.egg-info/requires.txt +4 -0
  13. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_browser.py +7 -1
  14. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_https.py +2 -2
  15. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_integration.py +27 -18
  16. readwebform-0.4.1/tests/test_real_browser.py +169 -0
  17. readwebform-0.4.1/tests/test_stress_regressions.py +478 -0
  18. readwebform-0.4.1/tests/test_timeout.py +251 -0
  19. readwebform-0.4.0/tests/test_timeout.py +0 -401
  20. {readwebform-0.4.0 → readwebform-0.4.1}/LICENSE +0 -0
  21. {readwebform-0.4.0 → readwebform-0.4.1}/setup.cfg +0 -0
  22. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/__main__.py +0 -0
  23. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/api.py +0 -0
  24. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/browser.py +0 -0
  25. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/output.py +0 -0
  26. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/parser.py +0 -0
  27. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform/py.typed +0 -0
  28. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform.egg-info/dependency_links.txt +0 -0
  29. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform.egg-info/entry_points.txt +0 -0
  30. {readwebform-0.4.0 → readwebform-0.4.1}/src/readwebform.egg-info/top_level.txt +0 -0
  31. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_api.py +0 -0
  32. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_cli.py +0 -0
  33. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_forms.py +0 -0
  34. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_multipart.py +0 -0
  35. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_output.py +0 -0
  36. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_parser.py +0 -0
  37. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_server_hardening.py +0 -0
  38. {readwebform-0.4.0 → readwebform-0.4.1}/tests/test_threading.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: readwebform
3
- Version: 0.4.0
3
+ Version: 0.4.1
4
4
  Summary: A command-line utility for gathering structured user input through temporary web forms
5
5
  Author-email: Vlad Lasky <github@vladlasky.com>
6
6
  License: MIT
@@ -34,11 +34,14 @@ Requires-Dist: pytest; extra == "dev"
34
34
  Requires-Dist: cryptography>=41.0.0; extra == "dev"
35
35
  Requires-Dist: ruff; extra == "dev"
36
36
  Requires-Dist: pyright; extra == "dev"
37
+ Provides-Extra: e2e
38
+ Requires-Dist: pytest; extra == "e2e"
39
+ Requires-Dist: playwright; extra == "e2e"
37
40
  Dynamic: license-file
38
41
 
39
42
  # readwebform
40
43
 
41
- ![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)
44
+ [![PyPI](https://img.shields.io/pypi/v/readwebform.svg)](https://pypi.org/project/readwebform/)
42
45
  ![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)
43
46
  ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
44
47
 
@@ -333,9 +336,9 @@ Uploaded files are stored in a temporary directory (e.g., `/tmp/readwebform_XXXX
333
336
  | Code | Meaning |
334
337
  |------|---------|
335
338
  | 0 | Successful submission (valid JSON on stdout) |
336
- | 1 | Internal error |
339
+ | 1 | Internal error, or the server could not start (port in use, bad host, invalid certificate) |
337
340
  | 2 | Invalid HTML or missing form |
338
- | 3 | Could not read input file |
341
+ | 3 | A file given on the command line could not be read or written |
339
342
  | 5 | Timeout waiting for submission |
340
343
  | 7 | User cancelled the form |
341
344
  | 8 | Invalid argument |
@@ -507,6 +510,7 @@ if result.success and result.files and 'document' in result.files:
507
510
  | `port` | `None` | Port to bind to (default: auto-select) |
508
511
  | `cert_file`, `key_file` | `None` | PEM certificate and key to serve HTTPS |
509
512
  | `url_file` | `None` | Write the form URL to this file once listening |
513
+ | `url_host` | `None` | Host name or address to put in the URL instead of the bind address |
510
514
  | `upload_dir` | `None` | Directory for uploads (default: temporary directory created on first upload) |
511
515
 
512
516
  #### `read_webform_fields(fields, title=None, text=None, **kwargs)`
@@ -674,6 +678,10 @@ python -m pytest tests/ -v --ignore=tests/test_integration.py
674
678
 
675
679
  # Run only integration tests
676
680
  python -m pytest tests/test_integration.py -v
681
+
682
+ # Real-browser tests (skipped unless Playwright and Chromium are installed)
683
+ pip install -e ".[e2e]" && playwright install chromium
684
+ python -m pytest tests/test_real_browser.py -v
677
685
  ```
678
686
 
679
687
  ### Demo GIF
@@ -686,16 +694,17 @@ See [SPEC.md](SPEC.md) for the full design specification. This document covers a
686
694
 
687
695
  ### Test Coverage
688
696
 
689
- - **307 tests** across 12 files
697
+ - **More than 370 tests** across 14 files
690
698
  - Unit tests for the multipart parser, HTML rewriting, declarative forms, output formatting, CLI parsing and the Python API
691
699
  - 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
700
  - 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
701
  - 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`
702
+ - Real-browser tests: Chromium, driven by Playwright, fills in and submits generated forms (multiple files, UTF-8 filenames, an unselected file input, required-field validation, cancel)
703
+ - CI runs the suite on Python 3.9 to 3.14 on Linux, plus macOS and Windows, runs the real-browser tests on Linux, and runs `ruff` and `pyright`
695
704
 
696
705
  ## Status
697
706
 
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.
707
+ readwebform is in **beta**. It is tested on Linux, macOS and Windows across Python 3.9 to 3.14 and published on PyPI, but until 1.0 the CLI and Python API may still change between minor versions; changes are listed in [CHANGELOG.md](CHANGELOG.md). If you have suggestions or run into issues, please open an issue on GitHub.
699
708
 
700
709
  ## License
701
710
 
@@ -1,6 +1,6 @@
1
1
  # readwebform
2
2
 
3
- ![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)
3
+ [![PyPI](https://img.shields.io/pypi/v/readwebform.svg)](https://pypi.org/project/readwebform/)
4
4
  ![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)
5
5
  ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
6
6
 
@@ -295,9 +295,9 @@ Uploaded files are stored in a temporary directory (e.g., `/tmp/readwebform_XXXX
295
295
  | Code | Meaning |
296
296
  |------|---------|
297
297
  | 0 | Successful submission (valid JSON on stdout) |
298
- | 1 | Internal error |
298
+ | 1 | Internal error, or the server could not start (port in use, bad host, invalid certificate) |
299
299
  | 2 | Invalid HTML or missing form |
300
- | 3 | Could not read input file |
300
+ | 3 | A file given on the command line could not be read or written |
301
301
  | 5 | Timeout waiting for submission |
302
302
  | 7 | User cancelled the form |
303
303
  | 8 | Invalid argument |
@@ -469,6 +469,7 @@ if result.success and result.files and 'document' in result.files:
469
469
  | `port` | `None` | Port to bind to (default: auto-select) |
470
470
  | `cert_file`, `key_file` | `None` | PEM certificate and key to serve HTTPS |
471
471
  | `url_file` | `None` | Write the form URL to this file once listening |
472
+ | `url_host` | `None` | Host name or address to put in the URL instead of the bind address |
472
473
  | `upload_dir` | `None` | Directory for uploads (default: temporary directory created on first upload) |
473
474
 
474
475
  #### `read_webform_fields(fields, title=None, text=None, **kwargs)`
@@ -636,6 +637,10 @@ python -m pytest tests/ -v --ignore=tests/test_integration.py
636
637
 
637
638
  # Run only integration tests
638
639
  python -m pytest tests/test_integration.py -v
640
+
641
+ # Real-browser tests (skipped unless Playwright and Chromium are installed)
642
+ pip install -e ".[e2e]" && playwright install chromium
643
+ python -m pytest tests/test_real_browser.py -v
639
644
  ```
640
645
 
641
646
  ### Demo GIF
@@ -648,16 +653,17 @@ See [SPEC.md](SPEC.md) for the full design specification. This document covers a
648
653
 
649
654
  ### Test Coverage
650
655
 
651
- - **307 tests** across 12 files
656
+ - **More than 370 tests** across 14 files
652
657
  - Unit tests for the multipart parser, HTML rewriting, declarative forms, output formatting, CLI parsing and the Python API
653
658
  - 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)
654
659
  - 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
655
660
  - Threading, timeout, HTTPS (ephemeral certificates via `cryptography`, test dependency only) and browser-launch isolation tests
656
- - CI runs the suite on Python 3.9 to 3.14 on Linux, plus macOS and Windows, and runs `ruff` and `pyright`
661
+ - Real-browser tests: Chromium, driven by Playwright, fills in and submits generated forms (multiple files, UTF-8 filenames, an unselected file input, required-field validation, cancel)
662
+ - CI runs the suite on Python 3.9 to 3.14 on Linux, plus macOS and Windows, runs the real-browser tests on Linux, and runs `ruff` and `pyright`
657
663
 
658
664
  ## Status
659
665
 
660
- 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.
666
+ readwebform is in **beta**. It is tested on Linux, macOS and Windows across Python 3.9 to 3.14 and published on PyPI, but until 1.0 the CLI and Python API may still change between minor versions; changes are listed in [CHANGELOG.md](CHANGELOG.md). If you have suggestions or run into issues, please open an issue on GitHub.
661
667
 
662
668
  ## License
663
669
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "readwebform"
7
- version = "0.4.0"
7
+ version = "0.4.1"
8
8
  description = "A command-line utility for gathering structured user input through temporary web forms"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -34,6 +34,7 @@ classifiers = [
34
34
  [project.optional-dependencies]
35
35
  test = ["pytest", "cryptography>=41.0.0"]
36
36
  dev = ["pytest", "cryptography>=41.0.0", "ruff", "pyright"]
37
+ e2e = ["pytest", "playwright"]
37
38
 
38
39
  [project.urls]
39
40
  Homepage = "https://github.com/vlasky/readwebform"
@@ -33,15 +33,15 @@ Programmatic Usage:
33
33
  ])
34
34
  """
35
35
 
36
+ from importlib.metadata import PackageNotFoundError
37
+ from importlib.metadata import version as _pkg_version
38
+
36
39
  try:
37
- from importlib.metadata import PackageNotFoundError
38
- from importlib.metadata import version as _pkg_version
39
- try:
40
- __version__ = _pkg_version("readwebform")
41
- except PackageNotFoundError:
42
- __version__ = "0.4.0"
43
- except ImportError: # pragma: no cover
44
- __version__ = "0.4.0"
40
+ __version__ = _pkg_version("readwebform")
41
+ except PackageNotFoundError:
42
+ # Running from a source tree that was never installed. pyproject.toml is
43
+ # the single place the version is set, so do not guess one here.
44
+ __version__ = "0+unknown"
45
45
  __author__ = "Vlad Lasky"
46
46
  __email__ = "github@vladlasky.com"
47
47
 
@@ -3,7 +3,9 @@ Command-line interface for readwebform.
3
3
  """
4
4
 
5
5
  import argparse
6
+ import ipaddress
6
7
  import math
8
+ import re
7
9
  import sys
8
10
 
9
11
  from . import __version__
@@ -21,6 +23,27 @@ class _ArgumentParser(argparse.ArgumentParser):
21
23
  self.exit(EXIT_INVALID_ARGUMENT, f'{self.prog}: error: {message}\n')
22
24
 
23
25
 
26
+ def is_valid_url_host(value: str) -> bool:
27
+ """
28
+ True if value can stand as the host in a URL: a host name, an IPv4
29
+ address, or an IPv6 address with or without brackets. A port is not
30
+ allowed; the server's own port is appended.
31
+ """
32
+ if value.startswith('[') and value.endswith(']'):
33
+ value = value[1:-1]
34
+ bracketed = True
35
+ else:
36
+ bracketed = False
37
+ if ':' in value or bracketed:
38
+ try:
39
+ ipaddress.IPv6Address(value.split('%', 1)[0]) # a zone id may follow %
40
+ except ValueError:
41
+ return False
42
+ return re.fullmatch(r'[0-9A-Za-z:.%_-]+', value) is not None
43
+ # Host name or IPv4. Non-ASCII letters are allowed (internationalised names).
44
+ return re.fullmatch(r'[^\s/?#@"<>\\\[\]\x00-\x1f\x7f]+', value) is not None
45
+
46
+
24
47
  class ReadWebFormArgumentParser:
25
48
  """Custom argument parser for readwebform."""
26
49
 
@@ -235,6 +258,22 @@ class ReadWebFormArgumentParser:
235
258
  if args.launch_browser is not None and args.no_launch_browser:
236
259
  self.parser.error('--launch-browser and --no-launch-browser are mutually exclusive')
237
260
 
261
+ # An empty value is almost always an unset shell variable. Several of
262
+ # these would otherwise be silently ignored, and an empty --host
263
+ # binds every interface.
264
+ for option in ('host', 'url_host', 'max_file_size', 'max_total_size'):
265
+ value = getattr(args, option, None)
266
+ if value is not None and not value.strip():
267
+ self.parser.error(f'--{option.replace("_", "-")} must not be empty')
268
+ # Paths are compared exactly: a file may legitimately be named ' '
269
+ for option in ('envfile', 'url_file', 'upload_dir', 'cert', 'key', 'htmlfile'):
270
+ if getattr(args, option, None) == '':
271
+ self.parser.error(f'--{option.replace("_", "-")} must not be empty')
272
+
273
+ if args.url_host is not None and not is_valid_url_host(args.url_host):
274
+ self.parser.error('--url-host must be a host name or an IP address, without a port '
275
+ '(write IPv6 addresses as ::1 or [::1])')
276
+
238
277
  if args.cert and not args.key:
239
278
  self.parser.error('--cert requires --key')
240
279
  if args.key and not args.cert:
@@ -3,6 +3,7 @@ Core orchestration for readwebform: load, validate, serve, output.
3
3
  """
4
4
 
5
5
  import ipaddress
6
+ import os
6
7
  import sys
7
8
  import traceback
8
9
  from typing import Optional
@@ -67,6 +68,12 @@ def run_readwebform(args) -> int:
67
68
  print(f'Error: Invalid size limit: {e}', file=sys.stderr)
68
69
  return EXIT_INVALID_ARGUMENT
69
70
 
71
+ try:
72
+ check_paths(args)
73
+ except InputError as e:
74
+ print(f'Error: {e}', file=sys.stderr)
75
+ return e.exit_code
76
+
70
77
  server = FormServer(
71
78
  html='', # set after CSRF injection
72
79
  host=args.host,
@@ -98,6 +105,15 @@ def run_readwebform(args) -> int:
98
105
  _emit_failure(args, 'interrupted')
99
106
  print('\nInterrupted by user', file=sys.stderr)
100
107
  return EXIT_INTERRUPTED
108
+ except OSError as e:
109
+ # The server could not start (port in use, bad host, bad
110
+ # certificate...). That is the user's environment, not a bug, so
111
+ # no traceback. The server has usually printed the reason.
112
+ if not getattr(e, 'readwebform_reported', False):
113
+ print(f'Error: {e}', file=sys.stderr)
114
+ if getattr(e, 'readwebform_file_error', False):
115
+ return EXIT_READ_ERROR
116
+ return EXIT_INTERNAL_ERROR
101
117
 
102
118
  if cancelled:
103
119
  _emit_failure(args, 'cancelled')
@@ -110,13 +126,25 @@ def run_readwebform(args) -> int:
110
126
  return EXIT_TIMEOUT
111
127
 
112
128
  env_prefix = getattr(args, 'env_prefix', 'WEBFORM_')
129
+ envfile_error = None
113
130
  if args.envfile:
114
- write_env_file(args.envfile, form_data.fields, env_prefix, file_metadata)
131
+ try:
132
+ write_env_file(args.envfile, form_data.fields, env_prefix, file_metadata)
133
+ except OSError as e:
134
+ envfile_error = e
135
+
136
+ # Always print the result, even when the envfile could not be
137
+ # written: the user has already filled in the form.
115
138
  if args.print_env:
116
139
  print(format_env_output(form_data.fields, env_prefix, file_metadata))
117
140
  else:
118
141
  print(format_json_output(form_data.fields, file_metadata, success=True))
119
142
 
143
+ if envfile_error is not None:
144
+ print(f'Error: Cannot write the envfile {args.envfile}: {envfile_error}', file=sys.stderr)
145
+ print(' The submission was still printed to stdout.', file=sys.stderr)
146
+ return EXIT_READ_ERROR
147
+
120
148
  return EXIT_SUCCESS
121
149
 
122
150
  except KeyboardInterrupt:
@@ -124,6 +152,10 @@ def run_readwebform(args) -> int:
124
152
  print('\nInterrupted by user', file=sys.stderr)
125
153
  return EXIT_INTERRUPTED
126
154
  except Exception as e:
155
+ if _caused_by_interrupt(e):
156
+ _emit_failure(args, 'interrupted')
157
+ print('\nInterrupted by user', file=sys.stderr)
158
+ return EXIT_INTERRUPTED
127
159
  print(f'Internal error: {e}', file=sys.stderr)
128
160
  traceback.print_exc(file=sys.stderr)
129
161
  return EXIT_INTERNAL_ERROR
@@ -169,6 +201,102 @@ def resolve_browser_launch(args) -> Optional[str]:
169
201
  return '' if gui_available() else None
170
202
 
171
203
 
204
+ def _check_creatable_dir(path: str, what: str) -> None:
205
+ """Raise InputError unless path is, or can be created as, a writable directory."""
206
+ path = os.path.realpath(path)
207
+ if os.path.exists(path):
208
+ if not os.path.isdir(path):
209
+ raise InputError(f'{what} {path} is not a directory', EXIT_READ_ERROR)
210
+ if not os.access(path, os.W_OK | os.X_OK):
211
+ raise InputError(f'{what} {path} is not writable', EXIT_READ_ERROR)
212
+ return
213
+ # It will be created on demand: the nearest existing ancestor decides
214
+ ancestor = os.path.dirname(path)
215
+ while ancestor and not os.path.exists(ancestor) and os.path.dirname(ancestor) != ancestor:
216
+ ancestor = os.path.dirname(ancestor)
217
+ if not os.path.isdir(ancestor):
218
+ raise InputError(f'{what} {path} cannot be created: {ancestor} is not a directory',
219
+ EXIT_READ_ERROR)
220
+ if not os.access(ancestor, os.W_OK | os.X_OK):
221
+ raise InputError(f'{what} {path} cannot be created: {ancestor} is not writable',
222
+ EXIT_READ_ERROR)
223
+
224
+
225
+ def _check_writable_file(path: str, what: str, will_be_created: Optional[str] = None) -> None:
226
+ """
227
+ Raise InputError unless a file can be created or overwritten at path.
228
+
229
+ will_be_created names a directory that readwebform may create later (the
230
+ upload directory); a file inside it cannot be checked yet and is allowed.
231
+ """
232
+ if os.path.isdir(path):
233
+ raise InputError(f'{what} {path} is a directory', EXIT_READ_ERROR)
234
+ target = os.path.realpath(path) # follows a symlink, including a dangling one
235
+ if os.path.exists(target):
236
+ if not os.access(target, os.W_OK):
237
+ raise InputError(f'{what} {path} is not writable', EXIT_READ_ERROR)
238
+ return
239
+ parent = os.path.dirname(target) or '.'
240
+ if not os.path.isdir(parent):
241
+ if will_be_created and os.path.realpath(will_be_created) == parent:
242
+ return
243
+ raise InputError(f'{what} {path}: the directory {parent} does not exist', EXIT_READ_ERROR)
244
+ if not os.access(parent, os.W_OK | os.X_OK):
245
+ raise InputError(f'{what} {path}: the directory {parent} is not writable', EXIT_READ_ERROR)
246
+
247
+
248
+ def check_paths(args) -> None:
249
+ """
250
+ Check the file arguments before the form is shown.
251
+
252
+ Finding out that the envfile cannot be written only after the user has
253
+ filled in the form would waste their submission, so fail now instead.
254
+ This is a courtesy check, not a guarantee: the write can still fail later.
255
+
256
+ Raises:
257
+ InputError: with exit code 3 if a path is unusable
258
+ """
259
+ upload_dir = getattr(args, 'upload_dir', None)
260
+ if upload_dir:
261
+ _check_creatable_dir(upload_dir, 'The upload directory')
262
+ envfile = getattr(args, 'envfile', None)
263
+ if envfile:
264
+ _check_writable_file(envfile, 'The envfile', will_be_created=upload_dir)
265
+ url_file = getattr(args, 'url_file', None)
266
+ if url_file:
267
+ _check_writable_file(url_file, 'The URL file')
268
+ for option, what in (('cert', 'The certificate'), ('key', 'The key')):
269
+ path = getattr(args, option, None)
270
+ if not path:
271
+ continue
272
+ # Not isfile(): a named pipe or /dev/fd/N from process substitution
273
+ # is a legitimate way to pass a key.
274
+ if os.path.isdir(path):
275
+ raise InputError(f'{what} file {path} is a directory', EXIT_READ_ERROR)
276
+ if not os.path.exists(path):
277
+ raise InputError(f'{what} file {path} does not exist', EXIT_READ_ERROR)
278
+ if not os.access(path, os.R_OK):
279
+ raise InputError(f'{what} file {path} is not readable', EXIT_READ_ERROR)
280
+
281
+
282
+ def _caused_by_interrupt(error: BaseException) -> bool:
283
+ """
284
+ True if a KeyboardInterrupt is behind this exception.
285
+
286
+ Ctrl+C that lands inside threading internals (for example while a thread
287
+ is being started) can surface as "RuntimeError: release unlocked lock"
288
+ raised while the KeyboardInterrupt was being handled.
289
+ """
290
+ seen = set()
291
+ current: Optional[BaseException] = error
292
+ while current is not None and id(current) not in seen:
293
+ if isinstance(current, KeyboardInterrupt):
294
+ return True
295
+ seen.add(id(current))
296
+ current = current.__cause__ or current.__context__
297
+ return False
298
+
299
+
172
300
  def _emit_failure(args, error: str) -> None:
173
301
  """Print the JSON failure envelope unless env output was requested."""
174
302
  if not args.print_env:
@@ -238,4 +366,9 @@ def read_stdin() -> str:
238
366
  """Read HTML from stdin."""
239
367
  if sys.stdin.isatty():
240
368
  print('Reading HTML from stdin (press Ctrl+D when done)...', file=sys.stderr)
241
- return sys.stdin.read()
369
+ try:
370
+ # Read bytes and decode as UTF-8 ourselves: the text layer would use
371
+ # the locale's encoding, and would raise a bare UnicodeDecodeError.
372
+ return sys.stdin.buffer.read().decode('utf-8')
373
+ except UnicodeDecodeError as e:
374
+ raise InputError(f'The HTML on stdin is not valid UTF-8: {e}', EXIT_READ_ERROR) from e
@@ -9,6 +9,10 @@ from typing import Optional
9
9
  from .parser import render_page
10
10
 
11
11
  # Field types accepted by --field and the Python API
12
+ # Names readwebform uses itself: the CSRF token and the cancel button. A user
13
+ # field with one of these names would break every submission.
14
+ RESERVED_NAMES = frozenset({'_csrf_token', '_cancel'})
15
+
12
16
  VALID_TYPES = frozenset({
13
17
  'text', 'email', 'password', 'number', 'date', 'url', 'tel', 'search',
14
18
  'time', 'datetime-local', 'month', 'week', 'range', 'color', 'hidden',
@@ -62,6 +66,8 @@ class FieldSpec:
62
66
 
63
67
  if not name:
64
68
  raise ValueError(f'Invalid field spec: {spec} (field name is empty)')
69
+ if name in RESERVED_NAMES:
70
+ raise ValueError(f'Invalid field spec: {spec} (the name {name} is reserved)')
65
71
 
66
72
  if field_type not in VALID_TYPES:
67
73
  raise ValueError(
@@ -339,9 +345,13 @@ def dict_to_fieldspec(field_dict: dict) -> FieldSpec:
339
345
  ValueError: If the name or type is missing or invalid
340
346
  """
341
347
  name = field_dict.get('name')
348
+ if isinstance(name, str):
349
+ name = name.strip() # as FieldSpec.parse does
342
350
  field_type = str(field_dict.get('type', '')).lower()
343
351
  if not name:
344
352
  raise ValueError('Field is missing a name')
353
+ if name in RESERVED_NAMES:
354
+ raise ValueError(f'The field name {name} is reserved')
345
355
  if field_type not in VALID_TYPES:
346
356
  raise ValueError(f'Invalid field type: {field_type!r} for field {name!r} '
347
357
  f'(must be one of {", ".join(sorted(VALID_TYPES))})')
@@ -347,20 +347,25 @@ def extract_value_from_header(header: str, param: str) -> Optional[str]:
347
347
  return parse_header_params(header).get(param.lower())
348
348
 
349
349
 
350
- def save_uploaded_file(uploaded_file: UploadedFile, directory: str) -> str:
350
+ def save_uploaded_file(uploaded_file: UploadedFile, directory: str,
351
+ next_suffix: Optional[dict[str, int]] = None) -> str:
351
352
  """
352
353
  Save an uploaded file to a directory, avoiding name collisions.
353
354
 
354
355
  Args:
355
356
  uploaded_file: UploadedFile instance
356
357
  directory: Target directory (must exist)
358
+ next_suffix: Optional dict shared between the calls for one request.
359
+ It remembers the next free suffix for each filename, so saving
360
+ many files with the same name does not retry every earlier
361
+ suffix each time.
357
362
 
358
363
  Returns:
359
364
  Full path to the saved file
360
365
  """
361
366
  filename = sanitize_filename(uploaded_file.filename)
362
367
  base, ext = os.path.splitext(filename)
363
- counter = 0
368
+ counter = next_suffix.get(filename, 0) if next_suffix is not None else 0
364
369
  while True:
365
370
  candidate = filename if counter == 0 else f'{base}_{counter}{ext}'
366
371
  filepath = os.path.join(directory, candidate)
@@ -370,6 +375,8 @@ def save_uploaded_file(uploaded_file: UploadedFile, directory: str) -> str:
370
375
  except FileExistsError:
371
376
  counter += 1
372
377
  continue
378
+ if next_suffix is not None:
379
+ next_suffix[filename] = counter + 1
373
380
  with os.fdopen(fd, 'wb') as f:
374
381
  f.write(uploaded_file.content)
375
382
  return filepath