andon-client 1.0.0__py3-none-any.whl

andon_client/__init__.py

@@ -0,0 +1,25 @@
+"""
+andon-client: send values from Python to the Andon app for iPhone and iPad.
+
+What is exported here is the public API, covered by semantic versioning;
+everything in the modules whose names start with an underscore is internal.
+"""
+
+from ._relay import PutResult
+from ._runtime import ReceiveResult, UploadReport, ValidationError
+from ._tiles import InputError
+from ._validate import Issue, Validation, validate
+from ._view import AndonView, UploadFailure
+
+__all__ = [
+    'AndonView',
+    'InputError',
+    'Issue',
+    'PutResult',
+    'ReceiveResult',
+    'UploadFailure',
+    'UploadReport',
+    'Validation',
+    'ValidationError',
+    'validate',
+]

andon_client/_accepts.py

@@ -0,0 +1,222 @@
+"""
+What a tile takes, read off the tile itself: its kind, whether it has
+categories, how many series or lanes it has, and which form its first series
+uses - a series in the step form (start, stepSec, points) takes no single number,
+because there is no timestamp to append it at.
+
+The hint a refused value gets, the same sentence as in the TypeScript package.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any, Dict, List, Mapping, NamedTuple, Optional
+
+from ._js import is_number, iso
+from ._words import API_WORDS, Words
+
+
+class Form(NamedTuple):
+    key: str
+    """names the wording"""
+    params: Dict[str, Any]
+    """what the wording needs (count, states)"""
+    example: Any
+    """a value to show"""
+    extra: Dict[str, Any]
+    """further parts of the update the form needs, by name: timestamp, series, lane"""
+
+
+def _text(w: Words) -> Dict[str, Dict[str, str]]:
+    return {
+        'text': {'payload': 'a text or a number', 'effect': 'replaces the value'},
+        'number': {'payload': 'a number', 'effect': 'replaces the value'},
+        'append': {'payload': 'a number', 'effect': 'is appended to the series, at the time it arrives'},
+        'appendAt': {'payload': 'a number with ' + w.timestamp, 'effect': 'is appended at that time, in milliseconds or ISO 8601'},
+        'appendTo': {'payload': 'a number with ' + w.series, 'effect': 'is appended to the series of that name'},
+        'pairs': {'payload': 'an array of [timestamp, value] pairs', 'effect': 'replaces the series; ' + w.series + ' picks which'},
+        'samples': {'payload': 'an object {series: [{name, samples}]}', 'effect': 'replaces every series'},
+        'steps': {'payload': 'an object {series: [{name, start, stepSec, points}]}', 'effect': 'replaces every series: a point every stepSec from start, in UTC'},
+        'values': {'payload': 'an array of numbers, one per category', 'effect': 'replaces the values; categories: __count__'},
+        'valuesTo': {'payload': 'an array of numbers with ' + w.series, 'effect': 'replaces the values of the series of that name'},
+        'categories': {'payload': 'an object {categories, series}', 'effect': 'replaces the categories and their values together'},
+        'statuses': {'payload': 'an object {series: [{name, values, statuses}]}', 'effect': 'a verdict per bar: ok, warning, critical or null'},
+        'rows': {'payload': 'an array of rows, each an array of cells', 'effect': 'replaces the rows; columns: __count__'},
+        'rowStatus': {'payload': 'an array of {cells, status}', 'effect': 'replaces the rows, with a status per row'},
+        'state': {'payload': 'a state ID (__states__)', 'effect': 'starts a new segment, at the time it arrives'},
+        'stateAt': {'payload': 'a state ID with ' + w.timestamp, 'effect': 'starts the segment at that time'},
+        'stateLane': {'payload': 'a state ID with ' + w.lane, 'effect': 'starts a segment in the lane of that name'},
+        'window': {'payload': 'an object {from, to}', 'effect': 'moves the time axis; what lies before from is trimmed'},
+        'fields': {'payload': 'an object of fields, e.g. {"status": "warning"}', 'effect': 'sets them; null removes one'},
+    }
+
+
+# The forms an error message names: what a value alone can be. Objects and forms
+# that need a further part of the update are left to the documentation.
+_IN_HINT = {'text', 'number', 'append', 'pairs', 'values', 'rows', 'state'}
+
+_MINUTE = 60 * 1000
+_HOUR = 60 * _MINUTE
+
+
+def _form(key: str, example: Any, params: Optional[Dict[str, Any]] = None, extra: Optional[Dict[str, Any]] = None) -> Form:
+    return Form(key, params or {}, example, extra or {})
+
+
+def _number_of(tile: Mapping[str, Any], fallback: float) -> Any:
+    return tile.get('value') if is_number(tile.get('value')) else fallback
+
+
+def _series_of(tile: Mapping[str, Any]) -> List[Any]:
+    series = tile.get('series')
+    return [s for s in series if isinstance(s, dict) and isinstance(s.get('name'), str)] if isinstance(series, list) else []
+
+
+def _values_of(series: Mapping[str, Any], fallback: Any) -> List[Any]:
+    """The last few values a series holds, whatever its form: what the examples are made of."""
+    v: List[Any] = []
+    if isinstance(series.get('samples'), list):
+        v = [p[1] if isinstance(p, list) and len(p) > 1 else None for p in series['samples']]
+    elif isinstance(series.get('points'), list):
+        v = series['points']
+    v = [x for x in v if is_number(x)][-4:]
+    return v if v else [fallback, fallback + 1, fallback - 1]
+
+
+def _pairs_of(values: List[Any], now: float) -> List[Any]:
+    """[timestamp, value] pairs one minute apart, the last one now."""
+    n = len(values) - 1
+    return [[iso(now - (n - i) * _MINUTE), v] for i, v in enumerate(values)]
+
+
+def _time_series_forms(tile: Mapping[str, Any], now: float) -> List[Form]:
+    every = _series_of(tile)
+    if not every:
+        return []
+    vals = [_values_of(s, _number_of(tile, 42)) for s in every]
+    last = vals[0][-1]
+    out: List[Form] = []
+    if not isinstance(every[0].get('points'), list):
+        out += [_form('append', last), _form('appendAt', last, {}, {'timestamp': {'example': iso(now)}})]
+        if len(every) > 1:
+            out.append(_form('appendTo', vals[1][-1], {}, {'series': {'example': every[1]['name']}}))
+
+    def step(s: Mapping[str, Any]) -> Any:
+        return s['stepSec'] if is_number(s.get('stepSec')) and s['stepSec'] > 0 else 3600
+
+    out += [
+        _form('pairs', _pairs_of(vals[0], now)),
+        _form('samples', {'series': [{'name': s['name'], 'samples': _pairs_of(vals[k], now)} for k, s in enumerate(every)]}),
+        # The step form with its last point at now.
+        _form('steps', {'series': [{'name': s['name'], 'start': iso(now - (len(vals[k]) - 1) * step(s) * 1000),
+                                    'stepSec': step(s), 'points': vals[k]} for k, s in enumerate(every)]}),
+    ]
+    return out
+
+
+def _category_forms(tile: Mapping[str, Any], kind: str) -> List[Form]:
+    count = len(tile['categories'])
+    every = _series_of(tile)
+
+    def values_for(s: Optional[Mapping[str, Any]]) -> List[Any]:
+        if s and isinstance(s.get('values'), list) and len(s['values']) == count:
+            return s['values']
+        return [i + 1 for i in range(count)]
+
+    out = [_form('values', values_for(every[0] if every else None), {'count': count})]
+    if len(every) > 1:
+        out.append(_form('valuesTo', values_for(every[1]), {}, {'series': {'example': every[1]['name']}}))
+    out.append(_form('categories', {
+        'categories': tile['categories'],
+        'series': [{'name': s['name'], 'values': values_for(s)} for s in (every or [{'name': 'A'}])],
+    }))
+    # A verdict per bar exists only on a bar with categories and exactly one series.
+    if kind == 'bar' and len(every) <= 1:
+        v = values_for(every[0] if every else None)
+        out.append(_form('statuses', {'series': [{'name': every[0]['name'] if every else 'A', 'values': v,
+                                                  'statuses': ['critical' if i == len(v) - 1 else None for i in range(len(v))]}]}))
+    return out
+
+
+def _table_forms(tile: Mapping[str, Any]) -> List[Form]:
+    columns = len(tile['columns']) if isinstance(tile.get('columns'), list) and tile['columns'] else 1
+    rows = tile.get('rows')
+    first = rows[0].get('cells') if isinstance(rows, list) and rows and isinstance(rows[0], dict) else None
+    row = first if isinstance(first, list) and len(first) == columns else ['A' if i == 0 else i for i in range(columns)]
+    return [_form('rows', [row], {'count': columns}), _form('rowStatus', [{'cells': row, 'status': 'warning'}])]
+
+
+def _timeline_forms(tile: Mapping[str, Any], now: float) -> List[Form]:
+    states = [s.get('id') for s in (tile.get('states') if isinstance(tile.get('states'), list) else [])
+              if isinstance(s, dict) and s.get('id')]
+    if not states:
+        return []
+    lanes = [lane for lane in (tile.get('lanes') if isinstance(tile.get('lanes'), list) else [])
+             if isinstance(lane, dict) and isinstance(lane.get('name'), str)]
+    out = [
+        _form('state', states[0], {'states': ', '.join(str(s) for s in states)}),
+        _form('stateAt', states[0], {}, {'timestamp': {'example': iso(now)}}),
+    ]
+    if len(lanes) > 1:
+        out.append(_form('stateLane', states[0], {}, {'lane': {'example': lanes[1]['name']}}))
+    out.append(_form('window', {'from': iso(now - 8 * _HOUR), 'to': iso(now)}))
+    return out
+
+
+def forms(tile: Any, now: Optional[float] = None) -> List[Form]:
+    """forms returns every form the tile takes, the most common first."""
+    if not isinstance(tile, dict):
+        return []
+    at = now if is_number(now) else time.time() * 1000
+    categories = isinstance(tile.get('categories'), list)
+    kind = tile.get('view')
+    if kind == 'label':
+        value = tile.get('value')
+        out = [_form('text', value if is_number(value) or isinstance(value, str) else 'Running')]
+    elif kind in ('gauge', 'progress'):
+        out = [_form('number', _number_of(tile, 0))]
+    elif kind == 'donut':
+        out = [_form('number', _number_of(tile, 0))] + (_category_forms(tile, 'donut') if categories else [])
+    elif kind == 'pie':
+        out = _category_forms(tile, 'pie') if categories else []
+    elif kind == 'bar':
+        out = _category_forms(tile, 'bar') if categories else _time_series_forms(tile, at)
+    elif kind == 'line':
+        out = _time_series_forms(tile, at)
+    elif kind == 'table':
+        out = _table_forms(tile)
+    elif kind == 'timeline':
+        out = _timeline_forms(tile, at)
+    else:
+        return []
+    if not out:
+        return []
+    out.append(_form('fields', {'status': 'warning'}))
+    return out
+
+
+def _fill(s: str, params: Mapping[str, Any]) -> str:
+    return re.sub(r'__(\w+)__', lambda m: str(params[m.group(1)]) if m.group(1) in params else m.group(0), s)
+
+
+def describe(f: Form, words: Words = API_WORDS) -> str:
+    """describe is the English wording of one form: "a number (replaces the value)"."""
+    t = _text(words)[f.key]
+    return _fill(t['payload'], f.params) + ' (' + _fill(t['effect'], f.params) + ')'
+
+
+def hint(tile: Any, words: Words = API_WORDS) -> str:
+    """
+    hint is one English sentence for an error message: what a value for the tile
+    can be. A refused value is the moment someone needs it. Objects and forms that
+    need a further part of the update are left out.
+    """
+    if not tile:
+        return ''
+    every = [describe(f, words) for f in forms(tile) if f.key in _IN_HINT]
+    if not every:
+        return ''
+    kind = str(tile.get('view')) + (' with categories' if isinstance(tile.get('categories'), list) else '')
+    last = every.pop()
+    return 'A ' + kind + ' takes ' + (', '.join(every) + ' or ' if every else '') + last

andon_client/_env.py

@@ -0,0 +1,73 @@
+"""
+The view's values from the environment: the names the .env from the Andon
+configurator uses, so that file can be handed to a process unedited:
+
+  ANDON_URL  ANDON_VIEW  ANDON_WRITE_SECRET  ANDON_CONTENT_KEY  ANDON_KEY_VERSION
+
+A prefix replaces the leading ANDON_ of each: with ANDON_CLOUD_, the view ID is
+read from ANDON_CLOUD_VIEW. That is what lets several views share one
+environment - one prefix per view.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Dict, Mapping, Optional
+
+from ._js import trim
+
+# Upper case, ending in an underscore, so that ANDON_CLOUD_ + VIEW reads like a
+# variable name.
+PREFIX = re.compile(r'[A-Z][A-Z0-9_]*_')
+
+SUFFIXES = ('URL', 'VIEW', 'WRITE_SECRET', 'CONTENT_KEY', 'KEY_VERSION')
+
+
+def name(prefix: Optional[str], suffix: str) -> str:
+    """
+    name is the variable a suffix is read from. Every message about a missing value
+    has to go through here, otherwise it names a variable nobody set.
+    """
+    return (prefix or 'ANDON_') + suffix
+
+
+def pick(prefix: Optional[str], suffix: str, env: Optional[Mapping[str, str]] = None) -> str:
+    """pick reads one value, trimmed; the empty string counts as unset."""
+    return trim((env if env is not None else os.environ).get(name(prefix, suffix)) or '')
+
+
+def check_prefix(prefix: Optional[str]) -> str:
+    """
+    check_prefix raises on a prefix that is not one. An empty prefix is not an
+    error: it means the default, ANDON_.
+    """
+    if not prefix:
+        return ''
+    if not PREFIX.fullmatch(prefix):
+        raise ValueError('environment prefix "' + prefix + '" has to be upper case and end in an '
+                         'underscore, for example ANDON_ or ANDON_CLOUD_')
+    return prefix
+
+
+def read_file(path: 'os.PathLike[str] | str') -> Dict[str, str]:
+    """
+    read_file reads a .env as the configurator writes it: NAME=value lines, # for a
+    comment, a value in quotes taken without them, a leading `export ` allowed.
+    """
+    out: Dict[str, str] = {}
+    with open(path, encoding='utf-8-sig') as f:
+        for line in f:
+            line = trim(line)
+            if not line or line.startswith('#'):
+                continue
+            if line.startswith('export '):
+                line = trim(line[len('export '):])
+            name, eq, value = line.partition('=')
+            if not eq or not trim(name):
+                continue
+            value = trim(value)
+            if len(value) >= 2 and value[0] in ('"', "'") and value[-1] == value[0]:
+                value = value[1:-1]
+            out[trim(name)] = value
+    return out

