sw-serverless 10.2.3__tar.gz

sw_serverless-10.2.3/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: sw-serverless
+Version: 10.2.3
+Summary: Write SW-Serverless adapters in Python: settings, commands, and the host protocol, with no dependencies.
+Author: Simplify9
+License-Expression: MIT
+Project-URL: Repository, https://github.com/simplify9/SW-Serverless
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# sw-serverless
+
+Write SW-Serverless adapters in Python 3.12 or later. The package has no dependencies: it speaks the
+host's protocol — gRPC over a Unix socket — with the standard library alone, so it vendors into an
+adapter package as plain files, for any platform.
+
+```python
+import sw_serverless as sw
+
+
+class Greeter:
+    def __init__(self):
+        sw.expect("Greeting", "Hello", description="What to say")
+        sw.expect("ApiKey", secret=True)
+
+    @sw.command(description="Greets someone")
+    def greet(self, name: str) -> str:
+        return f"{sw.value_of('Greeting')}, {name}"
+
+
+if __name__ == "__main__":
+    sw.run(Greeter)
+```
+
+- **Settings** are declared with `sw.expect(name, default=None, *, required, secret, description, type)`
+  and read with `sw.value_of(name)`: the call's own properties, then the values the adapter was
+  started with, then the default.
+- **Commands** are methods marked `@sw.command(name, description=...)`. A command takes at most one
+  argument. A `str` argument or result is raw text, `bytes` are passed as they are, and anything else
+  is JSON; a dataclass is read from and written as a JSON object. Commands may be sync or async; sync
+  ones run on a worker thread.
+- **Errors** raised by a command reach the caller with their type and message. Raise
+  `sw.AdapterError(message, type="Acme.Rejected")` to choose the type.
+- **Resident adapters** have a `start` method and run until stopped, with optional `stop`, `status`
+  (returns `connected`, `state`, `details`…) and `reset(session_id)`. In a command,
+  `sw.context()` publishes events (`await ctx.publish(...)`), keeps small state
+  (`get_state`/`set_state`/`delete_state`) and records metrics.
+- **Logging** through Python's `logging` reaches the host.
+- `python main.py --describe` prints what the adapter is; `sw-serverless build` writes it into the
+  manifest.
+
+An application with a contract of its own declares it with `@sw.implements("orders", 1, "processor")`
+on the adapter class, and can give its adapter authors base classes that do it for them.
+`sw-serverless init --lang python` starts an adapter.
+
+Tests: `PYTHONPATH=src python -m unittest discover -s tests`.

sw_serverless-10.2.3/README.md

@@ -0,0 +1,46 @@
+# sw-serverless
+
+Write SW-Serverless adapters in Python 3.12 or later. The package has no dependencies: it speaks the
+host's protocol — gRPC over a Unix socket — with the standard library alone, so it vendors into an
+adapter package as plain files, for any platform.
+
+```python
+import sw_serverless as sw
+
+
+class Greeter:
+    def __init__(self):
+        sw.expect("Greeting", "Hello", description="What to say")
+        sw.expect("ApiKey", secret=True)
+
+    @sw.command(description="Greets someone")
+    def greet(self, name: str) -> str:
+        return f"{sw.value_of('Greeting')}, {name}"
+
+
+if __name__ == "__main__":
+    sw.run(Greeter)
+```
+
+- **Settings** are declared with `sw.expect(name, default=None, *, required, secret, description, type)`
+  and read with `sw.value_of(name)`: the call's own properties, then the values the adapter was
+  started with, then the default.
+- **Commands** are methods marked `@sw.command(name, description=...)`. A command takes at most one
+  argument. A `str` argument or result is raw text, `bytes` are passed as they are, and anything else
+  is JSON; a dataclass is read from and written as a JSON object. Commands may be sync or async; sync
+  ones run on a worker thread.
+- **Errors** raised by a command reach the caller with their type and message. Raise
+  `sw.AdapterError(message, type="Acme.Rejected")` to choose the type.
+- **Resident adapters** have a `start` method and run until stopped, with optional `stop`, `status`
+  (returns `connected`, `state`, `details`…) and `reset(session_id)`. In a command,
+  `sw.context()` publishes events (`await ctx.publish(...)`), keeps small state
+  (`get_state`/`set_state`/`delete_state`) and records metrics.
+- **Logging** through Python's `logging` reaches the host.
+- `python main.py --describe` prints what the adapter is; `sw-serverless build` writes it into the
+  manifest.
+
+An application with a contract of its own declares it with `@sw.implements("orders", 1, "processor")`
+on the adapter class, and can give its adapter authors base classes that do it for them.
+`sw-serverless init --lang python` starts an adapter.
+
+Tests: `PYTHONPATH=src python -m unittest discover -s tests`.

