lvi-script-sandbox-utils 0.6.0__tar.gz

lvi_script_sandbox_utils-0.6.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Jayde Hanley
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lvi_script_sandbox_utils-0.6.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: lvi-script-sandbox-utils
+Version: 0.6.0
+Summary: Convenience utilities for LogicVein Script Sandbox Python scripts
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# LogicVein Script Sandbox Utils
+
+Convenience helpers for Python scripts that LogicVein Playbooks run in the
+Script Sandbox container. They wrap the sandbox's file-and-stdout contract:
+a Playbook hands your script its inputs in `in.json`, and your script returns
+results by printing JSON to stdout.
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install lvi-script-sandbox-utils
+```
+
+From TestPyPI (pre-release / testing):
+
+```bash
+pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  lvi-script-sandbox-utils
+```
+
+The sandbox runs scripts in a container, so the package has to be available
+inside it. If your sandbox mounts a packages directory (for example
+`./packages:/packages`), install into it:
+
+```bash
+pip install --target ./packages lvi-script-sandbox-utils
+```
+
+The library has no third-party dependencies (standard library only).
+
+### Upgrading from 0.1.x
+
+0.1.x installed as `logicvein.lvi_script_sandbox_utils`. From 0.2.0 it is
+the top-level package `lvi_script_sandbox_utils`, so change
+
+```python
+from logicvein import lvi_script_sandbox_utils as lvi
+```
+
+to `import lvi_script_sandbox_utils as lvi`. The `logicvein` package is
+left to `lvi-api-client`: when both shipped a `logicvein/` directory,
+`pip install --target` skipped whichever was installed second (or, with
+`--upgrade`, deleted the first).
+
+## Usage
+
+```python
+import lvi_script_sandbox_utils as lvi
+
+device = lvi.get_device()
+output = lvi.get_input("cli_output", default="")  # "" in the Playbook's first script node
+
+lvi.flush_output(hostname=device.device_hostname, line_count=len(output.splitlines()))
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `load_input(path=None, reload=False)` | The whole `in.json` as a dict, read once and cached. Treat it as read-only. |
+| `get_input(input_type, default=...)` | Read an input from `in.json`. `"cli_output"` returns the previous node's result value; `"device"` returns the raw device dict. A missing input returns `default`, or raises `KeyError` if none was given; any other `input_type` raises `ValueError`. |
+| `get_global(name, default=...)` | One Playbook global's value, e.g. `get_global("hostname")`. A missing global returns `default`, or raises `KeyError` naming the globals that are set. |
+| `get_globals()` | Every Playbook global as `{name: value}`. |
+| `get_metadata()` | Details of this run as an object: `playbook`, `execution_id`, `executor`, `job_id`, `node`, `started_at`, and so on. |
+| `get_device(blank_none=True)` | The Playbook's device as an object with a basic set of properties (see below). |
+| `get_full_device(blank_none=True)` | Like `get_device()`, with the additional properties included (`uuid`, `lastBackup`, `severity`, `memoSummary`, ...). |
+| `set_output(key, value)` | Record a global for the next `flush_output()`. |
+| `flush_output(**kwargs)` | Print the `set_output()` values plus `kwargs` (which win on a clash) to stdout as Playbook global variables (`output.globals`), then clear the `set_output()` values. Device and metadata objects print as their fields. |
+| `flush_string_output(text)` | Print a string to stdout as base64-encoded raw output (`output.raw`). |
+
+On the device objects:
+
+- `hostname` and `network` are renamed to `device_hostname` and
+  `device_network`, so they don't collide with other Playbook variables.
+- `traits` lists the device's capabilities from `metaJson` (`ssh`, `snmp`,
+  `ncm`, ...); `customFields` is dropped, since it repeats `custom1`..`custom5`.
+- End-of-life/sale epochs (`endOfLife`, `endOfSale`, `softwareEndOfLife`,
+  `softwareEndOfSale`) become `YYYY-MM-DD` dates, and `lastBackup`,
+  `lastChange`, `lastDiscovery`, `lastTelemetry` become
+  `YYYY-MM-DDTHH:MM:SSZ` timestamps, all in UTC. `get_metadata().started_at`
+  is converted the same way.
+- `None` values become `""`; pass `blank_none=False` to keep `None`.
+- A property LogicVein doesn't send is simply absent from the object.
+
+`vars(device)` gives the properties as a dict.
+
+### Where the input comes from
+
+`in.json` is read on first use, not at import, and only once; `load_input()`
+returns it as a dict (pass `reload=True` to read it again). The module
+attributes `device` and `device_full` are built the first time a script uses
+them. By default the file is `in.json` in the working directory, where the
+sandbox puts it; set `LVI_SANDBOX_INPUT` to read another file, e.g. a saved
+`in.json` while developing a script outside a Playbook:
+
+```bash
+LVI_SANDBOX_INPUT=./samples/in.json python my_script.py
+```
+
+## Development and releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and
+[PUBLISHING.md](PUBLISHING.md) for how releases are published.