andon_client/_js.py

@@ -0,0 +1,191 @@
+"""
+The few places where this package has to behave like JavaScript, because the
+TypeScript package @smartrsolutions/andon-client is its twin: both read the same
+template the same way, refuse the same values with the same words and seal the
+same document. Each helper names the JavaScript it stands in for.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import math
+import re
+from typing import Any
+
+# What String.prototype.trim() removes: JavaScript's white space and line
+# terminators. str.strip() removes a different set (it keeps U+FEFF and takes
+# U+001C to U+001F and U+0085), and MQTT payloads do arrive with a BOM.
+_WS = '\t\n\v\f\r \u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a' \
+      '\u2028\u2029\u202f\u205f\u3000\ufeff'
+WS_CLASS = '[' + re.escape(_WS) + ']'
+
+
+def trim(text: str) -> str:
+    """trim is String.prototype.trim()."""
+    return text.strip(_WS)
+
+
+def is_number(value: Any) -> bool:
+    """is_number is typeof value === 'number': bool is an int in Python, not here."""
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def is_finite_number(value: Any) -> bool:
+    """is_finite_number is typeof value === 'number' && Number.isFinite(value)."""
+    return is_number(value) and math.isfinite(value)
+
+
+def utf16_len(text: str) -> int:
+    """utf16_len is String.prototype.length: UTF-16 code units, not code points."""
+    return len(text.encode('utf-16-le')) // 2
+
+
+def utf16_key(text: str) -> bytes:
+    """utf16_key sorts strings by UTF-16 code unit, as sort() without a function does."""
+    return text.encode('utf-16-be', 'surrogatepass')
+
+
+def number_text(x: Any) -> str:
+    """number_text is String(x) for a number: the shortest digits, in JavaScript's notation."""
+    if isinstance(x, bool):
+        return 'true' if x else 'false'
+    if isinstance(x, int):
+        return str(x)
+    if math.isnan(x):
+        return 'NaN'
+    if math.isinf(x):
+        return 'Infinity' if x > 0 else '-Infinity'
+    if x == 0:
+        return '0'
+    sign = '-' if x < 0 else ''
+    # repr gives the shortest digits that read back as x, as JavaScript does; only
+    # where the point goes and when an exponent is written differ.
+    r = repr(abs(x))
+    mantissa, _, exp = r.partition('e')
+    whole, _, frac = mantissa.partition('.')
+    e = int(exp) if exp else 0
+    digits = (whole + frac).lstrip('0')
+    n = len(whole) + e if whole.strip('0') else e - (len(frac) - len(frac.lstrip('0')))
+    digits = digits.rstrip('0')
+    k = len(digits)
+    if k <= n <= 21:
+        return sign + digits + '0' * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + '.' + digits[n:]
+    if -6 < n <= 0:
+        return sign + '0.' + '0' * (-n) + digits
+    e = n - 1
+    return sign + digits[0] + ('.' + digits[1:] if k > 1 else '') + 'e' + ('+' if e >= 0 else '-') + str(abs(e))
+
+
+def to_string(value: Any) -> str:
+    """to_string is String(value) for what an update can carry."""
+    if value is None:
+        return 'null'
+    if isinstance(value, bool) or is_number(value):
+        return number_text(value)
+    return str(value)
+
+
+def _plain(value: Any) -> Any:
+    """_plain is the value as JSON.stringify sees it, in the types json.dumps writes alike."""
+    if isinstance(value, dict):
+        return {str(k): _plain(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_plain(v) for v in value]
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            return None  # JSON.stringify writes NaN and Infinity as null
+        if value.is_integer() and abs(value) < 1e21:
+            return int(value)  # 81.0 is 81 in JavaScript, and is written so
+        return value
+    if isinstance(value, _dt.datetime):
+        return iso_ms(value)  # what Date.prototype.toJSON writes
+    if isinstance(value, (str, int, bool)) or value is None:
+        return value
+    raise TypeError('a ' + type(value).__name__ + ' cannot be part of a view document')
+
+
+def stringify(value: Any) -> str:
+    """
+    stringify is JSON.stringify(value): no spaces, keys in insertion order, a float
+    with nothing after the point written as an integer, as JavaScript writes it.
+    Floats below 1e-4 or from 1e16 keep Python's notation; both read back the same.
+    """
+    return json.dumps(_plain(value), separators=(',', ':'), ensure_ascii=False, allow_nan=False)
+
+
+def clone(value: Any) -> Any:
+    """clone is JSON.parse(JSON.stringify(value)): tuples become lists, and nothing is shared."""
+    return json.loads(stringify(value))
+
+
+def iso_ms(moment: _dt.datetime) -> str:
+    """iso_ms is Date.prototype.toISOString(); a naive datetime is local time, as datetime.timestamp() takes it."""
+    ms = math.floor(moment.timestamp() * 1000 + 0.5) if moment.tzinfo is None else \
+        round((moment - _EPOCH).total_seconds() * 1000)
+    when = _EPOCH + _dt.timedelta(milliseconds=ms)
+    return _stamp(when) + '.%03dZ' % (when.microsecond // 1000)
+
+
+_EPOCH = _dt.datetime(1970, 1, 1, tzinfo=_dt.timezone.utc)
+
+# Date.parse for the date-time strings ISO 8601 allows and ECMAScript reads: a date
+# alone is UTC, a date and time without an offset local time.
+_ISO = re.compile(
+    r'([+-]\d{6}|\d{4})-(\d\d)-(\d\d)'
+    r'(?:[Tt ](\d\d):(\d\d)(?::(\d\d)(?:[.,](\d+))?)?\s*([Zz]|[+-]\d\d(?::?\d\d)?)?)?')
+
+
+def parse_date(text: Any) -> float:
+    """
+    parse_date is Date.parse(text) for ISO 8601: milliseconds since the epoch, or
+    NaN. JavaScript reads more spellings than that (Date.prototype.toString() among
+    them); this package takes ISO 8601 only, which is what the format asks for.
+    """
+    if not isinstance(text, str):
+        return math.nan
+    m = _ISO.fullmatch(trim(text))
+    if not m:
+        return math.nan
+    year, month, day = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    hour = int(m.group(4) or 0)
+    minute = int(m.group(5) or 0)
+    second = int(m.group(6) or 0)
+    ms = int((m.group(7) or '0')[:3].ljust(3, '0'))
+    zone = m.group(8)
+    next_day = hour == 24 and minute == 0 and second == 0 and ms == 0
+    if (hour > 23 and not next_day) or minute > 59 or second > 59:
+        return math.nan
+    try:
+        base = _dt.datetime(year, month, day, 0 if next_day else hour, minute, second)
+    except ValueError:
+        return math.nan
+    if next_day:
+        base += _dt.timedelta(days=1)
+    if m.group(4) is None or zone is not None:
+        offset = 0
+        if zone and zone not in 'Zz':
+            sign = -1 if zone[0] == '-' else 1
+            digits = zone[1:].replace(':', '')
+            hours, minutes = int(digits[:2]), int(digits[2:] or 0)
+            if hours > 23 or minutes > 59:
+                return math.nan
+            offset = sign * (hours * 60 + minutes)
+        seconds = (base.replace(tzinfo=_dt.timezone.utc) - _EPOCH).total_seconds() - offset * 60
+        return float(int(seconds) * 1000 + ms)
+    try:
+        return float(int(base.timestamp()) * 1000 + ms)
+    except (OverflowError, OSError, ValueError):
+        return math.nan
+
+
+def iso(ms: float) -> str:
+    """iso renders a timestamp as a view document demands: UTC, whole seconds, trailing Z."""
+    return _stamp(_EPOCH + _dt.timedelta(seconds=math.floor(ms / 1000))) + 'Z'
+
+
+def _stamp(when: _dt.datetime) -> str:
+    # By hand: strftime's %Y does not pad years below 1000 everywhere.
+    return '%04d-%02d-%02dT%02d:%02d:%02d' % (when.year, when.month, when.day, when.hour, when.minute, when.second)

andon_client/_relay.py

@@ -0,0 +1,157 @@
+"""
+The one request this package makes: PUT /v1/views/{id}/envelope.
+
+The write secret travels in the Authorization header and nowhere else; it is
+never part of a URL, a result or an error text. Users talk to relay.andon.app;
+ANDON_RELAY_URL exists for development against a local relay only.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Mapping, NamedTuple, Optional
+
+from ._js import trim
+
+DEFAULT_RELAY = 'https://relay.andon.app'
+TIMEOUT_SEC = 15
+
+THROTTLE_SEC = 10
+"""The relay accepts at most one upload per view per ten seconds (429 otherwise)."""
+
+
+def no_trailing_slash(url: str) -> str:
+    return url.rstrip('/')
+
+
+def relay_url(env: Optional[Mapping[str, str]] = None) -> str:
+    """relay_url is ANDON_RELAY_URL without a trailing slash, or the public relay."""
+    value = no_trailing_slash(trim((env if env is not None else os.environ).get('ANDON_RELAY_URL') or ''))
+    return value or DEFAULT_RELAY
+
+
+def relay_aliases(env: Optional[Mapping[str, str]] = None) -> List[str]:
+    """
+    relay_aliases are the other addresses under which a .env may name this same
+    relay. Development only: in a container a local relay is reachable as
+    host.docker.internal:8080, while the .env names it as 127.0.0.1:8080.
+    ANDON_RELAY_ALIASES is a comma-separated list, empty by default.
+    """
+    text = (env if env is not None else os.environ).get('ANDON_RELAY_ALIASES') or ''
+    return [a for a in (no_trailing_slash(trim(s)) for s in text.split(',')) if a]
+
+
+@dataclass(frozen=True)
+class PutResult:
+    """
+    The answer to one upload:
+
+      ok         204, stored
+      throttled  429, try again after retry_after_sec
+      retry      network error or 5xx, worth trying again later
+      fatal      401, 404, 400, 413: trying again changes nothing until a person does
+    """
+    outcome: str
+    status: int
+    """HTTP status, 0 when the relay was not reached"""
+    code: str = ''
+    """the relay's error code, network when it was not reached"""
+    message: str = ''
+    retry_after_sec: Optional[float] = None
+    """for throttled: when the relay takes the next upload"""
+
+
+class Response(NamedTuple):
+    """What a transport hands back: the status, the body as text, the Retry-After header."""
+    status: int
+    text: str
+    retry_after: Optional[str]
+
+
+Transport = Callable[[str, Dict[str, str], bytes, float], Response]
+"""transport(url, headers, body, timeout_sec) makes the PUT; raises OSError when there is no answer."""
+
+
+def urllib_transport(url: str, headers: Dict[str, str], body: bytes, timeout: float) -> Response:
+    request = urllib.request.Request(url, data=body, headers=headers, method='PUT')
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as res:  # noqa: S310 - the URL is the relay's
+            return Response(res.status, '' if res.status == 204 else _read(res), res.headers.get('retry-after'))
+    except urllib.error.HTTPError as err:
+        return Response(err.code, _read(err), err.headers.get('retry-after') if err.headers else None)
+
+
+def _read(res) -> str:
+    try:
+        return res.read(4096).decode('utf-8', 'replace')
+    except Exception:  # noqa: BLE001 - a body that cannot be read carries no code, nothing more
+        return ''
+
+
+def _error_code(text: str) -> str:
+    if not text.startswith('{'):
+        return ''
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        return ''  # not the relay's JSON (a proxy's page, say): no code to report
+    code = parsed.get('error') if isinstance(parsed, dict) else None
+    return code if isinstance(code, str) else ''
+
+
+def _unreachable(err: BaseException) -> str:
+    """_unreachable says why a request got no answer at all."""
+    if isinstance(err, (socket.timeout, TimeoutError)) or \
+            (isinstance(err, urllib.error.URLError) and isinstance(err.reason, (socket.timeout, TimeoutError))):
+        return 'the relay did not answer within ' + str(TIMEOUT_SEC) + ' s'
+    reason = err.reason if isinstance(err, urllib.error.URLError) else err
+    return 'the relay could not be reached: ' + (str(reason) or type(reason).__name__)
+
+
+def _hint(status: int, code: str) -> str:
+    """_hint says what to change, per the relay's answers."""
+    if status == 401:
+        return 'the relay rejected the write secret (' + code + '): use the current .env of the view'
+    if status == 404:
+        return 'the relay does not know this view (' + code + '): check the view ID, or use the current .env'
+    if status == 413:
+        return 'the envelope is larger than 256 KiB (' + code + '): fewer tiles or shorter series'
+    if status == 400:
+        return 'the relay refused the envelope (' + code + ')'
+    if status == 429:
+        return 'throttled (' + code + '): the next upload carries the latest state'
+    return 'upload failed with HTTP ' + str(status) + (' (' + code + ')' if code else '')
+
+
+def _retry_after(value: Optional[str]) -> float:
+    try:
+        seconds = float(trim(value)) if value is not None and trim(value) else 0
+    except ValueError:
+        return THROTTLE_SEC  # an HTTP date: the throttle is what the relay means
+    return seconds if math.isfinite(seconds) and seconds > 0 else THROTTLE_SEC
+
+
+def put(base: str, view: str, write_secret: str, envelope: str, transport: Optional[Transport] = None) -> PutResult:
+    """put uploads one envelope and classifies the answer. It never raises for the relay's sake."""
+    url = base + '/v1/views/' + urllib.parse.quote(view, safe='') + '/envelope'
+    headers = {'content-type': 'application/json', 'authorization': 'Bearer ' + write_secret}
+    try:
+        res = (transport or urllib_transport)(url, headers, envelope.encode('utf-8'), TIMEOUT_SEC)
+    except (OSError, ValueError) as err:  # URLError and timeouts are OSErrors; ValueError for a broken URL
+        return PutResult('retry', 0, 'network', _unreachable(err))
+    text = '' if res.status == 204 else (res.text or '')[:300]
+    code = _error_code(text)
+    if res.status == 204:
+        return PutResult('ok', 204)
+    if res.status == 429:
+        return PutResult('throttled', 429, code, _hint(429, code or 'throttled'), _retry_after(res.retry_after))
+    if res.status >= 500:
+        return PutResult('retry', res.status, code, _hint(res.status, code))
+    return PutResult('fatal', res.status, code, _hint(res.status, code))