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,399 @@
1
+ """
2
+ Multipart form data parser for readwebform.
3
+
4
+ Implements RFC 7578 (multipart/form-data) parsing without using the deprecated
5
+ cgi.FieldStorage module.
6
+ """
7
+
8
+ import os
9
+ import re
10
+ import urllib.parse
11
+ from typing import Optional, Union
12
+
13
+
14
+ class FormParseError(ValueError):
15
+ """Raised when a request body cannot be parsed."""
16
+
17
+
18
+ class SizeLimitExceeded(ValueError):
19
+ """Raised when an upload exceeds a configured size limit."""
20
+
21
+
22
+ class UploadedFile:
23
+ """Represents an uploaded file held in memory before it is saved."""
24
+
25
+ def __init__(self, filename: str, content: bytes, content_type: str):
26
+ self.filename = filename
27
+ self.content = content
28
+ self.content_type = content_type
29
+ self.size = len(content)
30
+
31
+
32
+ class FormData:
33
+ """Represents parsed form data.
34
+
35
+ Fields with the same name (e.g. multiple checkboxes or a multi-select) are
36
+ stored as lists. Single values are stored as strings. Files with the same
37
+ name (e.g. ``<input type="file" multiple>``) are stored as lists of
38
+ UploadedFile objects.
39
+ """
40
+
41
+ def __init__(self):
42
+ self.fields: dict[str, Union[str, list[str]]] = {}
43
+ self.files: dict[str, Union[UploadedFile, list[UploadedFile]]] = {}
44
+
45
+ def add_field(self, name: str, value: str) -> None:
46
+ """Add a field value, converting to a list if the name already exists."""
47
+ if name in self.fields:
48
+ existing = self.fields[name]
49
+ if isinstance(existing, list):
50
+ existing.append(value)
51
+ else:
52
+ self.fields[name] = [existing, value]
53
+ else:
54
+ self.fields[name] = value
55
+
56
+ def add_file(self, name: str, uploaded_file: UploadedFile) -> None:
57
+ """Add an uploaded file, converting to a list if the name already exists."""
58
+ if name in self.files:
59
+ existing = self.files[name]
60
+ if isinstance(existing, list):
61
+ existing.append(uploaded_file)
62
+ else:
63
+ self.files[name] = [existing, uploaded_file]
64
+ else:
65
+ self.files[name] = uploaded_file
66
+
67
+ def iter_files(self):
68
+ """Yield (name, UploadedFile) pairs, flattening repeated file fields."""
69
+ for name, value in self.files.items():
70
+ if isinstance(value, list):
71
+ for item in value:
72
+ yield name, item
73
+ else:
74
+ yield name, value
75
+
76
+
77
+ def parse_size_limit(limit_str: Optional[str]) -> Optional[int]:
78
+ """
79
+ Parse a size limit string to bytes.
80
+
81
+ Examples:
82
+ "5M" -> 5242880
83
+ "200K" -> 204800
84
+ "1G" -> 1073741824
85
+
86
+ Args:
87
+ limit_str: Size limit string (e.g. "5M", "200K"), or None for no limit
88
+
89
+ Returns:
90
+ Size in bytes, or None if no limit was given
91
+
92
+ Raises:
93
+ ValueError: If the string is not a valid size
94
+ """
95
+ if limit_str is None or limit_str.strip() == '':
96
+ return None
97
+
98
+ limit_str = limit_str.strip().upper()
99
+ multipliers = {
100
+ 'K': 1024,
101
+ 'M': 1024 * 1024,
102
+ 'G': 1024 * 1024 * 1024,
103
+ }
104
+
105
+ match = re.match(r'^(\d+)([KMG])?$', limit_str)
106
+ if not match:
107
+ raise ValueError(f'Invalid size limit format: {limit_str}')
108
+
109
+ value = int(match.group(1))
110
+ unit = match.group(2)
111
+
112
+ if unit:
113
+ return value * multipliers[unit]
114
+ return value
115
+
116
+
117
+ def parse_multipart(
118
+ body: bytes,
119
+ content_type: str,
120
+ max_file_size: Optional[int] = None,
121
+ max_total_size: Optional[int] = None
122
+ ) -> FormData:
123
+ """
124
+ Parse a multipart/form-data request body.
125
+
126
+ Args:
127
+ body: Request body as bytes
128
+ content_type: Content-Type header value
129
+ max_file_size: Maximum size for an individual file (None = no limit)
130
+ max_total_size: Maximum total body size (None = no limit)
131
+
132
+ Returns:
133
+ FormData instance
134
+
135
+ Raises:
136
+ SizeLimitExceeded: If a size limit is exceeded
137
+ FormParseError: If the body cannot be parsed
138
+ """
139
+ if max_total_size is not None and len(body) > max_total_size:
140
+ raise SizeLimitExceeded(f'Total upload size {len(body)} exceeds limit {max_total_size}')
141
+
142
+ boundary = extract_boundary(content_type)
143
+ if not boundary:
144
+ raise FormParseError('No boundary found in Content-Type header')
145
+
146
+ form_data = FormData()
147
+
148
+ for part in split_multipart_body(body, boundary):
149
+ headers, content = parse_part(part)
150
+ disposition = headers.get('content-disposition', '')
151
+ params = parse_header_params(disposition)
152
+
153
+ name = params.get('name')
154
+ if name is None:
155
+ # RFC 7578 requires a name; ignore parts without one
156
+ continue
157
+
158
+ filename = params.get('filename')
159
+ # An unselected <input type="file"> arrives as filename="" with an
160
+ # empty body; browsers always send it, so treat it as an empty field.
161
+ if filename:
162
+ if max_file_size is not None and len(content) > max_file_size:
163
+ raise SizeLimitExceeded(
164
+ f'File {filename} size {len(content)} exceeds limit {max_file_size}'
165
+ )
166
+ content_type_part = headers.get('content-type', 'application/octet-stream')
167
+ form_data.add_file(name, UploadedFile(filename, content, content_type_part))
168
+ else:
169
+ # Form fields are UTF-8 text; undecodable bytes are replaced rather than dropped
170
+ form_data.add_field(name, content.decode('utf-8', errors='replace'))
171
+
172
+ return form_data
173
+
174
+
175
+ def parse_urlencoded(body: bytes) -> FormData:
176
+ """
177
+ Parse an application/x-www-form-urlencoded request body.
178
+
179
+ Args:
180
+ body: Request body as bytes
181
+
182
+ Returns:
183
+ FormData instance
184
+
185
+ Raises:
186
+ FormParseError: If the body is not valid UTF-8
187
+ """
188
+ form_data = FormData()
189
+ try:
190
+ text = body.decode('utf-8')
191
+ except UnicodeDecodeError as e:
192
+ raise FormParseError(f'Form body is not valid UTF-8: {e}') from e
193
+
194
+ parsed = urllib.parse.parse_qs(text, keep_blank_values=True)
195
+ for key, values in parsed.items():
196
+ for value in values:
197
+ form_data.add_field(key, value)
198
+
199
+ return form_data
200
+
201
+
202
+ def extract_boundary(content_type: str) -> Optional[str]:
203
+ """
204
+ Extract the boundary parameter from a Content-Type header.
205
+
206
+ Args:
207
+ content_type: Content-Type header value
208
+
209
+ Returns:
210
+ Boundary string or None
211
+ """
212
+ params = parse_header_params(content_type)
213
+ boundary = params.get('boundary')
214
+ if boundary:
215
+ return boundary
216
+ return None
217
+
218
+
219
+ _PARAM_RE = re.compile(
220
+ r';\s*([A-Za-z0-9_.*-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^;]*))'
221
+ )
222
+
223
+
224
+ def parse_header_params(header: str) -> dict[str, str]:
225
+ """
226
+ Parse the ``; key=value`` parameters of a header such as Content-Disposition.
227
+
228
+ Parameters are only recognised after a ``;`` so ``filename=`` can never be
229
+ mistaken for ``name=``. Quoted values may contain backslash escapes. A
230
+ ``key*=charset''value`` (RFC 5987) parameter is decoded and stored under
231
+ ``key``.
232
+
233
+ Args:
234
+ header: Full header value, e.g. ``form-data; name="f"; filename="a.txt"``
235
+
236
+ Returns:
237
+ Dict of lower-cased parameter names to values
238
+ """
239
+ params: dict[str, str] = {}
240
+ for match in _PARAM_RE.finditer(header):
241
+ key = match.group(1).lower()
242
+ if match.group(2) is not None:
243
+ value = re.sub(r'\\(.)', r'\1', match.group(2))
244
+ else:
245
+ value = (match.group(3) or '').strip()
246
+
247
+ if key.endswith('*'):
248
+ key = key[:-1]
249
+ value = _decode_rfc5987(value)
250
+ params[key] = value
251
+ elif key not in params:
252
+ params[key] = value
253
+ return params
254
+
255
+
256
+ def _decode_rfc5987(value: str) -> str:
257
+ """Decode a ``charset'lang'percent-encoded`` extended parameter value."""
258
+ parts = value.split("'", 2)
259
+ if len(parts) == 3:
260
+ charset, _, encoded = parts
261
+ try:
262
+ return urllib.parse.unquote(encoded, encoding=charset or 'utf-8', errors='replace')
263
+ except LookupError:
264
+ return urllib.parse.unquote(encoded, errors='replace')
265
+ return urllib.parse.unquote(value, errors='replace')
266
+
267
+
268
+ def split_multipart_body(body: bytes, boundary: str) -> list[bytes]:
269
+ """
270
+ Split a multipart body into its parts (headers and content, undecoded).
271
+
272
+ A delimiter is only recognised at the start of a line, so a boundary string
273
+ that happens to occur inside a part's content is left untouched. Exactly the
274
+ CRLF (or LF) that precedes each delimiter is consumed; all other bytes of a
275
+ part are preserved.
276
+
277
+ Args:
278
+ body: Request body
279
+ boundary: Boundary string from the Content-Type header
280
+
281
+ Returns:
282
+ List of raw parts
283
+ """
284
+ delimiter = re.compile(
285
+ rb'(?:^|\r?\n)--' + re.escape(boundary.encode('utf-8')) + rb'(--)?[ \t]*(?:\r?\n|$)'
286
+ )
287
+
288
+ matches = list(delimiter.finditer(body))
289
+ parts = []
290
+ for i, match in enumerate(matches):
291
+ if match.group(1): # closing delimiter --boundary--
292
+ break
293
+ start = match.end()
294
+ end = matches[i + 1].start() if i + 1 < len(matches) else len(body)
295
+ parts.append(body[start:end])
296
+ return parts
297
+
298
+
299
+ def parse_part(part: bytes) -> tuple[dict[str, str], bytes]:
300
+ """
301
+ Parse a single multipart part into headers and content.
302
+
303
+ Args:
304
+ part: Raw part (headers, blank line, content)
305
+
306
+ Returns:
307
+ Tuple of (headers_dict, content). Header names are lower-cased. Header
308
+ values are decoded as UTF-8, which is how browsers send non-ASCII
309
+ filenames.
310
+ """
311
+ crlf_idx = part.find(b'\r\n\r\n')
312
+ lf_idx = part.find(b'\n\n')
313
+ if crlf_idx != -1 and (lf_idx == -1 or crlf_idx <= lf_idx):
314
+ header_data, content = part[:crlf_idx], part[crlf_idx + 4:]
315
+ elif lf_idx != -1:
316
+ header_data, content = part[:lf_idx], part[lf_idx + 2:]
317
+ else:
318
+ header_data, content = part, b''
319
+
320
+ headers: dict[str, str] = {}
321
+ last_key: Optional[str] = None
322
+ for line in header_data.decode('utf-8', errors='replace').splitlines():
323
+ if line[:1] in (' ', '\t') and last_key is not None:
324
+ # Folded header continuation line (RFC 5322 section 2.2.3)
325
+ headers[last_key] += ' ' + line.strip()
326
+ continue
327
+ if ':' not in line:
328
+ continue
329
+ key, value = line.split(':', 1)
330
+ last_key = key.strip().lower()
331
+ headers[last_key] = value.strip()
332
+
333
+ return headers, content
334
+
335
+
336
+ def extract_value_from_header(header: str, param: str) -> Optional[str]:
337
+ """
338
+ Extract a single parameter value from a header such as Content-Disposition.
339
+
340
+ Args:
341
+ header: Header value (e.g. 'form-data; name="field1"; filename="test.txt"')
342
+ param: Parameter name to extract (e.g. 'name', 'filename')
343
+
344
+ Returns:
345
+ Parameter value or None
346
+ """
347
+ return parse_header_params(header).get(param.lower())
348
+
349
+
350
+ def save_uploaded_file(uploaded_file: UploadedFile, directory: str) -> str:
351
+ """
352
+ Save an uploaded file to a directory, avoiding name collisions.
353
+
354
+ Args:
355
+ uploaded_file: UploadedFile instance
356
+ directory: Target directory (must exist)
357
+
358
+ Returns:
359
+ Full path to the saved file
360
+ """
361
+ filename = sanitize_filename(uploaded_file.filename)
362
+ base, ext = os.path.splitext(filename)
363
+ counter = 0
364
+ while True:
365
+ candidate = filename if counter == 0 else f'{base}_{counter}{ext}'
366
+ filepath = os.path.join(directory, candidate)
367
+ try:
368
+ # O_EXCL makes the collision check atomic
369
+ fd = os.open(filepath, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
370
+ except FileExistsError:
371
+ counter += 1
372
+ continue
373
+ with os.fdopen(fd, 'wb') as f:
374
+ f.write(uploaded_file.content)
375
+ return filepath
376
+
377
+
378
+ def sanitize_filename(filename: str) -> str:
379
+ """
380
+ Sanitize a filename to prevent directory traversal.
381
+
382
+ Args:
383
+ filename: Original filename from the client
384
+
385
+ Returns:
386
+ A safe basename
387
+ """
388
+ # Strip any directory components (handle both / and \ regardless of OS)
389
+ filename = filename.replace('\\', '/')
390
+ filename = os.path.basename(filename)
391
+ # Replace any remaining problematic characters
392
+ filename = re.sub(r'[^\w\s.-]', '_', filename)
393
+ # Limit length
394
+ if len(filename) > 255:
395
+ filename = filename[:255]
396
+ # Ensure not empty or a special directory name
397
+ if not filename or filename in ('.', '..'):
398
+ filename = 'upload'
399
+ return filename
readwebform/output.py ADDED
@@ -0,0 +1,171 @@
1
+ """
2
+ Output formatting for readwebform (JSON and environment variables).
3
+ """
4
+
5
+ import json
6
+ import os
7
+ import re
8
+ import shlex
9
+ import sys
10
+ from typing import Any, Optional, Union
11
+
12
+ DEFAULT_ENV_PREFIX = 'WEBFORM_'
13
+
14
+ _VAR_NAME_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
15
+
16
+
17
+ def format_json_output(
18
+ fields: Optional[dict[str, Any]],
19
+ files: Optional[dict[str, Any]],
20
+ success: bool = True,
21
+ error: Optional[str] = None
22
+ ) -> str:
23
+ """
24
+ Format form data as JSON with a consistent envelope.
25
+
26
+ Args:
27
+ fields: Field names to values (a list for repeated fields)
28
+ files: File field names to metadata dicts (a list for repeated file fields)
29
+ success: Whether the form submission was successful
30
+ error: Error name if not successful (e.g. 'timeout', 'cancelled')
31
+
32
+ Returns:
33
+ JSON string with keys success, fields, files, error (always present)
34
+ """
35
+ output = {
36
+ 'success': success,
37
+ 'fields': fields if fields is not None else {},
38
+ 'files': files if files is not None else {},
39
+ 'error': error
40
+ }
41
+ return json.dumps(output, indent=2, ensure_ascii=False)
42
+
43
+
44
+ def env_var_name(name: str, prefix: str = DEFAULT_ENV_PREFIX) -> str:
45
+ """
46
+ Derive a shell variable name from a form field name.
47
+
48
+ Characters that are not letters, digits or underscores become
49
+ underscores, and the result is upper-cased: ``first-name`` becomes
50
+ ``WEBFORM_FIRST_NAME``.
51
+ """
52
+ return prefix + re.sub(r'[^A-Za-z0-9_]', '_', name).upper()
53
+
54
+
55
+ def format_env_output(
56
+ fields: dict[str, Union[str, list[str]]],
57
+ prefix: str = DEFAULT_ENV_PREFIX,
58
+ files: Optional[dict[str, Any]] = None
59
+ ) -> str:
60
+ """
61
+ Format form data as shell ``export`` statements.
62
+
63
+ A repeated field (checkbox group, multi-select) produces
64
+ ``PREFIX_NAME`` with the values joined by newlines (rendered as the
65
+ literal two characters ``\\n``), ``PREFIX_NAME_COUNT`` and
66
+ ``PREFIX_NAME_1`` .. ``PREFIX_NAME_N``.
67
+
68
+ Uploaded files produce ``PREFIX_NAME_PATH`` and ``PREFIX_NAME_FILENAME``
69
+ (indexed in the same way when repeated).
70
+
71
+ Args:
72
+ fields: Field names to values
73
+ prefix: Prefix for variable names
74
+ files: Optional file metadata as produced by the server
75
+
76
+ Returns:
77
+ Shell export statements preceded by a warning comment
78
+ """
79
+ lines: list[str] = []
80
+ seen: dict[str, str] = {}
81
+ skipped: list[str] = []
82
+
83
+ def emit(var_name: str, value: str, source: str) -> None:
84
+ if not is_valid_var_name(var_name):
85
+ skipped.append(source)
86
+ return
87
+ if var_name in seen and seen[var_name] != source:
88
+ print(f'Warning: fields {seen[var_name]!r} and {source!r} both map to '
89
+ f'{var_name}; the latter wins', file=sys.stderr)
90
+ seen[var_name] = source
91
+ lines.append(f'export {var_name}={shlex.quote(sanitize_env_value(value))}')
92
+
93
+ for name, value in fields.items():
94
+ var_name = env_var_name(name, prefix)
95
+ if isinstance(value, list):
96
+ emit(var_name, '\n'.join(value), name)
97
+ emit(var_name + '_COUNT', str(len(value)), name)
98
+ for i, item in enumerate(value, 1):
99
+ emit(f'{var_name}_{i}', item, name)
100
+ else:
101
+ emit(var_name, value, name)
102
+
103
+ for name, meta in (files or {}).items():
104
+ var_name = env_var_name(name, prefix)
105
+ if isinstance(meta, list):
106
+ emit(var_name + '_COUNT', str(len(meta)), name)
107
+ for i, item in enumerate(meta, 1):
108
+ emit(f'{var_name}_{i}_PATH', item['path'], name)
109
+ emit(f'{var_name}_{i}_FILENAME', item['filename'], name)
110
+ else:
111
+ emit(var_name + '_PATH', meta['path'], name)
112
+ emit(var_name + '_FILENAME', meta['filename'], name)
113
+
114
+ if skipped:
115
+ print(f'Warning: Skipped invalid variable names: {", ".join(skipped)}', file=sys.stderr)
116
+
117
+ disclaimer = ('# WARNING: Environment files are for trusted local use only.\n'
118
+ '# Do not source envfiles generated from untrusted form data.\n')
119
+ return disclaimer + '\n'.join(lines)
120
+
121
+
122
+ def is_valid_var_name(name: str) -> bool:
123
+ """Check whether a string is a valid shell variable name."""
124
+ return bool(_VAR_NAME_RE.match(name))
125
+
126
+
127
+ def sanitize_env_value(value: str) -> str:
128
+ """
129
+ Sanitize a value for a single-line environment variable assignment.
130
+
131
+ Newlines become the literal characters ``\\n``, carriage returns are
132
+ dropped, and other control characters (except tab) are removed.
133
+ """
134
+ value = value.replace('\r', '').replace('\n', '\\n')
135
+ return ''.join(ch for ch in value if ch == '\t' or not (ord(ch) < 32 or ord(ch) == 127))
136
+
137
+
138
+ def write_env_file(filepath: str, fields: dict[str, Union[str, list[str]]],
139
+ prefix: str = DEFAULT_ENV_PREFIX,
140
+ files: Optional[dict[str, Any]] = None) -> None:
141
+ """
142
+ Write environment variable exports to a file readable only by the owner.
143
+
144
+ On POSIX the file is created with, or changed to, mode 0600; if an
145
+ existing file cannot be changed, OSError is raised and nothing is written.
146
+ Windows has no equivalent permission bits, so there the file inherits the
147
+ directory's ACL.
148
+
149
+ Args:
150
+ filepath: Output path (created or truncated with mode 0600)
151
+ fields: Field names to values
152
+ prefix: Prefix for variable names
153
+ files: Optional file metadata
154
+ """
155
+ content = format_env_output(fields, prefix, files)
156
+ # Open without O_TRUNC so an existing file keeps its contents if the
157
+ # permission change below fails.
158
+ fd = os.open(filepath, os.O_WRONLY | os.O_CREAT, 0o600)
159
+ try:
160
+ # The creation mode only applies to a new file. If the file exists
161
+ # and cannot be made owner-only, refuse to write secrets to it.
162
+ if hasattr(os, 'fchmod'):
163
+ os.fchmod(fd, 0o600)
164
+ else: # pragma: no cover - Windows has no fchmod; chmod only sets read-only
165
+ os.chmod(filepath, 0o600)
166
+ os.ftruncate(fd, 0)
167
+ except OSError:
168
+ os.close(fd)
169
+ raise
170
+ with os.fdopen(fd, 'w', encoding='utf-8') as f:
171
+ f.write(content)