hydo-assert 0.2.0__py3-none-any.whl

hydo_assert/__init__.py

@@ -0,0 +1,65 @@
+"""hydo-assert: the Python assertion SDK of hydo, the deterministic hypervisor.
+
+A Python program running under hydo uses this package to say what must be true and what should
+happen at least once. It writes the same console records as the Rust, Go and JavaScript SDKs,
+byte for byte, with the same deduplication rules; the wire format and verdict rules are in
+hydo/ASSERTIONS.md. Standard library only; Python 3.8+.
+
+Declare properties at module level, so the whole catalog is known once the module is imported::
+
+    import hydo_assert as ha
+
+    ACKED   = ha.always("kv.acked_durable", "every acknowledged write reads back with its value")
+    REPLAY  = ha.sometimes("kv.recovered", "the server replayed a non-empty log")
+    TORN    = ha.reachable("kv.torn_tail", "the log ended in a partial line")
+    BAD     = ha.unreachable("kv.bad_command", "the server got a command it does not know")
+    SIZE    = ha.always("kv.log_size", "the log stays under its cap")
+    BACK    = ha.eventually("kv.back", "the server answers within 5 s", 5.0)
+    LOST    = ha.buggify("kv.put.lost_reply", "the write lands but the reply is lost")
+
+    ha.catalog()                                 # once, early: the HYDO-ASSERT-DECL lines
+    ACKED.check(got == want, {"key": k, "got": got})
+    SIZE.cmp(n, "<=", cap)                       # op: < <= == != >= >
+    TORN.hit()
+    if LOST.fire():
+        return
+    BACK.await_cond(ping, poll=0.1)              # or: await BACK.await_async(aping, 0.1)
+    ha.setup_complete()                          # HYDO-SETUP-COMPLETE
+
+Records go to /dev/ttyS0; ``HYDO_ASSERT_OUT=<path>|stderr|off|logging`` overrides that.
+"""
+
+from ._core import (
+    Assertion,
+    always,
+    always_or_unreachable,
+    catalog,
+    reachable,
+    setup_complete,
+    sometimes,
+    unreachable,
+)
+from ._buggify import Point, buggify
+from ._eventually import Liveness, Watch, eventually
+
+#: The details type: any mapping (a plain dict). The Go SDK calls it D.
+D = dict
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Assertion",
+    "D",
+    "Liveness",
+    "Point",
+    "Watch",
+    "always",
+    "always_or_unreachable",
+    "buggify",
+    "catalog",
+    "eventually",
+    "reachable",
+    "setup_complete",
+    "sometimes",
+    "unreachable",
+]

hydo_assert/_buggify.py