sw_serverless-10.2.3/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sw-serverless"
+version = "10.2.3"
+description = "Write SW-Serverless adapters in Python: settings, commands, and the host protocol, with no dependencies."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Simplify9" }]
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: POSIX"]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/simplify9/SW-Serverless"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sw_serverless-10.2.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sw_serverless-10.2.3/src/sw_serverless/__init__.py

@@ -0,0 +1,28 @@
+"""Write SW-Serverless adapters in Python.
+
+    import sw_serverless as sw
+
+    class Greeter:
+        def __init__(self):
+            sw.expect("Greeting", "Hello", description="What to say")
+
+        @sw.command(description="Greets someone")
+        def greet(self, name: str) -> str:
+            return f"{sw.value_of('Greeting')}, {name}"
+
+    if __name__ == "__main__":
+        sw.run(Greeter)
+
+``python adapter.py --describe`` prints what it is; the host runs it otherwise. An adapter with a
+``start`` hook is resident: it runs until stopped, with ``stop``, ``status`` and ``reset`` hooks.
+"""
+
+from ._adapter import command, declared_settings, expect, implements, startup_values, value_of
+from ._runner import SDK_VERSION, AdapterError, Context, context, describe, run
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "AdapterError", "Context", "SDK_VERSION", "command", "context", "declared_settings", "describe",
+    "expect", "implements", "run", "startup_values", "value_of",
+]

sw_serverless-10.2.3/src/sw_serverless/_adapter.py

