serto-sdk 1.5.0__tar.gz

serto_sdk-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craytech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

serto_sdk-1.5.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: serto-sdk
+Version: 1.5.0
+Summary: Serto Python SDK — write integrations in Python that run on the Serto platform
+Author: Craytech
+License: MIT
+Project-URL: Homepage, https://github.com/neweyc/integration-platform
+Project-URL: Repository, https://github.com/neweyc/integration-platform
+Keywords: serto,integration,automation,workflow
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Serto Python SDK
+
+```sh
+pip install serto-sdk    # distribution name; the import package is `serto`
+```
+
+Write Serto integrations in Python. An integration is any callable taking a `Context`:
+
+```python
+# main.py
+def handler(ctx):
+    ctx.logger.info(f"Running in {ctx.execution.environment}")
+
+    order = ctx.payload_json()              # webhook/message body, parsed
+    api_key = ctx.secrets["API_KEY"]        # provisioned secret
+
+    # ... do the work ...
+
+    ctx.publish("orders.synced", {"count": 42})   # message other integrations can subscribe to
+```
+
+Declare it in a `serto.json` next to your code:
+
+```json
+{
+  "manifestVersion": "1",
+  "runtime": "python",
+  "integrations": [
+    {
+      "name": "Sync Orders",
+      "slug": "sync-orders",
+      "entrypoint": "main.py:handler",
+      "triggers": [{ "type": "scheduled", "cron": "0 * * * *" }],
+      "requiredSecrets": ["API_KEY"]
+    }
+  ]
+}
+```
+
+## How it runs
+
+The Serto agent launches `python -m serto` in your integration's directory, sends the invocation on
+stdin, and reads structured events (logs, published messages, the result) from stdout. The protocol is
+documented in [`docs/multi-language-runtimes.md`](../../docs/multi-language-runtimes.md). `async def`
+handlers are supported.
+
+## The Context
+
+| member | description |
+|---|---|
+| `ctx.logger` | `.trace/.debug/.info/.warning/.error/.critical` — captured into execution history |
+| `ctx.secrets` | dict of secrets provisioned for the environment |
+| `ctx.payload` / `ctx.payload_json()` | raw / parsed webhook or message body (`None` for scheduled) |
+| `ctx.trigger` | how the run was triggered (`ctx.trigger["type"]` + source-specific fields) |
+| `ctx.execution` | `.execution_id`, `.integration_name`, `.environment`, `.scheduled_at`, … |
+| `ctx.publish(subject, body)` | publish a message; a non-string body is JSON-encoded |
+
+## Tests
+
+```sh
+cd sdks/python && python -m unittest discover -s tests
+```

serto_sdk-1.5.0/README.md

@@ -0,0 +1,62 @@
+# Serto Python SDK
+
+```sh
+pip install serto-sdk    # distribution name; the import package is `serto`
+```
+
+Write Serto integrations in Python. An integration is any callable taking a `Context`:
+
+```python
+# main.py
+def handler(ctx):
+    ctx.logger.info(f"Running in {ctx.execution.environment}")
+
+    order = ctx.payload_json()              # webhook/message body, parsed
+    api_key = ctx.secrets["API_KEY"]        # provisioned secret
+
+    # ... do the work ...
+
+    ctx.publish("orders.synced", {"count": 42})   # message other integrations can subscribe to
+```
+
+Declare it in a `serto.json` next to your code:
+
+```json
+{
+  "manifestVersion": "1",
+  "runtime": "python",
+  "integrations": [
+    {
+      "name": "Sync Orders",
+      "slug": "sync-orders",
+      "entrypoint": "main.py:handler",
+      "triggers": [{ "type": "scheduled", "cron": "0 * * * *" }],
+      "requiredSecrets": ["API_KEY"]
+    }
+  ]
+}
+```
+
+## How it runs
+
+The Serto agent launches `python -m serto` in your integration's directory, sends the invocation on
+stdin, and reads structured events (logs, published messages, the result) from stdout. The protocol is
+documented in [`docs/multi-language-runtimes.md`](../../docs/multi-language-runtimes.md). `async def`
+handlers are supported.
+
+## The Context
+
+| member | description |
+|---|---|
+| `ctx.logger` | `.trace/.debug/.info/.warning/.error/.critical` — captured into execution history |
+| `ctx.secrets` | dict of secrets provisioned for the environment |
+| `ctx.payload` / `ctx.payload_json()` | raw / parsed webhook or message body (`None` for scheduled) |
+| `ctx.trigger` | how the run was triggered (`ctx.trigger["type"]` + source-specific fields) |
+| `ctx.execution` | `.execution_id`, `.integration_name`, `.environment`, `.scheduled_at`, … |
+| `ctx.publish(subject, body)` | publish a message; a non-string body is JSON-encoded |
+
+## Tests
+
+```sh
+cd sdks/python && python -m unittest discover -s tests
+```