@@ -0,0 +1,156 @@
+"""BUGGIFY: code-level fault points (FoundationDB style), as in the Go SDK (Milestone 56).
+
+A fault point is a named place where a real dependency can misbehave. The program asks it::
+
+    LOST_REPLY = hydo_assert.buggify("kv.put.lost_reply", "the write lands but the reply is lost")
+    ...
+    if LOST_REPLY.fire():
+        return  # do the work, drop the reply
+
+Activation is two-level, as in FoundationDB (P_BUGGIFIED_SECTION_ACTIVATED = 0.25,
+P_BUGGIFIED_SECTION_FIRES = 0.25): for a run each point is ENABLED with probability
+enable/1000; an enabled point FIRES on its k-th evaluation with probability fire/1000. Both
+decisions are pure functions of the seed, the point's id and k (splitmix64 and FNV-1a, the
+same arithmetic as the Go SDK), so a run stays a pure function of its schedule.
+
+Off unless configured: ``$HYDO_BUGGIFY``, or else the file ``$HYDO_BUGGIFY_FILE`` (default
+``/tmp/hydo-buggify``), holds ``<seed-hex>[,<enable-permille>[,<fire-permille>]]``. Under hydo
+the schedule token ``B=<...>`` is written to that file by the guest init. The configuration is
+read once, at the first evaluation of any point, which also writes::
+
+    HYDO-BUGGIFY {"seed":"...","enable_pm":250,"fire_pm":250,"enabled":["id",...]}
+
+Each point is declared as a sometimes property ``buggify.<id>`` ("fault point fired: <msg>"),
+recorded at its first firing with ``{"hit": k}``.
+"""
+
+import os
+import re
+
+from . import _core, _json, _sink
+
+_M = (1 << 64) - 1
+_GOLDEN = 0x9E3779B97F4A7C15
+
+_points = []
+_loaded = False
+_on = False
+_seed = 0
+_enable = 250
+_fire = 250
+
+# Go's unicode.IsSpace set (strings.TrimSpace), which differs from str.strip()'s.
+_GO_SPACE = (
+    "\t\n\x0b\x0c\r \x85\xa0        "
+    "    

  　"
+)
+_HEXRE = re.compile(r"[0-9A-Fa-f]+\Z")
+_DECRE = re.compile(r"[0-9]+\Z")
+
+
+def _mix(z):  # splitmix64 finalizer
+    z = (z + _GOLDEN) & _M
+    z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & _M
+    z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & _M
+    return z ^ (z >> 31)
+
+
+def _key(id):  # FNV-1a over the id's UTF-8 bytes
+    h = 14695981039346656037
+    for b in bytearray(id.encode("utf-8", "surrogateescape")):
+        h ^= b
+        h = (h * 1099511628211) & _M
+    return h
+
+
+def _parse_u64(s, rx, base):
+    """strconv.ParseUint(s, base, 64): no sign, no prefix, no spaces, <= 2^64-1."""
+    if not rx.match(s):
+        return None
+    v = int(s, base)
+    return v if v <= _M else None
+
+
+class Point(object):
+    """One declared fault point (create it with buggify())."""
+
+    __slots__ = ("id", "_assertion", "_hits")
+
+    def __init__(self, id, msg):
+        self.id = id
+        self._assertion = _core.declare(_core.SOMETIMES, "buggify." + id, "fault point fired: " + msg)
+        self._hits = 0
+
+    def __repr__(self):
+        return "Point(%r)" % (self.id,)
+
+    def _enabled(self):
+        return _mix(_seed ^ _key(self.id)) % 1000 < _enable
+
+    def fire(self, details=None):
+        """Whether the point misbehaves on this evaluation. Always False when BUGGIFY is not
+        configured; then it has no other effect either."""
+        with _core._mu:
+            if not _loaded:
+                _load()
+            if not _on or not self._enabled():
+                return False
+            self._hits += 1
+            k = self._hits
+            fire = _mix((_mix(_seed ^ _key(self.id)) + k * _GOLDEN) & _M) % 1000 < _fire
+        if fire:
+            d = _core.details_dict(details)
+            d["hit"] = k
+            self._assertion._record(True, d)
+        return fire
+
+
+def buggify(id, msg):
+    """Declare a fault point (it also joins the catalog as sometimes ``buggify.<id>``)."""
+    p = Point(id, msg)
+    with _core._mu:
+        _points.append(p)
+    return p
+
+
+def _load():
+    """Read "<seed-hex>[,<enable-permille>[,<fire-permille>]]" (called under _core._mu)."""
+    global _loaded, _on, _seed, _enable, _fire
+    _loaded = True
+    cfg = os.environ.get("HYDO_BUGGIFY", "")
+    if cfg == "":
+        f = os.environ.get("HYDO_BUGGIFY_FILE", "") or "/tmp/hydo-buggify"
+        try:
+            with open(f, "rb") as fh:
+                cfg = fh.read().decode("utf-8", "surrogateescape")
+        except (OSError, IOError):
+            pass
+    parts = cfg.strip(_GO_SPACE).split(",")
+    seed = _parse_u64(parts[0], _HEXRE, 16)
+    if seed is None:
+        return  # no configuration: every point stays off
+    _on, _seed = True, seed
+    if len(parts) > 1:
+        v = _parse_u64(parts[1], _DECRE, 10)
+        if v is not None:
+            _enable = v
+    if len(parts) > 2:
+        v = _parse_u64(parts[2], _DECRE, 10)
+        if v is not None:
+            _fire = v
+    enabled = [p.id for p in _points if p._enabled()]
+    _sink.write_line(
+        'HYDO-BUGGIFY {"seed":' + _json.quote(format(_seed, "x"))
+        + ',"enable_pm":' + str(_enable)
+        + ',"fire_pm":' + str(_fire)
+        + ',"enabled":' + _json.encode(enabled) + "}"
+    )
+
+
+def _reset():
+    """Forget the loaded configuration and every point's evaluation count (tests)."""
+    global _loaded, _on, _seed, _enable, _fire
+    with _core._mu:
+        _loaded, _on, _seed, _enable, _fire = False, False, 0, 250, 250
+        for p in _points:
+            p._hits = 0