@@ -0,0 +1,180 @@
+"""Declaring an adapter: its settings, its commands, its kinds and contracts.
+
+Settings are declared once, in code, with :func:`expect` — the Python form of the .NET SDK's
+``Runner.Expect`` — and reach the manifest through ``--describe`` and the host through ``Hello``.
+"""
+
+import contextvars
+import inspect
+import typing
+
+from . import _types
+
+SETTING_TYPES = ("text", "multiline", "number", "boolean", "select", "json")
+
+
+class Setting:
+    def __init__(self, name, default, required, secret, description, type):
+        self.name = name
+        self.default = default
+        self.required = required
+        self.secret = secret
+        self.description = description
+        self.type = type
+
+    def describe(self):
+        return {"name": self.name, "description": self.description, "type": self.type,
+                "required": self.required, "secret": self.secret, "default": self.default}
+
+
+_settings = {}
+
+
+def expect(name, default=None, *, required=None, secret=False, description=None, type="text"):
+    """Declares a setting the adapter reads.
+
+    Required unless it has a default or ``required=False`` says otherwise. A secret is masked
+    wherever a host application shows it. Declaring the same name again replaces it.
+    """
+    if not name or not isinstance(name, str):
+        raise ValueError("a setting needs a name")
+    if type not in SETTING_TYPES:
+        raise ValueError(f"setting type must be one of {', '.join(SETTING_TYPES)}")
+    if required is None:
+        required = default is None
+    _settings[name] = Setting(name, None if default is None else str(default), bool(required), bool(secret),
+                              description, type)
+    return name
+
+
+def declared_settings():
+    return list(_settings.values())
+
+
+# The values a call sees: this invocation's properties over the process's startup values.
+_startup_values = {}
+_call_values = contextvars.ContextVar("sw_call_values", default=None)
+
+
+def value_of(name, default=None):
+    """A setting's value for the current call: the call's own properties, then the values the
+    adapter was started with, then the declared default, then ``default``."""
+    call = _call_values.get()
+    if call and name in call:
+        return call[name]
+    if name in _startup_values:
+        return _startup_values[name]
+    declared = _settings.get(name)
+    if declared is not None and declared.default is not None:
+        return declared.default
+    return default
+
+
+def startup_values():
+    return dict(_startup_values)
+
+
+def command(name=None, *, description=None):
+    """Marks a method as a command the host can call, under ``name`` or the method's own name."""
+
+    def mark(fn):
+        fn.__sw_command__ = {"name": name or fn.__name__, "description": description}
+        return fn
+
+    if callable(name):  # used bare: @command
+        fn, name = name, None
+        return mark(fn)
+    return mark
+
+
+class Command:
+    def __init__(self, name, method, description):
+        self.name = name
+        self.method = method
+        self.description = description
+        signature = inspect.signature(method)
+        parameters = [p for p in signature.parameters.values()
+                      if p.name != "self" and p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
+        if len(parameters) > 1:
+            raise TypeError(f"command {name} takes {len(parameters)} arguments; a command takes at most one")
+        try:
+            hints = typing.get_type_hints(method)
+        except Exception:
+            hints = {}
+        self.takes_argument = bool(parameters)
+        self.argument_type = hints.get(parameters[0].name, _types._EMPTY) if parameters else None
+        returns = hints.get("return", signature.return_annotation)
+        self.returns_value = returns not in (None, type(None))
+        self.result_type = returns
+
+    def info(self):
+        input_schema = _types.schema(self.argument_type) if self.takes_argument else None
+        output_schema = _types.schema(self.result_type) if self.returns_value else None
+        return {"name": self.name, "description": self.description, "takes_argument": self.takes_argument,
+                "returns_value": self.returns_value, "input_schema": input_schema, "output_schema": output_schema,
+                "parameter_type": _type_name(self.argument_type) if self.takes_argument else ""}
+
+
+def _type_name(tp):
+    if tp in (_types._EMPTY, None):
+        return "object"
+    return getattr(tp, "__name__", str(tp))
+
+
+def implements(contract, version, *kinds):
+    """Declares, on an adapter class, a contract it implements and the kinds of it it is.
+
+        @sw.implements("orders", 1, "processor")
+        class Orders: ...
+
+    A host application's contract package does this for its own base classes."""
+
+    if not contract or not isinstance(version, int):
+        raise ValueError("a contract needs a name and an integer version")
+
+    def mark(cls):
+        contracts = dict(vars(cls).get("__sw_contracts__", {}))
+        contracts[contract] = version
+        cls.__sw_contracts__ = contracts
+        cls.__sw_kinds__ = list(dict.fromkeys([*vars(cls).get("__sw_kinds__", []), *kinds]))
+        return cls
+
+    return mark
+
+
+def commands_of(adapter):
+    """Every command on the adapter's class, by wire name. Kinds' base classes add their own."""
+    found = {}
+    cls = adapter if isinstance(adapter, type) else type(adapter)
+    for klass in reversed(cls.__mro__):
+        for attr, value in vars(klass).items():
+            marker = getattr(value, "__sw_command__", None)
+            if marker:
+                found[marker["name"]] = attr
+    result = {}
+    for wire_name, attr in found.items():
+        method = getattr(adapter, attr)
+        marker = getattr(getattr(cls, attr), "__sw_command__", None) or {}
+        result[wire_name] = Command(wire_name, method, marker.get("description"))
+    return result
+
+
+def kinds_of(cls):
+    kinds = []
+    for klass in cls.__mro__:
+        for kind in getattr(klass, "__sw_kinds__", ()) or ():
+            if kind not in kinds:
+                kinds.append(kind)
+    return kinds
+
+
+def contracts_of(cls):
+    contracts = {}
+    for klass in reversed(cls.__mro__):
+        contracts.update(getattr(klass, "__sw_contracts__", {}) or {})
+    return contracts
+
+
+def is_resident(cls):
+    """Resident when it has a start hook: it runs until stopped rather than for one session."""
+    return callable(getattr(cls, "start", None))

sw_serverless-10.2.3/src/sw_serverless/_hpack.py

@@ -0,0 +1,186 @@
+"""HPACK (RFC 7541): enough to talk to the host.
+
+The adapter sends one set of request headers, encoded as literals without indexing, which every
+decoder accepts. What the host sends back is decoded in full: static and dynamic tables, size
+updates and Huffman-coded strings, since a server is free to use all of them.
+"""
+
+from ._huffman import CODES
+
+STATIC_TABLE = (
+    (":authority", ""), (":method", "GET"), (":method", "POST"), (":path", "/"),
+    (":path", "/index.html"), (":scheme", "http"), (":scheme", "https"), (":status", "200"),
+    (":status", "204"), (":status", "206"), (":status", "304"), (":status", "400"),
+    (":status", "404"), (":status", "500"), ("accept-charset", ""), ("accept-encoding", "gzip, deflate"),
+    ("accept-language", ""), ("accept-ranges", ""), ("accept", ""), ("access-control-allow-origin", ""),
+    ("age", ""), ("allow", ""), ("authorization", ""), ("cache-control", ""),
+    ("content-disposition", ""), ("content-encoding", ""), ("content-language", ""), ("content-length", ""),
+    ("content-location", ""), ("content-range", ""), ("content-type", ""), ("cookie", ""),
+    ("date", ""), ("etag", ""), ("expect", ""), ("expires", ""),
+    ("from", ""), ("host", ""), ("if-match", ""), ("if-modified-since", ""),
+    ("if-none-match", ""), ("if-range", ""), ("if-unmodified-since", ""), ("last-modified", ""),
+    ("link", ""), ("location", ""), ("max-forwards", ""), ("proxy-authenticate", ""),
+    ("proxy-authorization", ""), ("range", ""), ("referer", ""), ("refresh", ""),
+    ("retry-after", ""), ("server", ""), ("set-cookie", ""), ("strict-transport-security", ""),
+    ("transfer-encoding", ""), ("user-agent", ""), ("vary", ""), ("via", ""),
+    ("www-authenticate", ""),
+)
+
+
+class HpackError(Exception):
+    pass
+
+
+def _huffman_tree():
+    # A binary trie over the codes: each node is [child0, child1, symbol].
+    root = [None, None, None]
+    for symbol, (code, length) in enumerate(CODES):
+        node = root
+        for bit in range(length - 1, -1, -1):
+            b = (code >> bit) & 1
+            if node[b] is None:
+                node[b] = [None, None, None]
+            node = node[b]
+        node[2] = symbol
+    return root
+
+
+_TREE = _huffman_tree()
+
+
+def huffman_decode(data):
+    out = bytearray()
+    node = _TREE
+    depth = 0
+    for byte in data:
+        for bit in range(7, -1, -1):
+            node = node[(byte >> bit) & 1]
+            depth += 1
+            if node is None:
+                raise HpackError("invalid Huffman code")
+            if node[2] is not None:
+                if node[2] == 256:
+                    raise HpackError("EOS symbol in a Huffman string")
+                out.append(node[2])
+                node = _TREE
+                depth = 0
+    # Padding is the most significant bits of EOS (all ones), and shorter than a byte.
+    if depth > 7:
+        raise HpackError("Huffman padding longer than 7 bits")
+    return bytes(out)
+
+
+def _decode_int(data, pos, prefix_bits):
+    mask = (1 << prefix_bits) - 1
+    value = data[pos] & mask
+    pos += 1
+    if value < mask:
+        return value, pos
+    shift = 0
+    while True:
+        if pos >= len(data):
+            raise HpackError("truncated integer")
+        byte = data[pos]
+        pos += 1
+        value += (byte & 0x7F) << shift
+        shift += 7
+        if not byte & 0x80:
+            return value, pos
+
+
+def _encode_int(value, prefix_bits, first_byte_flags=0):
+    mask = (1 << prefix_bits) - 1
+    if value < mask:
+        return bytes([first_byte_flags | value])
+    out = bytearray([first_byte_flags | mask])
+    value -= mask
+    while value >= 0x80:
+        out.append((value & 0x7F) | 0x80)
+        value >>= 7
+    out.append(value)
+    return bytes(out)
+
+
+def _decode_string(data, pos):
+    if pos >= len(data):
+        raise HpackError("truncated string")
+    huffman = data[pos] & 0x80
+    length, pos = _decode_int(data, pos, 7)
+    raw = data[pos:pos + length]
+    if len(raw) != length:
+        raise HpackError("truncated string")
+    pos += length
+    return (huffman_decode(raw) if huffman else bytes(raw)).decode("latin-1"), pos
+
+
+def _encode_string(text):
+    raw = text.encode("latin-1")
+    return _encode_int(len(raw), 7) + raw
+
+
+def encode(headers):
+    """Headers as literals without indexing: never touch either side's dynamic table."""
+    out = bytearray()
+    for name, value in headers:
+        out += b"\x00" + _encode_string(name) + _encode_string(value)
+    return bytes(out)
+
+
+class Decoder:
+    def __init__(self, max_size=4096):
+        self.max_size = max_size
+        self.size = 0
+        self.dynamic = []  # newest first
+
+    @staticmethod
+    def _entry_size(name, value):
+        return len(name.encode("latin-1")) + len(value.encode("latin-1")) + 32
+
+    def _evict(self):
+        while self.size > self.max_size and self.dynamic:
+            name, value = self.dynamic.pop()
+            self.size -= self._entry_size(name, value)
+
+    def _add(self, name, value):
+        self.dynamic.insert(0, (name, value))
+        self.size += self._entry_size(name, value)
+        self._evict()
+
+    def _lookup(self, index):
+        if index <= 0:
+            raise HpackError("index 0")
+        if index <= len(STATIC_TABLE):
+            return STATIC_TABLE[index - 1]
+        index -= len(STATIC_TABLE) + 1
+        if index >= len(self.dynamic):
+            raise HpackError("index past the dynamic table")
+        return self.dynamic[index]
+
+    def decode(self, data):
+        headers = []
+        pos = 0
+        while pos < len(data):
+            byte = data[pos]
+            if byte & 0x80:  # indexed
+                index, pos = _decode_int(data, pos, 7)
+                headers.append(self._lookup(index))
+            elif byte & 0x40:  # literal, incremental indexing
+                index, pos = _decode_int(data, pos, 6)
+                name = self._lookup(index)[0] if index else None
+                if name is None:
+                    name, pos = _decode_string(data, pos)
+                value, pos = _decode_string(data, pos)
+                self._add(name, value)
+                headers.append((name, value))
+            elif byte & 0x20:  # dynamic table size update
+                size, pos = _decode_int(data, pos, 5)
+                self.max_size = size
+                self._evict()
+            else:  # literal without indexing (0000) or never indexed (0001)
+                index, pos = _decode_int(data, pos, 4)
+                name = self._lookup(index)[0] if index else None
+                if name is None:
+                    name, pos = _decode_string(data, pos)
+                value, pos = _decode_string(data, pos)
+                headers.append((name, value))
+        return headers