lvi_script_sandbox_utils-0.6.0/README.md

@@ -0,0 +1,107 @@
+# LogicVein Script Sandbox Utils
+
+Convenience helpers for Python scripts that LogicVein Playbooks run in the
+Script Sandbox container. They wrap the sandbox's file-and-stdout contract:
+a Playbook hands your script its inputs in `in.json`, and your script returns
+results by printing JSON to stdout.
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install lvi-script-sandbox-utils
+```
+
+From TestPyPI (pre-release / testing):
+
+```bash
+pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  lvi-script-sandbox-utils
+```
+
+The sandbox runs scripts in a container, so the package has to be available
+inside it. If your sandbox mounts a packages directory (for example
+`./packages:/packages`), install into it:
+
+```bash
+pip install --target ./packages lvi-script-sandbox-utils
+```
+
+The library has no third-party dependencies (standard library only).
+
+### Upgrading from 0.1.x
+
+0.1.x installed as `logicvein.lvi_script_sandbox_utils`. From 0.2.0 it is
+the top-level package `lvi_script_sandbox_utils`, so change
+
+```python
+from logicvein import lvi_script_sandbox_utils as lvi
+```
+
+to `import lvi_script_sandbox_utils as lvi`. The `logicvein` package is
+left to `lvi-api-client`: when both shipped a `logicvein/` directory,
+`pip install --target` skipped whichever was installed second (or, with
+`--upgrade`, deleted the first).
+
+## Usage
+
+```python
+import lvi_script_sandbox_utils as lvi
+
+device = lvi.get_device()
+output = lvi.get_input("cli_output", default="")  # "" in the Playbook's first script node
+
+lvi.flush_output(hostname=device.device_hostname, line_count=len(output.splitlines()))
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `load_input(path=None, reload=False)` | The whole `in.json` as a dict, read once and cached. Treat it as read-only. |
+| `get_input(input_type, default=...)` | Read an input from `in.json`. `"cli_output"` returns the previous node's result value; `"device"` returns the raw device dict. A missing input returns `default`, or raises `KeyError` if none was given; any other `input_type` raises `ValueError`. |
+| `get_global(name, default=...)` | One Playbook global's value, e.g. `get_global("hostname")`. A missing global returns `default`, or raises `KeyError` naming the globals that are set. |
+| `get_globals()` | Every Playbook global as `{name: value}`. |
+| `get_metadata()` | Details of this run as an object: `playbook`, `execution_id`, `executor`, `job_id`, `node`, `started_at`, and so on. |
+| `get_device(blank_none=True)` | The Playbook's device as an object with a basic set of properties (see below). |
+| `get_full_device(blank_none=True)` | Like `get_device()`, with the additional properties included (`uuid`, `lastBackup`, `severity`, `memoSummary`, ...). |
+| `set_output(key, value)` | Record a global for the next `flush_output()`. |
+| `flush_output(**kwargs)` | Print the `set_output()` values plus `kwargs` (which win on a clash) to stdout as Playbook global variables (`output.globals`), then clear the `set_output()` values. Device and metadata objects print as their fields. |
+| `flush_string_output(text)` | Print a string to stdout as base64-encoded raw output (`output.raw`). |
+
+On the device objects:
+
+- `hostname` and `network` are renamed to `device_hostname` and
+  `device_network`, so they don't collide with other Playbook variables.
+- `traits` lists the device's capabilities from `metaJson` (`ssh`, `snmp`,
+  `ncm`, ...); `customFields` is dropped, since it repeats `custom1`..`custom5`.
+- End-of-life/sale epochs (`endOfLife`, `endOfSale`, `softwareEndOfLife`,
+  `softwareEndOfSale`) become `YYYY-MM-DD` dates, and `lastBackup`,
+  `lastChange`, `lastDiscovery`, `lastTelemetry` become
+  `YYYY-MM-DDTHH:MM:SSZ` timestamps, all in UTC. `get_metadata().started_at`
+  is converted the same way.
+- `None` values become `""`; pass `blank_none=False` to keep `None`.
+- A property LogicVein doesn't send is simply absent from the object.
+
+`vars(device)` gives the properties as a dict.
+
+### Where the input comes from
+
+`in.json` is read on first use, not at import, and only once; `load_input()`
+returns it as a dict (pass `reload=True` to read it again). The module
+attributes `device` and `device_full` are built the first time a script uses
+them. By default the file is `in.json` in the working directory, where the
+sandbox puts it; set `LVI_SANDBOX_INPUT` to read another file, e.g. a saved
+`in.json` while developing a script outside a Playbook:
+
+```bash
+LVI_SANDBOX_INPUT=./samples/in.json python my_script.py
+```
+
+## Development and releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and
+[PUBLISHING.md](PUBLISHING.md) for how releases are published.

