ser2netweb 3.0.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.
- ser2netweb/__init__.py +20 -0
- ser2netweb/__main__.py +6 -0
- ser2netweb/accounts.py +503 -0
- ser2netweb/cli.py +489 -0
- ser2netweb/clock.py +128 -0
- ser2netweb/config.py +4491 -0
- ser2netweb/console.py +181 -0
- ser2netweb/datalock.py +181 -0
- ser2netweb/engine/__init__.py +0 -0
- ser2netweb/engine/access.py +173 -0
- ser2netweb/engine/bindhint.py +115 -0
- ser2netweb/engine/bridge.py +1928 -0
- ser2netweb/engine/cluster.py +1140 -0
- ser2netweb/engine/modbus.py +530 -0
- ser2netweb/engine/modbus_gateway.py +1465 -0
- ser2netweb/engine/mqtt_pub.py +632 -0
- ser2netweb/engine/netguard.py +805 -0
- ser2netweb/engine/netinfo.py +199 -0
- ser2netweb/engine/portdiag.py +414 -0
- ser2netweb/engine/portlist.py +471 -0
- ser2netweb/engine/protocols/__init__.py +28 -0
- ser2netweb/engine/protocols/base.py +117 -0
- ser2netweb/engine/protocols/raw.py +12 -0
- ser2netweb/engine/protocols/rfc2217.py +586 -0
- ser2netweb/engine/protocols/telnet.py +172 -0
- ser2netweb/engine/serial_compat.py +598 -0
- ser2netweb/engine/serial_io.py +210 -0
- ser2netweb/engine/serial_link.py +414 -0
- ser2netweb/engine/sockopts.py +103 -0
- ser2netweb/engine/sparkplug.py +538 -0
- ser2netweb/engine/sparkplug_node.py +550 -0
- ser2netweb/engine/supervisor.py +533 -0
- ser2netweb/engine/tls.py +232 -0
- ser2netweb/envvars.py +57 -0
- ser2netweb/explain.py +117 -0
- ser2netweb/healthcheck.py +78 -0
- ser2netweb/i18n.py +110 -0
- ser2netweb/importer.py +550 -0
- ser2netweb/layout.py +118 -0
- ser2netweb/licences.py +86 -0
- ser2netweb/locale/tr.json +1569 -0
- ser2netweb/logsetup.py +253 -0
- ser2netweb/logtext.py +23 -0
- ser2netweb/notify.py +761 -0
- ser2netweb/optional.py +76 -0
- ser2netweb/reload.py +295 -0
- ser2netweb/runtime.py +762 -0
- ser2netweb/sdnotify.py +85 -0
- ser2netweb/ser2net_import.py +2001 -0
- ser2netweb/signins.py +98 -0
- ser2netweb/standalone.py +154 -0
- ser2netweb/state.py +1457 -0
- ser2netweb/storage.py +130 -0
- ser2netweb/textfold.py +51 -0
- ser2netweb/tlsreload.py +37 -0
- ser2netweb/watchdog.py +201 -0
- ser2netweb/web/__init__.py +0 -0
- ser2netweb/web/api.py +793 -0
- ser2netweb/web/auth.py +699 -0
- ser2netweb/web/certinfo.py +144 -0
- ser2netweb/web/httpguard.py +413 -0
- ser2netweb/web/ldap_auth.py +556 -0
- ser2netweb/web/oidc_auth.py +330 -0
- ser2netweb/web/proxy.py +398 -0
- ser2netweb/web/routes/__init__.py +78 -0
- ser2netweb/web/routes/cluster.py +669 -0
- ser2netweb/web/routes/common.py +359 -0
- ser2netweb/web/routes/console.py +451 -0
- ser2netweb/web/routes/forms.py +853 -0
- ser2netweb/web/routes/login.py +573 -0
- ser2netweb/web/routes/mappings.py +470 -0
- ser2netweb/web/routes/ops.py +374 -0
- ser2netweb/web/routes/settings.py +2135 -0
- ser2netweb/web/routes/system.py +308 -0
- ser2netweb/web/routes/totp.py +282 -0
- ser2netweb/web/selfsigned.py +129 -0
- ser2netweb/web/server.py +483 -0
- ser2netweb/web/static/app.css +327 -0
- ser2netweb/web/static/app.js +1102 -0
- ser2netweb/web/static/htmx.min.js +1 -0
- ser2netweb/web/static/points.js +218 -0
- ser2netweb/web/static/theme.js +7 -0
- ser2netweb/web/static/xterm-addon-fit.js +2 -0
- ser2netweb/web/static/xterm.css +218 -0
- ser2netweb/web/static/xterm.js +2 -0
- ser2netweb/web/templates/_cluster_body.html +109 -0
- ser2netweb/web/templates/_console.html +21 -0
- ser2netweb/web/templates/_footer.html +13 -0
- ser2netweb/web/templates/_login_notice.html +8 -0
- ser2netweb/web/templates/_macros.html +21 -0
- ser2netweb/web/templates/_mapping_form.html +477 -0
- ser2netweb/web/templates/_mapping_log.html +28 -0
- ser2netweb/web/templates/_mapping_traces.html +44 -0
- ser2netweb/web/templates/_mappings_body.html +149 -0
- ser2netweb/web/templates/_modbus_read.html +18 -0
- ser2netweb/web/templates/_ports_table.html +37 -0
- ser2netweb/web/templates/_serial_port_select.html +48 -0
- ser2netweb/web/templates/_shell.html +41 -0
- ser2netweb/web/templates/audit.html +55 -0
- ser2netweb/web/templates/base.html +77 -0
- ser2netweb/web/templates/dashboard.html +72 -0
- ser2netweb/web/templates/licenses.html +18 -0
- ser2netweb/web/templates/login.html +32 -0
- ser2netweb/web/templates/login_totp.html +23 -0
- ser2netweb/web/templates/settings.html +830 -0
- ser2netweb/web/templates/setup.html +43 -0
- ser2netweb/web/templates/totp.html +41 -0
- ser2netweb/web/totp.py +94 -0
- ser2netweb/winservice.py +1793 -0
- ser2netweb-3.0.0.dist-info/METADATA +120 -0
- ser2netweb-3.0.0.dist-info/RECORD +121 -0
- ser2netweb-3.0.0.dist-info/WHEEL +5 -0
- ser2netweb-3.0.0.dist-info/entry_points.txt +2 -0
- ser2netweb-3.0.0.dist-info/licenses/COMMERCIAL_LICENSE.md +94 -0
- ser2netweb-3.0.0.dist-info/licenses/LICENSE +662 -0
- ser2netweb-3.0.0.dist-info/licenses/NOTICE +20 -0
- ser2netweb-3.0.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +105 -0
- ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/htmx.org.txt +13 -0
- ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm-addon-fit.txt +19 -0
- ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm.txt +21 -0
- ser2netweb-3.0.0.dist-info/top_level.txt +1 -0
ser2netweb/importer.py
ADDED
|
@@ -0,0 +1,550 @@
|
|
|
1
|
+
"""Importing mappings: parse an uploaded file, plan the change, apply it.
|
|
2
|
+
|
|
3
|
+
The web UI first shows a preview (plan_rows) and only then applies the import, in
|
|
4
|
+
one of two modes:
|
|
5
|
+
* merge — a mapping with the same id, else the same name, is updated in place
|
|
6
|
+
(keeping the existing id, so its log and traces stay attached; a setting
|
|
7
|
+
the file doesn't have — an export of an older version — keeps its current
|
|
8
|
+
value); the others are added; mappings not in the file stay as they are;
|
|
9
|
+
* replace — the file's mappings replace all current ones (the pre-v2.8 behaviour).
|
|
10
|
+
Either way the previous config.json is kept in data/backups/ by ConfigStore.save.
|
|
11
|
+
|
|
12
|
+
A mapping from a ser2netweb export or config.json replaces the one it updates. One from a
|
|
13
|
+
classic ser2net file says only part of what a mapping has here, so a merge takes only
|
|
14
|
+
that part from it and keeps the rest (_overlay): TLS, the bind IP or the allowed clients
|
|
15
|
+
set after the first import, its USB identity, RS-485, MQTT, Modbus points. The preview
|
|
16
|
+
lists what an update changes and what it keeps, and how each mapping will be after the
|
|
17
|
+
import (enabled, TLS, which clients, read-only) with its own warnings.
|
|
18
|
+
"""
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import contextvars
|
|
22
|
+
import copy
|
|
23
|
+
import dataclasses
|
|
24
|
+
import ipaddress
|
|
25
|
+
import json
|
|
26
|
+
import re
|
|
27
|
+
from dataclasses import dataclass, field
|
|
28
|
+
from typing import Optional
|
|
29
|
+
|
|
30
|
+
from . import i18n
|
|
31
|
+
from .config import (
|
|
32
|
+
AppConfig, ConfigError, MappingConfig, ModbusPoint, _new_id, check_mqtt_clashes, host_port,
|
|
33
|
+
normalize_cidr,
|
|
34
|
+
)
|
|
35
|
+
from .i18n import _
|
|
36
|
+
from .ser2net_import import Note, looks_yaml, parse_ser2net_config
|
|
37
|
+
|
|
38
|
+
MODES = ("merge", "replace")
|
|
39
|
+
# An import file is read whole and its mappings are previewed and validated at once:
|
|
40
|
+
# limits far above any real export or config.json (and the classic parser has its own).
|
|
41
|
+
MAX_FILE_BYTES = 16 * 1024 * 1024
|
|
42
|
+
MAX_MAPPINGS = 1000
|
|
43
|
+
# An export or config.json nests about 6 deep. Deeper files are refused right after
|
|
44
|
+
# parsing: how deep the parser itself goes depends on the Python version and the stack
|
|
45
|
+
# (3.14 takes far deeper files), and reading a mapping recurses into its values.
|
|
46
|
+
MAX_DEPTH = 64
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass
|
|
50
|
+
class ImportPlan:
|
|
51
|
+
source: str # what the file was, for the preview
|
|
52
|
+
mappings: list[MappingConfig]
|
|
53
|
+
warnings: list[str] = field(default_factory=list)
|
|
54
|
+
classic: bool = False # a classic ser2net file: a merge overlays (_overlay)
|
|
55
|
+
# the source and the warnings in English, for the log and the audit log (which stay
|
|
56
|
+
# English: parse_for_preview); empty: as `source` / `warnings`
|
|
57
|
+
log_source: str = ""
|
|
58
|
+
log_warnings: list[str] = field(default_factory=list)
|
|
59
|
+
# per mapping, the settings the file doesn't have (see absent_settings); a merge keeps
|
|
60
|
+
# their current values. Empty for a classic ser2net configuration.
|
|
61
|
+
absent: list[list[str]] = field(default_factory=list)
|
|
62
|
+
|
|
63
|
+
def split_warnings(self) -> tuple[list[str], list[list[str]]]:
|
|
64
|
+
"""The warnings about the file as a whole, and those about each mapping (by its
|
|
65
|
+
position in `mappings`; a classic file's ser2net_import.Note knows its mapping),
|
|
66
|
+
which the preview shows in the mapping's row."""
|
|
67
|
+
general: list[str] = []
|
|
68
|
+
per: list[list[str]] = [[] for _m in self.mappings]
|
|
69
|
+
for w in self.warnings:
|
|
70
|
+
i = getattr(w, "mapping", None)
|
|
71
|
+
(per[i] if i is not None and 0 <= i < len(per) else general).append(w)
|
|
72
|
+
return general, per
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def parse_for_preview(raw: bytes, filename: str = "") -> ImportPlan:
|
|
76
|
+
"""parse_mappings_file, with the source and the warnings in English as well (log_*):
|
|
77
|
+
applying the import logs them, and the log and the audit log stay English whatever
|
|
78
|
+
the language of the page."""
|
|
79
|
+
plan = parse_mappings_file(raw, filename)
|
|
80
|
+
if i18n.current() == i18n.DEFAULT:
|
|
81
|
+
plan.log_source, plan.log_warnings = plan.source, list(plan.warnings)
|
|
82
|
+
else:
|
|
83
|
+
english = contextvars.copy_context().run(_in_english, raw, filename)
|
|
84
|
+
plan.log_source, plan.log_warnings = english.source, english.warnings
|
|
85
|
+
return plan
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _deeper_than(doc, limit: int) -> bool:
|
|
89
|
+
"""Whether a parsed JSON document nests lists / objects more than ``limit`` deep.
|
|
90
|
+
Without recursion, in memory for ``limit`` levels: one iterator per open level."""
|
|
91
|
+
levels = [iter((doc,))]
|
|
92
|
+
while levels:
|
|
93
|
+
for value in levels[-1]:
|
|
94
|
+
if isinstance(value, (dict, list)):
|
|
95
|
+
if len(levels) > limit:
|
|
96
|
+
return True
|
|
97
|
+
levels.append(iter(value.values() if isinstance(value, dict) else value))
|
|
98
|
+
break
|
|
99
|
+
else:
|
|
100
|
+
levels.pop()
|
|
101
|
+
return False
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _in_english(raw: bytes, filename: str) -> ImportPlan:
|
|
105
|
+
i18n.set_language(i18n.DEFAULT) # (in a copy of the context: for this call only)
|
|
106
|
+
return parse_mappings_file(raw, filename)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def parse_mappings_file(raw: bytes, filename: str = "") -> ImportPlan:
|
|
110
|
+
"""A ser2netweb mappings export ({"mappings": [...]}), a whole config.json, or a
|
|
111
|
+
classic ser2net configuration (ser2net.yaml of ser2net 4.x / ser2net.conf of 3.x).
|
|
112
|
+
Raises ConfigError with a user-facing message."""
|
|
113
|
+
if len(raw) > MAX_FILE_BYTES:
|
|
114
|
+
raise ConfigError(_("The file is larger than {0} MB.").format(MAX_FILE_BYTES // 2**20))
|
|
115
|
+
try:
|
|
116
|
+
text = raw.decode("utf-8-sig")
|
|
117
|
+
except UnicodeDecodeError:
|
|
118
|
+
raise ConfigError(_("The file is not UTF-8 text.")) from None
|
|
119
|
+
if not text.lstrip().startswith(("{", "[")):
|
|
120
|
+
return _classic_ser2net(text, filename)
|
|
121
|
+
try:
|
|
122
|
+
doc = json.loads(text)
|
|
123
|
+
except (ValueError, RecursionError) as e:
|
|
124
|
+
# where, not the parser's English words ("Expecting ',' delimiter: ...")
|
|
125
|
+
where = (_("line {0}, column {1}").format(e.lineno, e.colno)
|
|
126
|
+
if isinstance(e, json.JSONDecodeError) else
|
|
127
|
+
_("nested too deeply") if isinstance(e, RecursionError) else str(e))
|
|
128
|
+
raise ConfigError(_("The file is not valid JSON ({0}).").format(where)) from None
|
|
129
|
+
if _deeper_than(doc, MAX_DEPTH):
|
|
130
|
+
raise ConfigError(_("The file is not valid JSON ({0}).").format(
|
|
131
|
+
_("nested too deeply")))
|
|
132
|
+
if not isinstance(doc, dict) or not isinstance(doc.get("mappings"), list):
|
|
133
|
+
raise ConfigError(_('Expected a ser2netweb export: a JSON object with a "mappings" list.'))
|
|
134
|
+
if len(doc["mappings"]) > MAX_MAPPINGS:
|
|
135
|
+
raise ConfigError(_("The file has {0} mappings; at most {1} can be imported at once.")
|
|
136
|
+
.format(len(doc["mappings"]), MAX_MAPPINGS))
|
|
137
|
+
mappings: list[MappingConfig] = []
|
|
138
|
+
warnings: list[str] = []
|
|
139
|
+
absent: list[list[str]] = []
|
|
140
|
+
for i, item in enumerate(doc["mappings"], 1):
|
|
141
|
+
if not isinstance(item, dict):
|
|
142
|
+
raise ConfigError(_("Mapping #{0} is not an object.").format(i))
|
|
143
|
+
try:
|
|
144
|
+
m = MappingConfig.from_dict(item)
|
|
145
|
+
# TLS files of a data directory that moved are this one's (tls folder) before an
|
|
146
|
+
# edit's rules ask whether they exist
|
|
147
|
+
moved = AppConfig(mappings=[m]).find_moved_tls_files()
|
|
148
|
+
m.validate_input()
|
|
149
|
+
except (TypeError, ValueError) as e: # ConfigError is a ValueError
|
|
150
|
+
raise ConfigError(_("Mapping #{0} ({1}): {2}").format(i, item.get('name', '?'), e)) from None
|
|
151
|
+
if moved:
|
|
152
|
+
warnings.append(_("Mapping #{0} ({1}): its TLS files are not where the file says; "
|
|
153
|
+
"the files of that name in this data directory's tls folder are "
|
|
154
|
+
"used.").format(i, m.name))
|
|
155
|
+
warnings.extend(_tls_warning(i, m))
|
|
156
|
+
try: # files of another machine: the mapping is taken, its MQTT stays off
|
|
157
|
+
m.check_mqtt_tls_files()
|
|
158
|
+
except ConfigError as e:
|
|
159
|
+
warnings.append(_("Mapping #{0} ({1}): {2} It runs without MQTT until that is "
|
|
160
|
+
"fixed.").format(i, m.name, e))
|
|
161
|
+
warnings.extend(_("Mapping #{0} ({1}): {2}").format(i, m.name, w)
|
|
162
|
+
for w in m.input_warnings() + m.ignored_settings())
|
|
163
|
+
if item.get("id") and item["id"] != m.id:
|
|
164
|
+
warnings.append(_("Mapping #{0} ({1}): {2} is not a valid mapping id (1-64 letters, "
|
|
165
|
+
"digits or _), so it gets a new one.").format(
|
|
166
|
+
i, m.name, repr(item["id"])[:80]))
|
|
167
|
+
absent.append(absent_settings(item))
|
|
168
|
+
if absent[-1]:
|
|
169
|
+
names = list(dict.fromkeys(re.sub(r"\[\d+\]", "[]", p) for p in absent[-1]))
|
|
170
|
+
warnings.append(_("Mapping #{0} ({1}): the file has no {2} (an export of an older "
|
|
171
|
+
"version?). Merged into a mapping of the same name, they keep "
|
|
172
|
+
"their current values; otherwise they take the defaults.").format(
|
|
173
|
+
i, m.name, ", ".join(names[:8]) + (" …" if len(names) > 8 else "")))
|
|
174
|
+
mappings.append(m)
|
|
175
|
+
whole_config = "users" in doc or "admin_ui" in doc
|
|
176
|
+
source = _("ser2netweb config.json") if whole_config else _("ser2netweb export")
|
|
177
|
+
if whole_config:
|
|
178
|
+
warnings.append(_("Only the mappings are imported from a config.json; users, "
|
|
179
|
+
"passwords and settings stay as they are."))
|
|
180
|
+
return ImportPlan(source=source, mappings=mappings, warnings=warnings, absent=absent)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
_FULL_MAPPING = MappingConfig().to_dict()
|
|
184
|
+
_FULL_POINT = dataclasses.asdict(ModbusPoint())
|
|
185
|
+
_POINT = re.compile(r"modbus_poll\.points\[(\d+)\]")
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def absent_settings(item: dict, full: dict = _FULL_MAPPING, path: str = "") -> list[str]:
|
|
189
|
+
"""The settings (paths like "options.trace_max_mb", "modbus_poll.points[2].writable")
|
|
190
|
+
a mapping of an import file doesn't have, e.g. because an older version wrote it."""
|
|
191
|
+
out = []
|
|
192
|
+
for key, default in full.items():
|
|
193
|
+
if key == "id":
|
|
194
|
+
continue
|
|
195
|
+
if not isinstance(item, dict) or key not in item:
|
|
196
|
+
out.append(path + key)
|
|
197
|
+
elif key == "points" and isinstance(item[key], list):
|
|
198
|
+
for i, point in enumerate(item[key]):
|
|
199
|
+
if isinstance(point, dict):
|
|
200
|
+
out += [f"{path}points[{i}].{k}" for k in _FULL_POINT if k not in point]
|
|
201
|
+
elif isinstance(default, dict) and key != "match": # a section (match is a value)
|
|
202
|
+
out += absent_settings(item[key], default, f"{path}{key}.")
|
|
203
|
+
return out
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _keep_absent(m: MappingConfig, target: MappingConfig, absent: list[str]) -> MappingConfig:
|
|
207
|
+
"""*m* (merged into *target*) with target's values for the settings the file didn't
|
|
208
|
+
have; a Modbus point's by its name ("writable" only while it is a coil or holding
|
|
209
|
+
register)."""
|
|
210
|
+
if not absent:
|
|
211
|
+
return m
|
|
212
|
+
d, old = m.to_dict(), target.to_dict()
|
|
213
|
+
old_points = {p["name"]: p for p in old["modbus_poll"]["points"]}
|
|
214
|
+
for path in absent:
|
|
215
|
+
head, _dot, key = path.rpartition(".")
|
|
216
|
+
if pm := _POINT.fullmatch(head):
|
|
217
|
+
points, n = d["modbus_poll"]["points"], int(pm.group(1))
|
|
218
|
+
if n < len(points) and (stored := old_points.get(points[n]["name"])) is not None \
|
|
219
|
+
and (key != "writable" or points[n]["fn"] in (1, 3)):
|
|
220
|
+
points[n][key] = copy.deepcopy(stored[key])
|
|
221
|
+
continue
|
|
222
|
+
src, dst = old, d
|
|
223
|
+
for part in head.split(".") if head else ():
|
|
224
|
+
src, dst = src[part], dst[part]
|
|
225
|
+
dst[key] = copy.deepcopy(src[key])
|
|
226
|
+
return MappingConfig.from_dict(d)
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def _classic_ser2net(text: str, filename: str) -> ImportPlan:
|
|
230
|
+
"""A configuration file of the classic C ser2net, converted (ser2netweb/ser2net_import).
|
|
231
|
+
Nothing importable is an error, so a replace import cannot empty the mappings."""
|
|
232
|
+
dicts, warnings = parse_ser2net_config(text, filename)
|
|
233
|
+
if not dicts:
|
|
234
|
+
raise ConfigError(" ".join(warnings) or _("The file has no ser2net connections to import."))
|
|
235
|
+
source = _("ser2net.yaml (ser2net 4.x)") if looks_yaml(text) else _("ser2net.conf (ser2net 3.x)")
|
|
236
|
+
mappings = [MappingConfig.from_dict(d) for d in dicts]
|
|
237
|
+
for i, m in enumerate(mappings, 1):
|
|
238
|
+
m.validate_input() # the converter skips URL devices already; this backs it up
|
|
239
|
+
for w in _tls_warning(i, m):
|
|
240
|
+
note = Note(w)
|
|
241
|
+
note.mapping = i - 1 # (shown in its row of the preview)
|
|
242
|
+
warnings.append(note)
|
|
243
|
+
return ImportPlan(source=source, mappings=mappings, warnings=warnings, classic=True)
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def _tls_warning(i: int, m: MappingConfig) -> list[str]:
|
|
247
|
+
"""A TLS mapping whose certificate and key don't load here (a key that needs its
|
|
248
|
+
password, files of another machine) is imported all the same, with a warning: it can't
|
|
249
|
+
start until that is fixed, and never runs without TLS."""
|
|
250
|
+
try:
|
|
251
|
+
m.check_tls_files()
|
|
252
|
+
except ConfigError as e:
|
|
253
|
+
return [_("Mapping #{0} ({1}): {2} It can't start until that is fixed.").format(
|
|
254
|
+
i, m.name, e)]
|
|
255
|
+
return []
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def _match(existing: list[MappingConfig], m: MappingConfig):
|
|
259
|
+
return (next((e for e in existing if e.id == m.id), None)
|
|
260
|
+
or next((e for e in existing if e.name == m.name), None))
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def _bind_reach(ip: str) -> int:
|
|
264
|
+
"""How far a bind IP reaches: 0 the loopback, 1 one address, 2 every interface."""
|
|
265
|
+
try:
|
|
266
|
+
a = ipaddress.ip_address(ip)
|
|
267
|
+
except ValueError:
|
|
268
|
+
return 1
|
|
269
|
+
return 0 if a.is_loopback else 2 if a.is_unspecified else 1
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def _reach(net) -> int:
|
|
273
|
+
"""How far a listener (NetworkSettings) reaches: _bind_reach, and 3 for every
|
|
274
|
+
interface of both families (dual_stack on 0.0.0.0 / ::)."""
|
|
275
|
+
return 3 if net.both_families else _bind_reach(net.bind_ip)
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def _within(inner: list[str], outer: list[str]) -> bool:
|
|
279
|
+
"""The clients `inner` allows are all allowed by `outer` too (an empty list: any)."""
|
|
280
|
+
if not outer:
|
|
281
|
+
return True
|
|
282
|
+
if not inner:
|
|
283
|
+
return False
|
|
284
|
+
try:
|
|
285
|
+
nets_in, nets_out = ([ipaddress.ip_network(normalize_cidr(x), strict=False) for x in xs]
|
|
286
|
+
for xs in (inner, outer))
|
|
287
|
+
except ValueError:
|
|
288
|
+
return sorted(inner) == sorted(outer)
|
|
289
|
+
return all(any(n.version == w.version and n.subnet_of(w) for w in nets_out) # type: ignore[arg-type]
|
|
290
|
+
for n in nets_in)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _overlay(old: MappingConfig, new: MappingConfig) -> MappingConfig:
|
|
294
|
+
"""`new`, from a classic ser2net file, merged into `old`, the mapping it updates. The
|
|
295
|
+
file says only part of what a mapping has here (what ser2net_import writes), so only
|
|
296
|
+
that is taken from it, and never so that the mapping gets more open: a disabled
|
|
297
|
+
mapping stays disabled, the bind IP (with the families it takes, dual_stack), the
|
|
298
|
+
allowed clients and read-only are not widened, TLS is not turned off and a TLS client
|
|
299
|
+
CA is not dropped, a Modbus gateway stays one. What the file leaves at ser2netweb's
|
|
300
|
+
default (no banner, no timeout, ...) keeps the mapping's own value, the port locking
|
|
301
|
+
(flock / uucplock) too; the serial framing is always the file's (ser2netweb ran with it,
|
|
302
|
+
9600N81 by default)."""
|
|
303
|
+
r = MappingConfig.from_dict(old.to_dict())
|
|
304
|
+
plain = MappingConfig()
|
|
305
|
+
|
|
306
|
+
def given(dst, src, default, *attrs): # the values the file sets (not the default)
|
|
307
|
+
for a in attrs:
|
|
308
|
+
if getattr(src, a) != getattr(default, a):
|
|
309
|
+
setattr(dst, a, getattr(src, a))
|
|
310
|
+
r.name, r.kind = new.name, new.kind
|
|
311
|
+
r.enabled = old.enabled and new.enabled
|
|
312
|
+
s, ns = r.serial, new.serial
|
|
313
|
+
s.port, s.baudrate, s.bytesize, s.parity, s.stopbits, s.flowcontrol = (
|
|
314
|
+
ns.port, ns.baudrate, ns.bytesize, ns.parity, ns.stopbits, ns.flowcontrol)
|
|
315
|
+
given(s, ns, plain.serial, "rts_on_open", "dtr_on_open", "exclusive")
|
|
316
|
+
given(s.advanced, ns.advanced, plain.serial.advanced, "hangup_when_done", "nobreak",
|
|
317
|
+
"tiocexcl", "respect_uucp_locks")
|
|
318
|
+
n, nn = r.network, new.network
|
|
319
|
+
n.mode, n.port = nn.mode, nn.port
|
|
320
|
+
if old.network.protocol != "modbus" or nn.mode != "server": # (a gateway is a TCP server)
|
|
321
|
+
n.protocol = nn.protocol
|
|
322
|
+
if _reach(nn) <= _reach(n):
|
|
323
|
+
n.bind_ip, n.dual_stack = nn.bind_ip, nn.dual_stack
|
|
324
|
+
if nn.allowed_client_ips and _within(nn.allowed_client_ips, n.allowed_client_ips):
|
|
325
|
+
n.allowed_client_ips = list(nn.allowed_client_ips)
|
|
326
|
+
n.read_only = n.read_only or nn.read_only
|
|
327
|
+
if nn.tls:
|
|
328
|
+
n.tls, n.tls_cert, n.tls_key = True, nn.tls_cert, nn.tls_key
|
|
329
|
+
if nn.tls_client_ca: # (clientauth with its CA file here; a CA the mapping has stays)
|
|
330
|
+
n.tls_client_ca = nn.tls_client_ca
|
|
331
|
+
given(n, nn, plain.network, "kick_old_user", "max_connections")
|
|
332
|
+
if n.protocol == "rfc2217":
|
|
333
|
+
n.max_connections = 1 # (RFC 2217 takes a single client here: the file's is 1 too)
|
|
334
|
+
o, no = r.options, new.options
|
|
335
|
+
given(o, no, plain.options, "idle_timeout_s", "banner", "openstr", "closestr", "closeon")
|
|
336
|
+
if no.trace_both:
|
|
337
|
+
o.trace_both, o.trace_hexdump, o.trace_timestamp = (
|
|
338
|
+
no.trace_both, no.trace_hexdump, no.trace_timestamp)
|
|
339
|
+
return r
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def _merged(target: MappingConfig, m: MappingConfig, classic: bool,
|
|
343
|
+
absent: Optional[list[str]] = None) -> MappingConfig:
|
|
344
|
+
"""What `m` makes of the mapping `target` it updates (a copy; `m.id` is not used): a
|
|
345
|
+
classic ser2net file's mapping keeps what such a file can't say (_overlay), any other
|
|
346
|
+
target's values for the settings its file didn't have (`absent`, _keep_absent)."""
|
|
347
|
+
if classic:
|
|
348
|
+
return _overlay(target, m)
|
|
349
|
+
return MappingConfig.from_dict({**_keep_absent(m, target, absent or []).to_dict(),
|
|
350
|
+
"id": target.id})
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def apply_import(current: list[MappingConfig], incoming: list[MappingConfig],
|
|
354
|
+
mode: str, classic: bool = False, absent: list[list[str]] | None = None,
|
|
355
|
+
) -> tuple[list[MappingConfig], list[MappingConfig]]:
|
|
356
|
+
"""(new mapping list, mappings that were added or changed). Pure: the inputs
|
|
357
|
+
are not modified. An update in merge mode keeps what the file doesn't say: `classic`
|
|
358
|
+
(a classic ser2net file) what such a file can't say (_overlay); else `absent`, per
|
|
359
|
+
incoming mapping the settings its file didn't have (ImportPlan.absent), keep their
|
|
360
|
+
current values (_keep_absent)."""
|
|
361
|
+
if mode not in MODES:
|
|
362
|
+
raise ConfigError(_("Import mode must be one of {0}.").format(", ".join(MODES)))
|
|
363
|
+
if mode == "replace":
|
|
364
|
+
seen: set[str] = set()
|
|
365
|
+
out = []
|
|
366
|
+
for m in incoming:
|
|
367
|
+
m = MappingConfig.from_dict(m.to_dict())
|
|
368
|
+
if m.id in seen:
|
|
369
|
+
m.id = _new_id()
|
|
370
|
+
seen.add(m.id)
|
|
371
|
+
out.append(m)
|
|
372
|
+
return out, list(out)
|
|
373
|
+
result = [MappingConfig.from_dict(m.to_dict()) for m in current]
|
|
374
|
+
touched = []
|
|
375
|
+
for i, m in enumerate(incoming):
|
|
376
|
+
m = MappingConfig.from_dict(m.to_dict())
|
|
377
|
+
target = _match(result, m)
|
|
378
|
+
if target is not None:
|
|
379
|
+
m = _merged(target, m, classic, absent[i] if absent and i < len(absent) else [])
|
|
380
|
+
if m.to_dict() == target.to_dict():
|
|
381
|
+
continue # identical: nothing to restart
|
|
382
|
+
result[result.index(target)] = m
|
|
383
|
+
else:
|
|
384
|
+
if any(e.id == m.id for e in result):
|
|
385
|
+
m.id = _new_id()
|
|
386
|
+
result.append(m)
|
|
387
|
+
touched.append(m)
|
|
388
|
+
return result, touched
|
|
389
|
+
|
|
390
|
+
|
|
391
|
+
def mqtt_clash(mappings: list[MappingConfig], touched: list[MappingConfig]) -> Optional[str]:
|
|
392
|
+
"""Why an import that leaves ``mappings`` (adding or changing ``touched``) can't be
|
|
393
|
+
applied over MQTT (see config.check_mqtt_clashes): a mapping it brings shares its MQTT
|
|
394
|
+
client ID, Sparkplug B edge node or a command topic with another enabled mapping on
|
|
395
|
+
the same broker. None when it doesn't."""
|
|
396
|
+
for m in touched:
|
|
397
|
+
try:
|
|
398
|
+
check_mqtt_clashes(m, mappings)
|
|
399
|
+
except ConfigError as e:
|
|
400
|
+
return _("Mapping '{0}': {1}").format(m.name, e)
|
|
401
|
+
return None
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def plan_rows(current: list[MappingConfig], incoming: list[MappingConfig],
|
|
405
|
+
mode: str, classic: bool = False,
|
|
406
|
+
notes: Optional[list[list[str]]] = None,
|
|
407
|
+
absent: list[list[str]] | None = None) -> list[dict]:
|
|
408
|
+
"""Preview rows: {name, kind, action: add|update|same|remove, target, changes, after,
|
|
409
|
+
notes}. For an update, `changes` lists what it changes and what it keeps of the
|
|
410
|
+
mapping (_diff); `after` is how the mapping will be (_after); `notes` are its
|
|
411
|
+
warnings (ImportPlan.split_warnings, in the order of `incoming`), those about its
|
|
412
|
+
protection first. `classic` / `absent`: as for apply_import."""
|
|
413
|
+
rows = []
|
|
414
|
+
for i, m in enumerate(incoming):
|
|
415
|
+
target = _match(current, m) if mode == "merge" else None
|
|
416
|
+
changes: list[dict] = []
|
|
417
|
+
result = m
|
|
418
|
+
if target is None:
|
|
419
|
+
action = "add"
|
|
420
|
+
else:
|
|
421
|
+
result = _merged(target, m, classic, absent[i] if absent and i < len(absent) else [])
|
|
422
|
+
action = "same" if result.to_dict() == target.to_dict() else "update"
|
|
423
|
+
changes = _diff(target, m, result)
|
|
424
|
+
own = [{"text": getattr(n, "detail", "") or n, "security": getattr(n, "security", False)}
|
|
425
|
+
for n in (notes[i] if notes and i < len(notes) else [])]
|
|
426
|
+
rows.append({"name": m.name, "kind": _kind(m), "action": action,
|
|
427
|
+
"target": target.name if target is not None else "", "changes": changes,
|
|
428
|
+
"after": _after(result),
|
|
429
|
+
"notes": sorted(own, key=lambda n: not n["security"])})
|
|
430
|
+
if mode == "replace":
|
|
431
|
+
for e in current:
|
|
432
|
+
rows.append({"name": e.name, "kind": _kind(e), "action": "remove", "target": "",
|
|
433
|
+
"changes": [], "after": None, "notes": []})
|
|
434
|
+
return rows
|
|
435
|
+
|
|
436
|
+
|
|
437
|
+
def _after(m: MappingConfig) -> dict:
|
|
438
|
+
"""How a mapping will be after the import, for the preview (as the dashboard tags it):
|
|
439
|
+
enabled, TLS, read-only, `clients` (entries of its allow-list; None: it doesn't
|
|
440
|
+
listen) and `open` (enabled and taking any client beyond the loopback)."""
|
|
441
|
+
n = m.network
|
|
442
|
+
listens = m.kind == "net" and n.mode != "client"
|
|
443
|
+
return {"enabled": m.enabled, "tls": listens and n.tls, "read_only": n.read_only,
|
|
444
|
+
"clients": len(n.allowed_client_ips) if listens else None,
|
|
445
|
+
"open": listens and m.enabled and not n.allowed_client_ips
|
|
446
|
+
and _reach(n) > 0}
|
|
447
|
+
|
|
448
|
+
|
|
449
|
+
_CONTROL = re.compile(r"[\x00-\x1f\x7f\u2028\u2029]")
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
def log_lines(plan: ImportPlan) -> list[str]:
|
|
453
|
+
"""The import's warnings for all.log, in English, one line each: a line break or other
|
|
454
|
+
control character from the file is written as its escape (it would start a log line
|
|
455
|
+
of its own)."""
|
|
456
|
+
warnings = plan.log_warnings if plan.log_source else plan.warnings
|
|
457
|
+
return [_CONTROL.sub(lambda m: m.group().encode("unicode_escape").decode(), w)
|
|
458
|
+
for w in warnings]
|
|
459
|
+
|
|
460
|
+
|
|
461
|
+
def audit_detail(plan: ImportPlan, most: int = 500) -> str:
|
|
462
|
+
"""The audit record of an import: how many mappings from what, and its warnings (in
|
|
463
|
+
English), cut to `most` characters."""
|
|
464
|
+
source, warnings = ((plan.log_source, plan.log_warnings) if plan.log_source else
|
|
465
|
+
(plan.source, plan.warnings))
|
|
466
|
+
text = f"{len(plan.mappings)} mappings ({source})"
|
|
467
|
+
if warnings:
|
|
468
|
+
text += f"; {len(warnings)} warnings: " + "; ".join(warnings)
|
|
469
|
+
return text if len(text) <= most else text[:most - 1] + "…"
|
|
470
|
+
|
|
471
|
+
|
|
472
|
+
def _shown(value: str, most: int = 60) -> str:
|
|
473
|
+
"""A string option in the preview: control characters escaped, cut at `most`, — for
|
|
474
|
+
none."""
|
|
475
|
+
v = value.encode("unicode_escape").decode("ascii") if not value.isprintable() else value
|
|
476
|
+
return "—" if not v else v if len(v) <= most else v[:most - 1] + "…"
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
def _fields(m: MappingConfig) -> list[tuple[str, str]]:
|
|
480
|
+
"""What the preview compares of a mapping: (label, value as shown), in the order of
|
|
481
|
+
the mapping form."""
|
|
482
|
+
s, n, o = m.serial, m.network, m.options
|
|
483
|
+
on, off = _("on"), _("off")
|
|
484
|
+
framing = s.compact() + (f" · {s.flowcontrol}" if s.flowcontrol != "none" else "")
|
|
485
|
+
return [
|
|
486
|
+
(_("State"), _("enabled") if m.enabled else _("disabled")),
|
|
487
|
+
(_("Serial port"), s.port),
|
|
488
|
+
(_("Serial"), framing),
|
|
489
|
+
(_("RTS on open"), s.rts_on_open),
|
|
490
|
+
(_("DTR on open"), s.dtr_on_open),
|
|
491
|
+
(_("Protocol"), f"{n.mode}/{n.protocol}"),
|
|
492
|
+
(_("Bind IP"), _("All interfaces (IPv4 + IPv6)") if n.both_families else n.bind_ip),
|
|
493
|
+
(_("Listen port"), str(n.port)),
|
|
494
|
+
("TLS", on if n.tls else off),
|
|
495
|
+
(_("Allowed client IPs / CIDRs"), " ".join(n.allowed_client_ips) or _("any client")),
|
|
496
|
+
(_("Read-only"), on if n.read_only else off),
|
|
497
|
+
(_("Max connections"), str(n.max_connections)),
|
|
498
|
+
(_("Kick old client"), on if n.kick_old_user else off),
|
|
499
|
+
(_("Idle timeout (s)"), str(o.idle_timeout_s)),
|
|
500
|
+
(_("Connect banner"), _shown(o.banner)),
|
|
501
|
+
("openstr", _shown(o.openstr)),
|
|
502
|
+
("closestr", _shown(o.closestr)),
|
|
503
|
+
(_("Close-on string"), _shown(o.closeon)),
|
|
504
|
+
(_("Trace file name"), _shown(o.trace_both)),
|
|
505
|
+
]
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
def _looser(old: MappingConfig, new: MappingConfig) -> set[str]:
|
|
509
|
+
"""The fields (labels of _fields) in which `new` is more open than `old`: started,
|
|
510
|
+
TLS off, a wider bind IP or allow-list, writable."""
|
|
511
|
+
a, b = old.network, new.network
|
|
512
|
+
out = set()
|
|
513
|
+
if new.enabled and not old.enabled:
|
|
514
|
+
out.add(_("State"))
|
|
515
|
+
if a.tls and not b.tls:
|
|
516
|
+
out.add("TLS")
|
|
517
|
+
if _reach(b) > _reach(a):
|
|
518
|
+
out.add(_("Bind IP"))
|
|
519
|
+
if not _within(b.allowed_client_ips, a.allowed_client_ips):
|
|
520
|
+
out.add(_("Allowed client IPs / CIDRs"))
|
|
521
|
+
if a.read_only and not b.read_only:
|
|
522
|
+
out.add(_("Read-only"))
|
|
523
|
+
return out
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
def _diff(old: MappingConfig, file: MappingConfig, result: MappingConfig) -> list[dict]:
|
|
527
|
+
"""What an update does to the mapping `old`: each field it changes ({what, before,
|
|
528
|
+
after}) and, for a classic file, each one the file has otherwise that the mapping
|
|
529
|
+
keeps ({what, before, file, kept: True}). `security`: the change opens the mapping
|
|
530
|
+
up, or the file would have."""
|
|
531
|
+
before, given, after = _fields(old), _fields(file), _fields(result)
|
|
532
|
+
looser, would = _looser(old, result), _looser(old, file)
|
|
533
|
+
out = []
|
|
534
|
+
for (what, b), (_l, f), (_m, a) in zip(before, given, after, strict=True):
|
|
535
|
+
if b != a:
|
|
536
|
+
out.append({"what": what, "before": b, "after": a, "kept": False,
|
|
537
|
+
"security": what in looser})
|
|
538
|
+
elif f != a:
|
|
539
|
+
out.append({"what": what, "before": b, "file": f, "kept": True,
|
|
540
|
+
"security": what in would})
|
|
541
|
+
return out
|
|
542
|
+
|
|
543
|
+
|
|
544
|
+
def _kind(m: MappingConfig) -> str:
|
|
545
|
+
if m.kind == "serialbridge":
|
|
546
|
+
return f"{m.serial.port} ↔ {m.serial_b.port}"
|
|
547
|
+
net = m.network
|
|
548
|
+
where = (f"→ {host_port(net.remote_host, net.remote_port)}" if net.mode == "client"
|
|
549
|
+
else f"{net.bind_shown}:{net.port}")
|
|
550
|
+
return f"{m.serial.port} · {net.mode}/{net.protocol} {where}"
|
ser2netweb/layout.py
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""How this copy of ser2netweb is installed, and where it keeps its data by default.
|
|
2
|
+
|
|
3
|
+
source a source checkout (ser2netweb.py, bootstrap.py and ./lib beside the package),
|
|
4
|
+
also the Docker image's /app: data/ in the checkout
|
|
5
|
+
standalone a standalone executable (PyInstaller): data/ next to the executable
|
|
6
|
+
package that executable as the .deb / .rpm package installs it, /usr/bin/ser2netweb:
|
|
7
|
+
/var/lib/ser2netweb, the data directory of the package's service
|
|
8
|
+
pip installed by pip or pipx (the wheel from PyPI: the package in a site-packages
|
|
9
|
+
folder, or wherever --target put it next to its .dist-info): the platform's
|
|
10
|
+
folder for a user's application data, never next to the package, which pip
|
|
11
|
+
owns (and may replace or delete on the next upgrade)
|
|
12
|
+
|
|
13
|
+
--data-dir and --config choose another folder in every case. A pip install gets its
|
|
14
|
+
dependencies from pip, so the offline bootstrap into ./lib (bootstrap.py) is not used there.
|
|
15
|
+
Standard library only (the command line reads this before the dependencies load).
|
|
16
|
+
"""
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import functools
|
|
20
|
+
import ntpath
|
|
21
|
+
import os
|
|
22
|
+
import posixpath
|
|
23
|
+
import sys
|
|
24
|
+
from collections.abc import Mapping
|
|
25
|
+
from typing import Optional
|
|
26
|
+
|
|
27
|
+
NAME = "ser2netweb"
|
|
28
|
+
SOURCE, STANDALONE, PACKAGE, PIP = "source", "standalone", "package", "pip"
|
|
29
|
+
# --about's "Build:" line
|
|
30
|
+
LABELS = {SOURCE: "source", STANDALONE: "standalone executable",
|
|
31
|
+
PACKAGE: "standalone executable, .deb / .rpm package",
|
|
32
|
+
PIP: "Python package (pip / pipx)"}
|
|
33
|
+
# where the .deb / .rpm package puts the executable, and its service's data directory
|
|
34
|
+
# (packaging/nfpm.yaml; ser2netweb-install.sh and the standalone unit use /usr/local/bin)
|
|
35
|
+
PACKAGE_EXECUTABLE = "/usr/bin/ser2netweb"
|
|
36
|
+
PACKAGE_DATA_DIR = "/var/lib/ser2netweb"
|
|
37
|
+
PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__)) # this package's folder
|
|
38
|
+
_SITE_FOLDERS = ("site-packages", "dist-packages") # (dist-packages: Debian's Python)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _dist_infos(folder: str) -> list[str]:
|
|
42
|
+
"""The ser2netweb-*.dist-info folders an installer left in `folder`."""
|
|
43
|
+
try:
|
|
44
|
+
names = os.listdir(folder)
|
|
45
|
+
except OSError:
|
|
46
|
+
return []
|
|
47
|
+
return sorted(n for n in names
|
|
48
|
+
if n.lower().startswith(NAME + "-") and n.lower().endswith(".dist-info"))
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def detect(frozen: bool, executable: str, package_dir: str,
|
|
52
|
+
platform: str = sys.platform) -> str:
|
|
53
|
+
"""The kind of installation (SOURCE, STANDALONE, PACKAGE or PIP) of a copy whose package
|
|
54
|
+
is `package_dir`, run by `executable`."""
|
|
55
|
+
if frozen:
|
|
56
|
+
# (a Linux path, compared as one whatever OS this runs on; a frozen executable's
|
|
57
|
+
# sys.executable is absolute)
|
|
58
|
+
if platform.startswith("linux") and posixpath.normpath(executable) == PACKAGE_EXECUTABLE:
|
|
59
|
+
return PACKAGE
|
|
60
|
+
return STANDALONE
|
|
61
|
+
parent = os.path.dirname(os.path.abspath(package_dir))
|
|
62
|
+
if os.path.basename(parent).lower() in _SITE_FOLDERS or _dist_infos(parent):
|
|
63
|
+
return PIP
|
|
64
|
+
# a source checkout (an editable install `pip install -e .` too: the package stays in
|
|
65
|
+
# the checkout, so its data does as well)
|
|
66
|
+
return SOURCE
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@functools.cache
|
|
70
|
+
def kind() -> str:
|
|
71
|
+
"""The kind of this installation (detect() for the running copy; found once)."""
|
|
72
|
+
return detect(bool(getattr(sys, "frozen", False)), sys.executable, PACKAGE_DIR)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def user_data_dir(platform: str = sys.platform, environ: Optional[Mapping[str, str]] = None,
|
|
76
|
+
home: Optional[str] = None) -> str:
|
|
77
|
+
"""A user's folder for ser2netweb's data: %LOCALAPPDATA%\\ser2netweb on Windows,
|
|
78
|
+
~/Library/Application Support/ser2netweb on macOS, $XDG_DATA_HOME/ser2netweb (or
|
|
79
|
+
~/.local/share/ser2netweb) elsewhere, as the XDG base directory spec has it: a
|
|
80
|
+
relative XDG_DATA_HOME is ignored."""
|
|
81
|
+
env = os.environ if environ is None else environ
|
|
82
|
+
path = ntpath if platform == "win32" else posixpath
|
|
83
|
+
if home is None:
|
|
84
|
+
home = os.path.expanduser("~")
|
|
85
|
+
if platform == "win32":
|
|
86
|
+
base = env.get("LOCALAPPDATA", "")
|
|
87
|
+
if not path.isabs(base):
|
|
88
|
+
base = path.join(home, "AppData", "Local")
|
|
89
|
+
elif platform == "darwin":
|
|
90
|
+
base = path.join(home, "Library", "Application Support")
|
|
91
|
+
else:
|
|
92
|
+
base = env.get("XDG_DATA_HOME", "")
|
|
93
|
+
if not path.isabs(base):
|
|
94
|
+
base = path.join(home, ".local", "share")
|
|
95
|
+
return path.join(base, NAME)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def default_data_dir(app_dir: str, kind_: Optional[str] = None) -> str:
|
|
99
|
+
"""The data directory without --data-dir / --config: data/ in `app_dir` (a source
|
|
100
|
+
checkout, or the folder of a standalone executable), the package's service's data
|
|
101
|
+
directory, or a pip install's user data folder."""
|
|
102
|
+
k = kind() if kind_ is None else kind_
|
|
103
|
+
if k == PIP:
|
|
104
|
+
return user_data_dir()
|
|
105
|
+
if k == PACKAGE:
|
|
106
|
+
return PACKAGE_DATA_DIR
|
|
107
|
+
return os.path.join(app_dir, "data")
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def licence_dir(package_dir: str = PACKAGE_DIR) -> Optional[str]:
|
|
111
|
+
"""A pip install's licence texts (LICENSE, NOTICE, ...: the wheel's license-files,
|
|
112
|
+
which an installer puts in <name>.dist-info/licenses next to the package), else None."""
|
|
113
|
+
parent = os.path.dirname(os.path.abspath(package_dir))
|
|
114
|
+
for name in _dist_infos(parent):
|
|
115
|
+
folder = os.path.join(parent, name, "licenses")
|
|
116
|
+
if os.path.isdir(folder):
|
|
117
|
+
return folder
|
|
118
|
+
return None
|