hydo_assert/_core.py

@@ -0,0 +1,168 @@
+"""Assertions, the catalog and the lifecycle line (the Go SDK's hydoassert.go)."""
+
+import os
+import threading
+
+from . import _json, _sink
+
+ALWAYS = "always"
+ALWAYS_OR_UNREACHABLE = "always_or_unreachable"
+SOMETIMES = "sometimes"
+REACHABLE = "reachable"
+UNREACHABLE = "unreachable"
+EVENTUALLY = "eventually"
+
+# One process-wide lock, as Go's `mu`: held while the catalog grows, while a record is
+# deduplicated, formatted and written, and while the BUGGIFY configuration is loaded. It is
+# never held across a blocking call or an `await`. Reentrant, so an assertion evaluated from a
+# signal handler that interrupted a record cannot deadlock.
+_mu = threading.RLock()
+_catalog = []
+
+
+def _after_fork():
+    global _mu
+    _mu = threading.RLock()
+
+
+class Assertion(object):
+    """One declared property. Create it with always(), sometimes(), ... (it joins the catalog)."""
+
+    __slots__ = ("_type", "id", "msg", "_seen")
+
+    def __init__(self, t, id, msg):
+        self._type = t
+        self.id = id
+        self.msg = msg
+        self._seen = [False, False]  # outcome already emitted by this process: [false, true]
+
+    def __repr__(self):
+        return "Assertion(%r, %r, %r)" % (self._type, self.id, self.msg)
+
+    def _record(self, ok, details):
+        with _mu:
+            i = 1 if ok else 0
+            if self._seen[i]:
+                return
+            self._seen[i] = True
+            _emit_eval(self._type, self.id, ok, self.msg, details)
+
+    def check(self, cond, details=None):
+        """Evaluate an always / always_or_unreachable / sometimes property. For sometimes only a
+        true outcome is recorded. Returns bool(cond), so it can be used inline."""
+        ok = bool(cond)
+        if self._type == SOMETIMES and not ok:
+            return ok
+        self._record(ok, details)
+        return ok
+
+    def hit(self, details=None):
+        """Mark a reachable location (recorded ok=true) or an unreachable one (recorded
+        ok=false: reaching it is a violation) as reached."""
+        self._record(self._type != UNREACHABLE, details)
+
+    def cmp(self, left, op, right, details=None):
+        """Evaluate ``left <op> right`` (op one of < <= == != >= >) as check(), with left, op
+        and right added to the details. An unknown op evaluates to false."""
+        try:
+            if op == "<":
+                ok = left < right
+            elif op == "<=":
+                ok = left <= right
+            elif op == "==":
+                ok = left == right
+            elif op == "!=":
+                ok = left != right
+            elif op == ">=":
+                ok = left >= right
+            elif op == ">":
+                ok = left > right
+            else:
+                ok = False
+        except TypeError:
+            ok = False
+        d = details_dict(details)
+        d["left"], d["op"], d["right"] = left, op, right
+        return self.check(ok, d)
+
+def details_dict(details):
+    """A fresh dict of ``details`` (None -> {}; a mapping is copied, so the caller's object is
+    never changed; any other value -> {"value": it})."""
+    if details is None:
+        return {}
+    if isinstance(details, _json.Mapping):
+        return dict(details)
+    return {"value": details}
+
+
+def declare(t, id, msg):
+    a = Assertion(t, id, msg)
+    with _mu:
+        _catalog.append(a)
+    return a
+
+
+def always(id, msg):
+    """Declare a property that must hold whenever it is evaluated (and be evaluated at least once)."""
+    return declare(ALWAYS, id, msg)
+
+
+def always_or_unreachable(id, msg):
+    """Declare a property that must hold whenever evaluated; never being evaluated is fine."""
+    return declare(ALWAYS_OR_UNREACHABLE, id, msg)
+
+
+def sometimes(id, msg):
+    """Declare a property that must be true at least once across an exploration."""
+    return declare(SOMETIMES, id, msg)
+
+
+def reachable(id, msg):
+    """Declare a code location that must be reached at least once."""
+    return declare(REACHABLE, id, msg)
+
+
+def unreachable(id, msg):
+    """Declare a code location that must never be reached."""
+    return declare(UNREACHABLE, id, msg)
+
+
+def _emit_eval(t, id, ok, msg, details):
+    if details is not None and not isinstance(details, _json.Mapping):
+        details = {"value": details}
+    try:
+        line = (
+            'HYDO-ASSERT {"t":' + _json.quote(t)
+            + ',"id":' + _json.quote(id)
+            + ',"ok":' + ("true" if ok else "false")
+            + ',"msg":' + _json.quote(msg)
+            + ((',"details":' + _json.encode(details)) if details else "")
+            + "}"
+        )
+    except _json.Unencodable:
+        return  # as Go: json.Marshal fails, the record is not written
+    _sink.write_line(line)
+
+
+def catalog():
+    """Write one HYDO-ASSERT-DECL line per declared assertion, in declaration order, so
+    properties that are never evaluated can still be reported. Call it once, early, from the
+    process that should carry the catalog into the console."""
+    with _mu:
+        for a in _catalog:
+            _sink.write_line(
+                'HYDO-ASSERT-DECL {"t":' + _json.quote(a._type)
+                + ',"id":' + _json.quote(a.id)
+                + ',"msg":' + _json.quote(a.msg) + "}"
+            )
+
+
+def setup_complete():
+    """Write the lifecycle line HYDO-SETUP-COMPLETE: the system is provisioned and ready,
+    faults may begin, and this is a good snapshot/branch point."""
+    _sink.write_line("HYDO-SETUP-COMPLETE")
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork)
+    os.register_at_fork(after_in_child=_sink._after_fork)

