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
readwebform/multipart.py
ADDED
|
@@ -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)
|