feat: add dry run mode for Python SDK

[leoparente]

This pull request introduces a new "dry run" mode for the Diode SDK, allowing users to generate ingestion requests without contacting a Diode server. It includes updates to the SDK's core functionality, documentation, and tests. The most important changes are grouped below by theme.

OUTPUT DATA

{"stream": "latest", "entities": [{"timestamp": "2025-06-10T13:11:08.754276Z", "vlan": {"site": {"name": "siteA"}, "vid": "1", "name": "default"}}, {"timestamp": "2025-06-10T13:11:08.754329Z", "vlan": {"site": {"name": "siteB"}, "vid": "1", "name": "default"}}], "id": "c9a00044-8dc7-47a1-8ed5-7f53e588fd9c","sdkName": "diode-sdk-python-dry-run", "sdkVersion": "0.0.0"}

New Dry Run Functionality:

• Added a new DiodeDryRunClient class that outputs ingestion requests to stdout or JSON files instead of sending them to a Diode server. This includes support for specifying an output directory via the DIODE_DRY_RUN_OUTPUT_DIR environment variable or the output_dir parameter. (netboxlabs/diode/sdk/client.py, netboxlabs/diode/sdk/client.pyR311-R381)
• Introduced the load_dryrun_entities function to read and parse entities from JSON files generated during dry runs. (netboxlabs/diode/sdk/client.py, netboxlabs/diode/sdk/client.pyR34-R55)

Documentation Updates:

• Updated the README.md to document the new DIODE_DRY_RUN_OUTPUT_DIR environment variable and provide examples of using DiodeDryRunClient and load_dryrun_entities. (README.md, [1] [2]

SDK Enhancements:

• Refactored the SDK to introduce a DiodeClientInterface protocol, which is implemented by both DiodeClient and DiodeDryRunClient. This ensures consistent behavior across client implementations. (netboxlabs/diode/sdk/client.pyi, netboxlabs/diode/sdk/client.pyiR1-R25)

Testing Improvements:

• Added comprehensive tests for the new dry run functionality, including verifying JSON output to stdout and files, and testing the load_dryrun_entities function with both generated and fixture-based JSON files. (tests/test_client.py, tests/test_client.pyR676-R757)
• Refactored existing tests to improve readability and maintain consistency with the new functionality. (tests/test_client.py, [1] [2]

Other Changes:

• Updated the SDK's __init__.py to expose DiodeDryRunClient and load_dryrun_entities as part of the public API. (netboxlabs/diode/sdk/__init__.py, netboxlabs/diode/sdk/init.pyL5-R13)

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
/opt/hostedtoolcache/Python/3.11.12/x64/lib/python3.11/site-packages/netboxlabs/diode/sdk
client.py	240	7	97%	102, 277, 337, 342, 346, 402, 430
TOTAL	274	7	97%

Tests	Skipped	Failures	Errors	Time
97	0 💤	0 ❌	0 🔥	1.211s ⏱️

[Copilot]

Pull Request Overview

Adds a “dry run” mode to the Python SDK so that ingestion requests can be generated locally without contacting a Diode server.

• Introduces DiodeDryRunClient and load_dryrun_entities for JSON output and reloading
• Updates public API exports and documentation (README)
• Adds comprehensive tests for dry-run functionality

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
netboxlabs/diode/sdk/client.py	Implements DiodeDryRunClient and load_dryrun_entities
netboxlabs/diode/sdk/client.pyi	Adds DiodeClientInterface protocol
netboxlabs/diode/sdk/init.py	Exposes dry-run classes in public API
tests/test_client.py	Adds tests for dry-run stdout/file output
README.md	Documents DIODE_DRY_RUN_OUTPUT_DIR and dry-run usage

Comments suppressed due to low confidence (2)

netboxlabs/diode/sdk/client.py:41

• [nitpick] The docstring mentions "concatenated JSON messages" but the function expects a single JSON object representing an IngestRequest. Consider updating the docstring to accurately describe the input format.

    """Yield entities from a file with concatenated JSON messages."""

netboxlabs/diode/sdk/client.py:40

• The function uses json.load but import json is missing at the top of the file, leading to a NameError at runtime. Add import json to the module imports.

def load_dryrun_entities(file_path: str | Path) -> Iterable[Entity]:

[mfiedorowicz]

🙇

[github-actions]

🎉 This PR is included in version 1.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