hydo_assert/_eventually.py

@@ -0,0 +1,120 @@
+"""Bounded liveness: ``eventually`` properties (the Go SDK's eventually.go).
+
+An eventually property says "after an anchor, the condition becomes true within a deadline".
+hvx makes guest time deterministic, so a deadline measured on the guest's monotonic clock is
+deterministic too: the same schedule gives the same verdict and the same elapsed time.
+
+One evaluation record per episode, with ``elapsed_ms`` and ``within_ms`` (integers) in the
+details: ok=true when the condition became true by the deadline, ok=false when the deadline
+passed first (or it became true too late). Each outcome is emitted at most once per process.
+"""
+
+import asyncio
+import datetime
+import inspect
+import threading
+import time
+
+from . import _core
+
+_NS_PER_MS = 1000000
+
+
+def _now_ns():
+    return time.monotonic_ns()
+
+
+def _to_ns(d):
+    """Seconds (int/float) or a datetime.timedelta, as integer nanoseconds."""
+    if isinstance(d, datetime.timedelta):
+        return (d // datetime.timedelta(microseconds=1)) * 1000
+    return int(round(d * 1000000000))
+
+
+class Liveness(object):
+    """A declared eventually property (create it with eventually())."""
+
+    __slots__ = ("_assertion", "within_ns")
+
+    def __init__(self, id, msg, within):
+        self._assertion = _core.declare(_core.EVENTUALLY, id, msg)
+        self.within_ns = _to_ns(within)
+
+    @property
+    def id(self):
+        return self._assertion.id
+
+    def begin(self):
+        """Start an episode now (the anchor)."""
+        return Watch(self)
+
+    def await_cond(self, cond, poll, details=None):
+        """Start an episode now, call ``cond()`` every ``poll`` seconds until it is true or
+        the deadline has passed, record the outcome and return it. Blocks the thread. The last
+        check happens at or after the deadline, so a condition that becomes true exactly at
+        the deadline still counts."""
+        w = Watch(self)
+        poll_s = _to_ns(poll) / 1e9
+        while True:
+            if cond():
+                return w.done(details)
+            if _now_ns() - w.start_ns > self.within_ns:
+                w.expire(details)
+                return False
+            time.sleep(poll_s)
+
+    async def await_async(self, cond, poll, details=None):
+        """As await_cond, for asyncio code: ``cond`` may be a plain function or return an
+        awaitable (an ``async def``), and the wait between checks is ``asyncio.sleep``."""
+        w = Watch(self)
+        poll_s = _to_ns(poll) / 1e9
+        while True:
+            r = cond()
+            if inspect.isawaitable(r):
+                r = await r
+            if r:
+                return w.done(details)
+            if _now_ns() - w.start_ns > self.within_ns:
+                w.expire(details)
+                return False
+            await asyncio.sleep(poll_s)
+
+
+class Watch(object):
+    """One episode of a Liveness property, started at its anchor."""
+
+    __slots__ = ("liveness", "start_ns", "_done", "_lock")
+
+    def __init__(self, liveness):
+        self.liveness = liveness
+        self.start_ns = _now_ns()
+        self._done = False
+        self._lock = threading.Lock()
+
+    def _finish(self, ok, elapsed_ns, details):
+        with self._lock:
+            if self._done:
+                return ok
+            self._done = True
+        d = _core.details_dict(details)
+        d["elapsed_ms"] = elapsed_ns // _NS_PER_MS
+        d["within_ms"] = self.liveness.within_ns // _NS_PER_MS
+        self.liveness._assertion._record(ok, d)
+        return ok
+
+    def done(self, details=None):
+        """The condition became true now: recorded ok if within the deadline, else a violation
+        (true, but too late). Returns whether it was in time. Only the first done/expire of an
+        episode is recorded."""
+        el = _now_ns() - self.start_ns
+        return self._finish(el <= self.liveness.within_ns, el, details)
+
+    def expire(self, details=None):
+        """The deadline passed with the condition still false (a violation)."""
+        self._finish(False, _now_ns() - self.start_ns, details)
+
+
+def eventually(id, msg, within):
+    """Declare a bounded-liveness property: after an anchor, the condition holds within
+    ``within`` (seconds, or a datetime.timedelta)."""
+    return Liveness(id, msg, within)

hydo_assert/_json.py

@@ -0,0 +1,163 @@
+"""A JSON encoder that writes exactly what Go's encoding/json writes for the same data.
+
+The Go SDK (sdk/go/hydoassert) encodes its records with json.Marshal. To be byte-identical:
+
+- object keys are sorted by their UTF-8 bytes (Go sorts map keys that way);
+- strings are escaped as Go escapes them: ``"`` ``\\`` ``\\b`` ``\\f`` ``\\n`` ``\\r`` ``\\t``,
+  other control characters as ``\\u00xx``, the HTML characters ``<`` ``>`` ``&`` as
+  ``\\u003c`` ``\\u003e`` ``\\u0026``, U+2028 and U+2029 as ``\\u2028`` ``\\u2029``; everything
+  else (all other non-ASCII text) is written as UTF-8. A lone surrogate (Python's stand-in for
+  an undecodable byte, e.g. from ``surrogateescape``) is written as ``\\ufffd``, as Go up to
+  1.26 writes each invalid UTF-8 byte (Go 1.27's encoder writes a raw U+FFFD instead; the
+  guest images are built with the pinned Go 1.26.5);
+- floats use Go's format: the shortest digits that round-trip, plain notation when
+  1e-6 <= |f| < 1e21 (or f == 0), else exponent notation ``1e+21`` / ``1.5e-7``;
+- a NaN or an infinity cannot be encoded (Go's Marshal fails): Unencodable is raised and the
+  caller drops the whole record.
+
+Python-only value types (Go has no equivalent, so no Go program can produce them): a tuple is
+an array; ``bytes``/``bytearray`` are base64 strings (as Go encodes ``[]byte``); a set or
+frozenset is an array sorted by the encoded elements (so the output does not depend on hash
+order); any other object is encoded as the string ``str(obj)``. Mapping keys that are ints are
+written in decimal (as Go writes integer map keys); other non-string keys as ``str(key)``.
+"""
+
+import base64
+import decimal
+import math
+
+try:  # Python 3.3+
+    from collections.abc import Mapping
+except ImportError:  # pragma: no cover
+    from collections import Mapping
+
+
+class Unencodable(ValueError):
+    """A value Go's json.Marshal would refuse (NaN, +Inf, -Inf)."""
+
+
+_HEX = "0123456789abcdef"
+
+
+def _build_escape_table():
+    t = {}
+    for c in range(0x20):
+        t[c] = "\\u00" + _HEX[c >> 4] + _HEX[c & 0xF]
+    t[0x08] = "\\b"
+    t[0x0C] = "\\f"
+    t[0x0A] = "\\n"
+    t[0x0D] = "\\r"
+    t[0x09] = "\\t"
+    t[0x22] = '\\"'
+    t[0x5C] = "\\\\"
+    t[0x3C] = "\\u003c"
+    t[0x3E] = "\\u003e"
+    t[0x26] = "\\u0026"
+    t[0x2028] = "\\u2028"
+    t[0x2029] = "\\u2029"
+    for c in range(0xD800, 0xE000):
+        t[c] = "\\ufffd"
+    return t
+
+
+_ESCAPES = _build_escape_table()
+
+
+def quote(s):
+    """The JSON string literal of ``s``, as Go writes it (with HTML escaping)."""
+    return '"' + s.translate(_ESCAPES) + '"'
+
+
+def _format_float(f):
+    if math.isnan(f) or math.isinf(f):
+        raise Unencodable("NaN or infinity")
+    if f == 0.0:
+        return "-0" if math.copysign(1.0, f) < 0 else "0"
+    sign, digits, exp = decimal.Decimal(repr(f)).as_tuple()
+    digits = list(digits)
+    while len(digits) > 1 and digits[-1] == 0:  # repr may carry a trailing ".0"
+        digits.pop()
+        exp += 1
+    ds = "".join(str(d) for d in digits)
+    n = len(ds)
+    e10 = exp + n - 1  # the value is d.ddd x 10^e10
+    neg = "-" if sign else ""
+    a = abs(f)
+    if a < 1e-6 or a >= 1e21:
+        mant = ds[0] + ("." + ds[1:] if n > 1 else "")
+        if e10 < 0:
+            return neg + mant + "e-" + str(-e10)  # Go cleans e-07 to e-7
+        return neg + mant + "e+" + ("%02d" % e10)
+    if exp >= 0:
+        return neg + ds + "0" * exp
+    if e10 >= 0:
+        return neg + ds[: e10 + 1] + "." + ds[e10 + 1:]
+    return neg + "0." + "0" * (-e10 - 1) + ds
+
+
+def _key_str(k):
+    if isinstance(k, str):
+        return k
+    if isinstance(k, bool):
+        return "true" if k else "false"
+    if isinstance(k, int):
+        return str(int(k))
+    return str(k)
+
+
+def _utf8(s):
+    """The bytes Go would compare: a surrogate from surrogateescape is its original byte."""
+    try:
+        return s.encode("utf-8", "surrogateescape")
+    except UnicodeEncodeError:
+        return s.encode("utf-8", "surrogatepass")
+
+
+def encode(v):
+    """The JSON text of ``v``, as Go's encoding/json writes the equivalent Go value."""
+    out = []
+    _enc(v, out)
+    return "".join(out)
+
+
+def _enc(v, out):
+    if v is None:
+        out.append("null")
+    elif v is True:
+        out.append("true")
+    elif v is False:
+        out.append("false")
+    elif isinstance(v, str):
+        out.append(quote(v))
+    elif isinstance(v, bool):  # a bool subclass (numpy-like); after the singletons
+        out.append("true" if v else "false")
+    elif isinstance(v, int):
+        out.append(str(int(v)))
+    elif isinstance(v, float):
+        out.append(_format_float(float(v)))
+    elif isinstance(v, Mapping):
+        items = sorted(((_key_str(k), x) for k, x in v.items()), key=lambda kv: _utf8(kv[0]))
+        out.append("{")
+        first = True
+        for k, x in items:
+            if not first:
+                out.append(",")
+            first = False
+            out.append(quote(k))
+            out.append(":")
+            _enc(x, out)
+        out.append("}")
+    elif isinstance(v, (list, tuple)):
+        out.append("[")
+        for i, x in enumerate(v):
+            if i:
+                out.append(",")
+            _enc(x, out)
+        out.append("]")
+    elif isinstance(v, (bytes, bytearray, memoryview)):
+        out.append('"' + base64.b64encode(bytes(v)).decode("ascii") + '"')
+    elif isinstance(v, (set, frozenset)):
+        elems = sorted((encode(x) for x in v), key=_utf8)
+        out.append("[" + ",".join(elems) + "]")
+    else:
+        out.append(quote(str(v)))