lvi_script_sandbox_utils-0.6.0/VERSION

@@ -0,0 +1 @@
+0.6.0

lvi_script_sandbox_utils-0.6.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lvi-script-sandbox-utils"
+dynamic = ["version"]
+description = "Convenience utilities for LogicVein Script Sandbox Python scripts"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+lvi_script_sandbox_utils = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.black]
+line-length = 120
+
+[tool.isort]
+line_length = 120
+profile = "black"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

lvi_script_sandbox_utils-0.6.0/setup.cfg

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

lvi_script_sandbox_utils-0.6.0/src/lvi_script_sandbox_utils/__init__.py

@@ -0,0 +1,307 @@
+"""Convenience utilities for LogicVein Script Sandbox scripts.
+
+A Playbook hands a script its inputs in `in.json` (in the working directory
+by default) and reads results from what the script prints to stdout.
+Nothing is read at import time: `in.json` is loaded on first use, once.
+"""
+
+import base64
+import copy
+import json
+import os
+from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version
+from types import SimpleNamespace
+from typing import Any, Dict, Optional
+
+try:
+    __version__ = version("lvi-script-sandbox-utils")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+INPUT_PATH_ENV = "LVI_SANDBOX_INPUT"
+DEFAULT_INPUT_PATH = "in.json"
+
+output: dict = {}
+_cache: Dict[str, Dict[str, Any]] = {}
+
+
+def input_path() -> str:
+    """Return the path `in.json` is read from.
+
+    Returns:
+        The `LVI_SANDBOX_INPUT` environment variable if set, else `in.json`
+        (relative to the working directory, where the sandbox puts it).
+    """
+    return os.environ.get(INPUT_PATH_ENV) or DEFAULT_INPUT_PATH
+
+
+def load_input(path: Optional[str] = None, reload: bool = False) -> Dict[str, Any]:
+    """Return the Playbook's inputs, reading the file once per path.
+
+    Args:
+        path: File to read; defaults to `input_path()`.
+        reload: Read the file again even if it was already loaded.
+
+    Returns:
+        The parsed `in.json`. It is shared and cached, so don't modify it;
+        the `get_*` functions return copies.
+
+    Raises:
+        FileNotFoundError: The file doesn't exist (e.g. running outside a
+            Playbook without `LVI_SANDBOX_INPUT` set).
+    """
+    path = path or input_path()
+    if reload or path not in _cache:
+        with open(path, "r", encoding="utf-8") as file:
+            _cache[path] = json.load(file)
+    return _cache[path]
+
+
+_MISSING: Any = object()
+
+# Device fields holding epoch milliseconds: calendar dates, and points in time.
+_DATE_FIELDS = ("endOfLife", "endOfSale", "softwareEndOfLife", "softwareEndOfSale")
+_TIMESTAMP_FIELDS = ("lastBackup", "lastChange", "lastDiscovery", "lastTelemetry")
+_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+# Device fields only get_full_device() returns; get_device() leaves them out.
+_FULL_ONLY_FIELDS = (
+    "backupElapsed",
+    "backupStatus",
+    "complianceState",
+    "lastBackup",
+    "lastChange",
+    "lastDiscovery",
+    "lastTelemetry",
+    "memoSummary",
+    "ncmEnabled",
+    "severity",
+    "sysObjectID",
+    "uuid",
+    "violationMessage",
+)
+
+
+def _output(**kwargs):
+    """Format kwargs into an output dict usable as Playbook vars."""
+    data = {"output": {"globals": {**kwargs}}}
+    return data
+
+
+def _raw_device() -> Dict[str, Any]:
+    data = load_input()
+    if "device" not in data:
+        raise KeyError("in.json has no 'device': the Playbook didn't pass a device to this script")
+    return data["device"]
+
+
+def _epoch_ms(value: Any, fmt: str) -> Any:
+    """Format epoch milliseconds in UTC, leaving anything else (None, "", 0) as is.
+
+    UTC, not the container's local time zone, so a date never shifts by a day.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value == 0:
+        return value
+    return datetime.fromtimestamp(value / 1000, tz=timezone.utc).strftime(fmt)
+
+
+def get_full_device(blank_none: bool = True) -> SimpleNamespace:
+    """Return mostly all device properties as an object.
+
+    Fields LogicVein doesn't send are simply absent; nothing here requires a
+    particular field to exist. `hostname` and `network` become
+    `device_hostname` and `device_network`, `metaJson`'s traits become
+    `traits`, and `customFields` (a copy of `custom1`..`custom5`) is dropped.
+    End-of-life/sale epochs become `YYYY-MM-DD` dates and the `last*`
+    epochs `YYYY-MM-DDTHH:MM:SSZ` timestamps, both in UTC.
+
+    Args:
+        blank_none: Turn `None` values into `""` for easier handling in the
+            Playbook. Pass False to keep `None`, so "not set" stays
+            distinguishable from an empty string.
+
+    Raises:
+        KeyError: `in.json` has no device.
+    """
+    # The JSON round trip is a deep copy, so the cached input is never changed.
+    device = json.loads(json.dumps(_raw_device()), object_hook=lambda d: SimpleNamespace(**d))
+    fields = vars(device)
+    meta = fields.pop("metaJson", None)
+    fields["traits"] = list(getattr(meta, "traits", None) or [])
+    fields.pop("customFields", None)
+    for old_name, new_name in (("hostname", "device_hostname"), ("network", "device_network")):
+        if old_name in fields:
+            fields[new_name] = fields.pop(old_name)
+    for field in _DATE_FIELDS:
+        if field in fields:
+            fields[field] = _epoch_ms(fields[field], "%Y-%m-%d")
+    for field in _TIMESTAMP_FIELDS:
+        if field in fields:
+            fields[field] = _epoch_ms(fields[field], _TIMESTAMP_FORMAT)
+    if blank_none:
+        for key, value in fields.items():
+            if value is None:
+                fields[key] = ""
+    return device
+
+
+def get_device(blank_none: bool = True) -> SimpleNamespace:
+    """Return a basic set of device properties as an object.
+
+    Args:
+        blank_none: As for `get_full_device()`.
+
+    Raises:
+        KeyError: `in.json` has no device.
+    """
+    device = get_full_device(blank_none)
+    for field in _FULL_ONLY_FIELDS:
+        vars(device).pop(field, None)
+    return device
+
+
+def get_input(input_type: str, default: Any = _MISSING) -> Any:
+    """Get input from the previous node.
+
+    Args:
+        input_type: `"cli_output"` for the previous node's result value, or
+            `"device"` for the raw device dict.
+        default: Returned when that input isn't in `in.json` (e.g.
+            `"cli_output"` in the Playbook's first script node). Without it,
+            a missing input raises `KeyError`.
+
+    Returns:
+        The input, as a copy.
+
+    Raises:
+        ValueError: `input_type` isn't one of the above; use `get_global()`
+            for other Playbook globals.
+        KeyError: The input is missing and no default was given.
+    """
+    data = load_input()
+    if input_type == "cli_output":
+        result = data.get("globals", {}).get("result")
+        value = result.get("value", _MISSING) if isinstance(result, dict) else _MISSING
+        missing = "no previous node result (globals.result)"
+    elif input_type == "device":
+        value = data.get("device", _MISSING)
+        missing = "no 'device'"
+    else:
+        raise ValueError(
+            f"Unknown input_type {input_type!r}: expected 'cli_output' or 'device'. "
+            "Use get_global() for other Playbook globals."
+        )
+    if value is _MISSING:
+        if default is _MISSING:
+            raise KeyError(f"in.json has {missing}")
+        return default
+    return copy.deepcopy(value)
+
+
+def _global_value(entry: Any) -> Any:
+    # in.json stores each global as {"type": ..., "value": ...}.
+    if isinstance(entry, dict) and "value" in entry:
+        return copy.deepcopy(entry["value"])
+    return copy.deepcopy(entry)
+
+
+def get_globals() -> Dict[str, Any]:
+    """Return every Playbook global passed to this script.
+
+    Returns:
+        `{name: value}`, with each global's `{"type", "value"}` wrapper
+        removed.
+    """
+    return {name: _global_value(entry) for name, entry in load_input().get("globals", {}).items()}
+
+
+def get_global(name: str, default: Any = _MISSING) -> Any:
+    """Return one Playbook global's value, e.g. `get_global("hostname")`.
+
+    Args:
+        name: The global's name.
+        default: Returned when the global isn't set. Without it, a missing
+            global raises `KeyError`.
+
+    Returns:
+        The global's value (its `{"type", "value"}` wrapper removed).
+
+    Raises:
+        KeyError: The global isn't set and no default was given.
+    """
+    playbook_globals = load_input().get("globals", {})
+    if name not in playbook_globals:
+        if default is _MISSING:
+            available = ", ".join(sorted(playbook_globals)) or "none"
+            raise KeyError(f"No Playbook global {name!r} (in.json has: {available})")
+        return default
+    return _global_value(playbook_globals[name])
+
+
+def get_metadata() -> SimpleNamespace:
+    """Return details of this Playbook run, e.g. `playbook`, `execution_id`, `executor`.
+
+    Returns:
+        The `metadata` section of `in.json` as an object; empty if absent.
+        `started_at` is a `YYYY-MM-DDTHH:MM:SSZ` UTC timestamp.
+    """
+    metadata = copy.deepcopy(load_input().get("metadata", {}))
+    if "started_at" in metadata:
+        metadata["started_at"] = _epoch_ms(metadata["started_at"], _TIMESTAMP_FORMAT)
+    return SimpleNamespace(**metadata)
+
+
+def _json_default(value: Any) -> Any:
+    # Device and metadata objects print as their fields.
+    if isinstance(value, SimpleNamespace):
+        return vars(value)
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def set_output(key: str, value: Any) -> None:
+    """Set a key and value in the global output dict, printed by the next `flush_output()`."""
+    output[key] = value
+
+
+def flush_output(**kwargs: Any) -> None:
+    """Print Playbook globals (`output.globals`) to stdout.
+
+    Args:
+        **kwargs: Globals to print, alongside any set with `set_output()`;
+            a keyword wins over a `set_output()` value of the same name.
+            Values must be JSON-serializable; device and metadata objects
+            are printed as their fields.
+
+    The `set_output()` values are cleared once printed.
+    """
+    data = _output(**{**output, **kwargs})
+    print(json.dumps(data, default=_json_default))
+    output.clear()
+
+
+def flush_string_output(text: Any) -> None:
+    """Put a string output in the output.raw field and send to stdout.
+
+    Args:
+        text: The raw output; anything else is converted with `str()`.
+    """
+    data = {"output": {"raw": base64.b64encode(f"{text}".encode("utf-8")).decode("utf-8")}}
+    print(json.dumps(data))
+
+
+_LAZY_ATTRIBUTES = {"device": get_device, "device_full": get_full_device}
+
+
+def __getattr__(name: str) -> Any:
+    """Build `device` and `device_full` on first access instead of at import.
+
+    The result is stored as a real module attribute, so later accesses (and
+    changes a script makes to it) see the same object, as when these were
+    built at import time.
+    """
+    if name in _LAZY_ATTRIBUTES:
+        value = _LAZY_ATTRIBUTES[name]()
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

lvi_script_sandbox_utils-0.6.0/src/lvi_script_sandbox_utils.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: lvi-script-sandbox-utils
+Version: 0.6.0
+Summary: Convenience utilities for LogicVein Script Sandbox Python scripts
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# LogicVein Script Sandbox Utils
+
+Convenience helpers for Python scripts that LogicVein Playbooks run in the
+Script Sandbox container. They wrap the sandbox's file-and-stdout contract:
+a Playbook hands your script its inputs in `in.json`, and your script returns
+results by printing JSON to stdout.
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install lvi-script-sandbox-utils
+```
+
+From TestPyPI (pre-release / testing):
+
+```bash
+pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  lvi-script-sandbox-utils
+```
+
+The sandbox runs scripts in a container, so the package has to be available
+inside it. If your sandbox mounts a packages directory (for example
+`./packages:/packages`), install into it:
+
+```bash
+pip install --target ./packages lvi-script-sandbox-utils
+```
+
+The library has no third-party dependencies (standard library only).
+
+### Upgrading from 0.1.x
+
+0.1.x installed as `logicvein.lvi_script_sandbox_utils`. From 0.2.0 it is
+the top-level package `lvi_script_sandbox_utils`, so change
+
+```python
+from logicvein import lvi_script_sandbox_utils as lvi
+```
+
+to `import lvi_script_sandbox_utils as lvi`. The `logicvein` package is
+left to `lvi-api-client`: when both shipped a `logicvein/` directory,
+`pip install --target` skipped whichever was installed second (or, with
+`--upgrade`, deleted the first).
+
+## Usage
+
+```python
+import lvi_script_sandbox_utils as lvi
+
+device = lvi.get_device()
+output = lvi.get_input("cli_output", default="")  # "" in the Playbook's first script node
+
+lvi.flush_output(hostname=device.device_hostname, line_count=len(output.splitlines()))
+```
+
+### Functions
+
+| Function | Purpose |
+|----------|---------|
+| `load_input(path=None, reload=False)` | The whole `in.json` as a dict, read once and cached. Treat it as read-only. |
+| `get_input(input_type, default=...)` | Read an input from `in.json`. `"cli_output"` returns the previous node's result value; `"device"` returns the raw device dict. A missing input returns `default`, or raises `KeyError` if none was given; any other `input_type` raises `ValueError`. |
+| `get_global(name, default=...)` | One Playbook global's value, e.g. `get_global("hostname")`. A missing global returns `default`, or raises `KeyError` naming the globals that are set. |
+| `get_globals()` | Every Playbook global as `{name: value}`. |
+| `get_metadata()` | Details of this run as an object: `playbook`, `execution_id`, `executor`, `job_id`, `node`, `started_at`, and so on. |
+| `get_device(blank_none=True)` | The Playbook's device as an object with a basic set of properties (see below). |
+| `get_full_device(blank_none=True)` | Like `get_device()`, with the additional properties included (`uuid`, `lastBackup`, `severity`, `memoSummary`, ...). |
+| `set_output(key, value)` | Record a global for the next `flush_output()`. |
+| `flush_output(**kwargs)` | Print the `set_output()` values plus `kwargs` (which win on a clash) to stdout as Playbook global variables (`output.globals`), then clear the `set_output()` values. Device and metadata objects print as their fields. |
+| `flush_string_output(text)` | Print a string to stdout as base64-encoded raw output (`output.raw`). |
+
+On the device objects:
+
+- `hostname` and `network` are renamed to `device_hostname` and
+  `device_network`, so they don't collide with other Playbook variables.
+- `traits` lists the device's capabilities from `metaJson` (`ssh`, `snmp`,
+  `ncm`, ...); `customFields` is dropped, since it repeats `custom1`..`custom5`.
+- End-of-life/sale epochs (`endOfLife`, `endOfSale`, `softwareEndOfLife`,
+  `softwareEndOfSale`) become `YYYY-MM-DD` dates, and `lastBackup`,
+  `lastChange`, `lastDiscovery`, `lastTelemetry` become
+  `YYYY-MM-DDTHH:MM:SSZ` timestamps, all in UTC. `get_metadata().started_at`
+  is converted the same way.
+- `None` values become `""`; pass `blank_none=False` to keep `None`.
+- A property LogicVein doesn't send is simply absent from the object.
+
+`vars(device)` gives the properties as a dict.
+
+### Where the input comes from
+
+`in.json` is read on first use, not at import, and only once; `load_input()`
+returns it as a dict (pass `reload=True` to read it again). The module
+attributes `device` and `device_full` are built the first time a script uses
+them. By default the file is `in.json` in the working directory, where the
+sandbox puts it; set `LVI_SANDBOX_INPUT` to read another file, e.g. a saved
+`in.json` while developing a script outside a Playbook:
+
+```bash
+LVI_SANDBOX_INPUT=./samples/in.json python my_script.py
+```
+
+## Development and releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and
+[PUBLISHING.md](PUBLISHING.md) for how releases are published.

lvi_script_sandbox_utils-0.6.0/src/lvi_script_sandbox_utils.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+VERSION
+pyproject.toml
+src/lvi_script_sandbox_utils/__init__.py
+src/lvi_script_sandbox_utils/py.typed
+src/lvi_script_sandbox_utils.egg-info/PKG-INFO
+src/lvi_script_sandbox_utils.egg-info/SOURCES.txt
+src/lvi_script_sandbox_utils.egg-info/dependency_links.txt
+src/lvi_script_sandbox_utils.egg-info/requires.txt
+src/lvi_script_sandbox_utils.egg-info/top_level.txt
+tests/test_device_data.py
+tests/test_inputs.py
+tests/test_loading.py
+tests/test_outputs.py
+tests/test_package.py

lvi_script_sandbox_utils-0.6.0/src/lvi_script_sandbox_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lvi_script_sandbox_utils-0.6.0/src/lvi_script_sandbox_utils.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest
+pytest-cov

lvi_script_sandbox_utils-0.6.0/src/lvi_script_sandbox_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+lvi_script_sandbox_utils

lvi_script_sandbox_utils-0.6.0/tests/test_device_data.py

@@ -0,0 +1,72 @@
+import json
+import time
+
+import pytest
+
+# 2026-10-27T00:30:00Z: shortly after midnight UTC, so a local-time conversion
+# west of UTC would land on the 26th.
+JUST_AFTER_MIDNIGHT_UTC = 1793061000000
+
+
+def write(path, data):
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def test_none_becomes_blank_by_default(lvi):
+    device = lvi.get_device()
+    assert device.custom3 == ""
+    assert device.endOfLife == ""
+
+
+def test_blank_none_false_keeps_none(lvi):
+    device = lvi.get_full_device(blank_none=False)
+    assert device.custom3 is None
+    assert device.endOfLife is None
+    assert lvi.get_device(blank_none=False).custom3 is None
+
+
+@pytest.fixture
+def los_angeles_time(monkeypatch):
+    monkeypatch.setenv("TZ", "America/Los_Angeles")
+    time.tzset()
+    yield
+    monkeypatch.undo()
+    time.tzset()
+
+
+def test_dates_use_utc(lvi, in_json, sample, los_angeles_time):
+    sample["device"]["endOfLife"] = JUST_AFTER_MIDNIGHT_UTC
+    write(in_json, sample)
+    assert lvi.get_device().endOfLife == "2026-10-27"
+
+
+def test_zero_date_left_alone(lvi, in_json, sample):
+    sample["device"]["endOfSale"] = 0
+    write(in_json, sample)
+    assert lvi.get_device().endOfSale == 0
+
+
+def test_timestamps_converted(lvi):
+    device = lvi.get_full_device()
+    assert device.lastBackup == "2026-10-27T16:00:10Z"
+    assert device.lastChange == "2026-10-15T12:00:11Z"
+
+
+def test_booleans_are_not_epochs(lvi):
+    assert lvi.get_full_device().ncmEnabled is True
+
+
+def test_traits_kept(lvi):
+    assert "ssh" in lvi.get_device().traits
+    assert "ssh" in lvi.get_full_device().traits
+
+
+@pytest.mark.parametrize("meta", [None, {}, {"traits": None}])
+def test_traits_without_meta(lvi, in_json, sample, meta):
+    sample["device"]["metaJson"] = meta
+    write(in_json, sample)
+    assert lvi.get_device().traits == []
+
+
+def test_metadata_started_at(lvi):
+    assert lvi.get_metadata().started_at == "2026-10-27T16:43:15Z"

lvi_script_sandbox_utils-0.6.0/tests/test_inputs.py

@@ -0,0 +1,84 @@
+import json
+
+import pytest
+
+
+def write(path, data):
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def test_cli_output_missing_raises_clear_error(lvi):
+    # The sample is a first script node: globals has no `result`.
+    with pytest.raises(KeyError, match="no previous node result"):
+        lvi.get_input("cli_output")
+
+
+def test_cli_output_default(lvi):
+    assert lvi.get_input("cli_output", default="") == ""
+
+
+def test_cli_output_present(lvi, in_json, sample):
+    sample["globals"]["result"] = {"type": "string", "value": "line 1\nline 2"}
+    write(in_json, sample)
+    assert lvi.get_input("cli_output") == "line 1\nline 2"
+
+
+def test_device_input_is_a_copy(lvi):
+    device = lvi.get_input("device")
+    device["hostname"] = "changed"
+    assert lvi.get_input("device")["hostname"] == "c1800"
+
+
+def test_unknown_input_type(lvi):
+    with pytest.raises(ValueError, match="get_global"):
+        lvi.get_input("hostname")
+
+
+def test_get_global_unwraps_value(lvi):
+    assert lvi.get_global("hostname") == "c1800"
+
+
+def test_get_global_missing(lvi):
+    with pytest.raises(KeyError, match="has: hostname"):
+        lvi.get_global("nope")
+    assert lvi.get_global("nope", None) is None
+
+
+def test_get_globals(lvi):
+    assert lvi.get_globals() == {"hostname": "c1800"}
+
+
+def test_get_metadata(lvi):
+    metadata = lvi.get_metadata()
+    assert metadata.playbook == "Script - Simple Load"
+    assert metadata.execution_id == 40723
+
+
+def test_get_metadata_absent(lvi, in_json, sample):
+    del sample["metadata"]
+    write(in_json, sample)
+    assert vars(lvi.get_metadata()) == {}
+
+
+def test_basic_and_full_device_fields(lvi):
+    basic = set(vars(lvi.get_device()))
+    full = set(vars(lvi.get_full_device()))
+    assert {"device_hostname", "device_network", "osVersion", "custom1"} <= basic
+    assert "uuid" in full and "uuid" not in basic
+    assert not {"hostname", "network", "metaJson", "customFields"} & full
+
+
+@pytest.mark.parametrize("field", ["uuid", "metaJson", "customFields", "hostname", "endOfLife"])
+def test_device_tolerates_missing_field(lvi, in_json, sample, field):
+    del sample["device"][field]
+    write(in_json, sample)
+    lvi.get_device()
+    lvi.get_full_device()
+
+
+def test_no_device(lvi, in_json, sample):
+    del sample["device"]
+    write(in_json, sample)
+    with pytest.raises(KeyError, match="no 'device'"):
+        lvi.get_device()
+    assert lvi.get_input("device", default=None) is None

lvi_script_sandbox_utils-0.6.0/tests/test_loading.py

@@ -0,0 +1,56 @@
+import importlib
+import json
+import sys
+
+import pytest
+
+
+def test_import_reads_nothing(tmp_path, monkeypatch):
+    # No in.json here: importing must still work (e.g. for tests or tooling).
+    monkeypatch.chdir(tmp_path)
+    sys.modules.pop("lvi_script_sandbox_utils", None)
+    module = importlib.import_module("lvi_script_sandbox_utils")
+    try:
+        assert "device" not in vars(module)
+        with pytest.raises(FileNotFoundError):
+            module.device
+    finally:
+        sys.modules.pop("lvi_script_sandbox_utils", None)
+
+
+def test_device_is_built_once(lvi):
+    assert lvi.device is lvi.device
+    lvi.device.note = "set by script"
+    assert lvi.device.note == "set by script"
+
+
+def test_unknown_attribute_still_raises(lvi):
+    with pytest.raises(AttributeError):
+        lvi.not_a_thing
+
+
+def test_file_is_read_once(lvi, in_json):
+    assert lvi.load_input()["device"]["hostname"] == "c1800"
+    in_json.write_text(json.dumps({"device": {}}), encoding="utf-8")
+    assert lvi.load_input()["device"]["hostname"] == "c1800"
+    assert lvi.load_input(reload=True)["device"] == {}
+
+
+def test_input_path_from_environment(lvi, tmp_path, monkeypatch, sample):
+    other = tmp_path / "other.json"
+    sample["device"]["hostname"] = "from-env"
+    other.write_text(json.dumps(sample), encoding="utf-8")
+    monkeypatch.setenv(lvi.INPUT_PATH_ENV, str(other))
+    assert lvi.input_path() == str(other)
+    assert lvi.device.device_hostname == "from-env"
+
+
+def test_explicit_path(lvi, in_json):
+    assert lvi.load_input(str(in_json))["metadata"]["playbook"] == "Script - Simple Load"
+
+
+def test_device_functions_do_not_change_cached_input(lvi):
+    lvi.get_device()
+    lvi.get_full_device()
+    device = lvi.load_input()["device"]
+    assert "hostname" in device and "metaJson" in device

lvi_script_sandbox_utils-0.6.0/tests/test_outputs.py

@@ -0,0 +1,39 @@
+import base64
+import json
+
+
+def printed(capsys):
+    return json.loads(capsys.readouterr().out)
+
+
+def test_flush_output(lvi, capsys):
+    lvi.flush_output(hostname="c1800", count=2)
+    assert printed(capsys) == {"output": {"globals": {"hostname": "c1800", "count": 2}}}
+
+
+def test_set_output_is_flushed_then_cleared(lvi, capsys):
+    lvi.set_output("a", 1)
+    lvi.set_output("b", 2)
+    lvi.flush_output(b=3)
+    assert printed(capsys) == {"output": {"globals": {"a": 1, "b": 3}}}
+    assert lvi.output == {}
+    lvi.flush_output()
+    assert printed(capsys) == {"output": {"globals": {}}}
+
+
+def test_device_objects_are_serialized(lvi, capsys):
+    lvi.flush_output(device=lvi.get_device(), run=lvi.get_metadata())
+    data = printed(capsys)["output"]["globals"]
+    assert data["device"]["device_hostname"] == "c1800"
+    assert data["run"]["execution_id"] == 40723
+
+
+def test_flush_string_output(lvi, capsys):
+    lvi.flush_string_output("hi\nthere")
+    raw = printed(capsys)["output"]["raw"]
+    assert base64.b64decode(raw).decode("utf-8") == "hi\nthere"
+
+
+def test_flush_string_output_converts_to_str(lvi, capsys):
+    lvi.flush_string_output(42)
+    assert base64.b64decode(printed(capsys)["output"]["raw"]) == b"42"

lvi_script_sandbox_utils-0.6.0/tests/test_package.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+
+def test_version_is_defined(lvi):
+    assert isinstance(lvi.__version__, str)
+
+
+def test_no_logicvein_package_is_shipped():
+    # A `logicvein/` directory would collide with lvi-api-client's on install.
+    assert not (Path(__file__).parents[1] / "src" / "logicvein").exists()
+
+
+def test_import_loads_device(lvi):
+    assert lvi.device.device_hostname == "c1800"
+    assert lvi.device_full.uuid == "00000000-0000-4000-8000-000000000001"