serto_sdk-1.5.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI is "serto-sdk" (the bare "serto" name is already taken); the import package
+# is still `serto` (import serto). The release workflow overrides the version from the git tag.
+name = "serto-sdk"
+version = "1.5.0"
+description = "Serto Python SDK — write integrations in Python that run on the Serto platform"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Craytech" }]
+keywords = ["serto", "integration", "automation", "workflow"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/neweyc/integration-platform"
+Repository = "https://github.com/neweyc/integration-platform"
+
+[tool.setuptools.packages.find]
+include = ["serto*"]

serto_sdk-1.5.0/serto/__init__.py

@@ -0,0 +1,17 @@
+"""Serto Python SDK — write integrations in Python that run on the Serto platform.
+
+A handler is any callable taking a single ``Context`` argument::
+
+    def handler(ctx):
+        ctx.logger.info("running")
+        data = ctx.payload_json()
+        ctx.publish("orders.synced", {"count": 42})
+
+Declare it in ``serto.json`` with an entrypoint of ``your_file.py:handler``. See
+docs/multi-language-runtimes.md.
+"""
+
+from .context import Context, Execution, Logger
+
+__all__ = ["Context", "Execution", "Logger"]
+__version__ = "0.1.0"

serto_sdk-1.5.0/serto/__main__.py

@@ -0,0 +1,3 @@
+from serto._harness import main
+
+main()

serto_sdk-1.5.0/serto/_harness.py

@@ -0,0 +1,86 @@
+"""The Serto Python harness — the mirror of the agent's SubprocessRunner.
+
+The agent launches this (``python -m serto``) in the package directory, writes one invocation JSON object
+to stdin, and reads wire-protocol events (JSON-lines) from stdout. The harness reads the invocation,
+resolves the declared entrypoint, runs it with a Context, and emits a terminal ``result`` event.
+
+Contract: docs/multi-language-runtimes.md.
+"""
+
+import asyncio
+import importlib
+import importlib.util
+import inspect
+import json
+import os
+import sys
+import traceback
+
+from .context import Context
+
+
+def _resolve_entrypoint(spec):
+    """Resolve an entrypoint string into a callable.
+
+    Forms:
+      * ``file.py:function`` — load the file (relative to the working directory) and read ``function``.
+      * ``module:function``  — import the module and read ``function``.
+    """
+    if not spec or ":" not in spec:
+        raise ValueError(
+            "Entrypoint must be 'file.py:function' or 'module:function', got %r" % (spec,))
+
+    module_part, func_name = spec.rsplit(":", 1)
+
+    if module_part.endswith(".py"):
+        path = os.path.abspath(module_part)
+        if not os.path.exists(path):
+            raise FileNotFoundError("Entrypoint file not found: %s" % path)
+        mod_name = os.path.splitext(os.path.basename(path))[0]
+        loaded = importlib.util.spec_from_file_location(mod_name, path)
+        module = importlib.util.module_from_spec(loaded)
+        loaded.loader.exec_module(module)
+    else:
+        module = importlib.import_module(module_part)
+
+    if not hasattr(module, func_name):
+        raise AttributeError("Entrypoint '%s' has no attribute '%s'" % (module_part, func_name))
+    return getattr(module, func_name)
+
+
+def run(invocation, emit):
+    """Resolve and execute the integration. Raises on failure; the caller maps that to a result event.
+
+    Supports both sync handlers and ``async def`` handlers.
+    """
+    ctx = Context(invocation, emit)
+    handler = _resolve_entrypoint(invocation.get("entrypoint", ""))
+    result = handler(ctx)
+    if inspect.iscoroutine(result):
+        asyncio.run(result)
+
+
+def main(stdin=None, stdout=None):
+    """Entry point for ``python -m serto``. Reads the invocation, runs it, emits a result.
+
+    stdin/stdout are injectable for testing. The integration's own stdout is redirected to stderr so a
+    stray ``print()`` can never corrupt the JSON-lines protocol channel.
+    """
+    protocol_out = stdout if stdout is not None else sys.stdout
+    source = stdin if stdin is not None else sys.stdin
+
+    saved_stdout = sys.stdout
+    sys.stdout = sys.stderr
+
+    def emit(event):
+        protocol_out.write(json.dumps(event) + "\n")
+        protocol_out.flush()
+
+    try:
+        invocation = json.loads(source.read())
+        run(invocation, emit)
+        emit({"type": "result", "succeeded": True, "error": None})
+    except Exception:
+        emit({"type": "result", "succeeded": False, "error": traceback.format_exc()})
+    finally:
+        sys.stdout = saved_stdout

serto_sdk-1.5.0/serto/context.py

@@ -0,0 +1,73 @@
+"""The execution context handed to a Python integration.
+
+Mirrors the .NET IIntegrationContext: secrets, a structured logger, the trigger, the payload, and a way
+to publish messages. Logs and messages are emitted as wire-protocol events (see _harness); the agent
+forwards them onto the same pipeline a C# integration uses, so a Python run is indistinguishable
+downstream. See docs/multi-language-runtimes.md.
+"""
+
+import json
+
+
+class Execution:
+    """Metadata about the current run."""
+
+    def __init__(self, data):
+        self.execution_id = data.get("executionId")
+        self.integration_id = data.get("integrationId")
+        self.integration_name = data.get("integrationName")
+        self.environment = data.get("environment")
+        self.scheduled_at = data.get("scheduledAt")
+
+
+class Logger:
+    """Structured logger. Levels match .NET LogLevel names so they render identically in execution history."""
+
+    def __init__(self, emit):
+        self._emit = emit
+
+    def _log(self, level, message, exception=None):
+        event = {"type": "log", "level": level, "message": str(message)}
+        if exception is not None:
+            event["exception"] = str(exception)
+        self._emit(event)
+
+    def trace(self, message):
+        self._log("Trace", message)
+
+    def debug(self, message):
+        self._log("Debug", message)
+
+    def info(self, message):
+        self._log("Information", message)
+
+    def warning(self, message):
+        self._log("Warning", message)
+
+    def error(self, message, exception=None):
+        self._log("Error", message, exception)
+
+    def critical(self, message, exception=None):
+        self._log("Critical", message, exception)
+
+
+class Context:
+    def __init__(self, invocation, emit):
+        self._emit = emit
+        self.execution = Execution(invocation.get("execution", {}))
+        # The trigger is passed through verbatim; read trigger["type"] and source-specific fields.
+        self.trigger = invocation.get("trigger", {})
+        # Raw request/message body for webhook- and message-triggered runs; None otherwise.
+        self.payload = invocation.get("payload")
+        self.secrets = invocation.get("secrets", {})
+        self.logger = Logger(emit)
+
+    def payload_json(self):
+        """Deserialize the payload as JSON, or None when there is no payload."""
+        return json.loads(self.payload) if self.payload else None
+
+    def publish(self, subject, body):
+        """Publish a message other integrations can subscribe to. A non-string body is JSON-encoded."""
+        if not isinstance(body, str):
+            body = json.dumps(body)
+        self._emit({"type": "message", "subject": subject, "body": body})

serto_sdk-1.5.0/serto_sdk.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: serto-sdk
+Version: 1.5.0
+Summary: Serto Python SDK — write integrations in Python that run on the Serto platform
+Author: Craytech
+License: MIT
+Project-URL: Homepage, https://github.com/neweyc/integration-platform
+Project-URL: Repository, https://github.com/neweyc/integration-platform
+Keywords: serto,integration,automation,workflow
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Serto Python SDK
+
+```sh
+pip install serto-sdk    # distribution name; the import package is `serto`
+```
+
+Write Serto integrations in Python. An integration is any callable taking a `Context`:
+
+```python
+# main.py
+def handler(ctx):
+    ctx.logger.info(f"Running in {ctx.execution.environment}")
+
+    order = ctx.payload_json()              # webhook/message body, parsed
+    api_key = ctx.secrets["API_KEY"]        # provisioned secret
+
+    # ... do the work ...
+
+    ctx.publish("orders.synced", {"count": 42})   # message other integrations can subscribe to
+```
+
+Declare it in a `serto.json` next to your code:
+
+```json
+{
+  "manifestVersion": "1",
+  "runtime": "python",
+  "integrations": [
+    {
+      "name": "Sync Orders",
+      "slug": "sync-orders",
+      "entrypoint": "main.py:handler",
+      "triggers": [{ "type": "scheduled", "cron": "0 * * * *" }],
+      "requiredSecrets": ["API_KEY"]
+    }
+  ]
+}
+```
+
+## How it runs
+
+The Serto agent launches `python -m serto` in your integration's directory, sends the invocation on
+stdin, and reads structured events (logs, published messages, the result) from stdout. The protocol is
+documented in [`docs/multi-language-runtimes.md`](../../docs/multi-language-runtimes.md). `async def`
+handlers are supported.
+
+## The Context
+
+| member | description |
+|---|---|
+| `ctx.logger` | `.trace/.debug/.info/.warning/.error/.critical` — captured into execution history |
+| `ctx.secrets` | dict of secrets provisioned for the environment |
+| `ctx.payload` / `ctx.payload_json()` | raw / parsed webhook or message body (`None` for scheduled) |
+| `ctx.trigger` | how the run was triggered (`ctx.trigger["type"]` + source-specific fields) |
+| `ctx.execution` | `.execution_id`, `.integration_name`, `.environment`, `.scheduled_at`, … |
+| `ctx.publish(subject, body)` | publish a message; a non-string body is JSON-encoded |
+
+## Tests
+
+```sh
+cd sdks/python && python -m unittest discover -s tests
+```

serto_sdk-1.5.0/serto_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+serto/__init__.py
+serto/__main__.py
+serto/_harness.py
+serto/context.py
+serto_sdk.egg-info/PKG-INFO
+serto_sdk.egg-info/SOURCES.txt
+serto_sdk.egg-info/dependency_links.txt
+serto_sdk.egg-info/top_level.txt
+tests/test_harness.py

serto_sdk-1.5.0/serto_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

serto_sdk-1.5.0/serto_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+serto

serto_sdk-1.5.0/setup.cfg

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

serto_sdk-1.5.0/tests/test_harness.py

@@ -0,0 +1,70 @@
+import io
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from serto._harness import main, run  # noqa: E402
+
+FIXTURES = os.path.join(os.path.dirname(__file__), "fixtures.py")
+
+
+def invocation(func, payload=None, secrets=None):
+    return {
+        "protocolVersion": "1",
+        "entrypoint": FIXTURES + ":" + func,
+        "execution": {"environment": "production"},
+        "trigger": {"type": "manual"},
+        "payload": payload,
+        "secrets": secrets or {},
+    }
+
+
+class RunTests(unittest.TestCase):
+    def _events(self, func, **kw):
+        events = []
+        run(invocation(func, **kw), events.append)
+        return events
+
+    def test_logs_and_publishes(self):
+        events = self._events("success_handler")
+        self.assertIn({"type": "log", "level": "Information", "message": "ran ok"}, events)
+        message = next(e for e in events if e["type"] == "message")
+        self.assertEqual("test.subject", message["subject"])
+        self.assertEqual({"k": 1}, json.loads(message["body"]))
+
+    def test_secrets_are_available(self):
+        events = self._events("secret_handler", secrets={"API_KEY": "xyz"})
+        self.assertTrue(any("secret=xyz" in e.get("message", "") for e in events))
+
+    def test_failure_propagates(self):
+        with self.assertRaises(RuntimeError):
+            self._events("failing_handler")
+
+    def test_async_handler_is_awaited(self):
+        events = self._events("async_handler")
+        self.assertTrue(any(e.get("message") == "async ran" for e in events))
+
+
+class MainTests(unittest.TestCase):
+    def _run_main(self, func, **kw):
+        out = io.StringIO()
+        main(stdin=io.StringIO(json.dumps(invocation(func, **kw))), stdout=out)
+        return [json.loads(line) for line in out.getvalue().splitlines() if line.strip()]
+
+    def test_success_emits_result_true(self):
+        events = self._run_main("success_handler")
+        self.assertEqual({"type": "result", "succeeded": True, "error": None}, events[-1])
+
+    def test_failure_emits_result_false_with_traceback(self):
+        events = self._run_main("failing_handler")
+        result = events[-1]
+        self.assertEqual("result", result["type"])
+        self.assertFalse(result["succeeded"])
+        self.assertIn("boom", result["error"])
+
+
+if __name__ == "__main__":
+    unittest.main()