iotrace 0.1.0__tar.gz

iotrace-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: iotrace
+Version: 0.1.0
+Summary: Python wrapper for NI IO Trace programmatic C API
+Keywords: ni,io-trace,iotrace,nitrace,ni-io-trace,nimi-python,nidcpower,nidmm,niscope,niswitch,nidigital,nidaqmx,nifgen,nirfsa,nirfsg,nise,ni-visa,pyVISA
+Author: Karsten van Zwol
+Author-email: Karsten van Zwol <karsten.van.zwol@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/ktvanzwol/nitrace
+Project-URL: Repository, https://github.com/ktvanzwol/nitrace
+Project-URL: Issues, https://github.com/ktvanzwol/nitrace/issues
+Description-Content-Type: text/markdown
+
+# NI IO Trace Python API
+
+A Python library for controlling [NI IO Trace](https://www.ni.com/docs/en-US/bundle/ni-io-trace/page/overview.html) programmatically. Launch the application, start and stop tracing, write log messages, and close IO Trace — all from Python.
+
+## Requirements
+
+- Windows
+- Python 3.10+
+- NI IO Trace installed (part of NI software distributions)
+  - [Where Can I Download NI I/O Trace?](https://knowledge.ni.com/KnowledgeArticleDetails?id=kA00Z000000kJcQSAU)
+
+## Installation
+
+Install from PyPI:
+
+```
+pip install iotrace
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```
+uv add iotrace
+```
+
+Or install directly from GitHub:
+
+```
+pip install git+https://github.com/ktvanzwol/nitrace.git
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+import iotrace
+
+# Launch the application (minimized by default)
+iotrace.launch_io_trace()
+
+# Start tracing to a NI IO Trace log file
+iotrace.start_tracing(
+    log_file_setting=iotrace.LogFileSetting.IO_TRACE,
+    file_path=Path.cwd() / "trace.nitrace",
+    file_write_mode=iotrace.FileWriteMode.CREATE_OR_OVERWRITE,
+)
+
+# Insert a marker into the trace log
+iotrace.log_message("Test started")
+
+# ... run your NI driver calls ...
+
+# Stop tracing and leave the application running to inspect the log.
+iotrace.stop_tracing()
+
+print("Trace complete. Log file saved to:", Path.cwd() / "trace.nitrace")
+```
+
+## CLI
+
+A command-line interface is included:
+
+```
+# Launch IO Trace and start tracing to a CSV file
+iotrace start --log-format csv --file trace.csv --write-mode overwrite
+
+# Stop tracing and close the application
+iotrace stop --close
+```
+
+### `iotrace start`
+
+| Option | Description |
+|---|---|
+| `--log-format` | Log file format: `none`, `io-trace`, `plain-text`, `csv`, `xml` (default: `none`). |
+| `--file` | Path to the log file. |
+| `--write-mode` | File write mode: `create`, `append`, `overwrite` (default: `create`). |
+
+### `iotrace stop`
+
+| Option | Description |
+|---|---|
+| `--close` | Close NI IO Trace after stopping. |
+
+## API Reference
+
+- **Functions:**
+  - [`get_application_path`](#get_application_path---path)
+  - [`launch_io_trace`](#launch_io_tracewindow_statewindowstateminimized---subprocesspopen)
+  - [`start_tracing`](#start_tracinglog_file_settinglogfilesettingno_file-file_pathnone-file_write_modefilewritemodecreate_only---none)
+  - [`stop_tracing`](#stop_tracing---none)
+  - [`log_message`](#log_messagemessage-str---none)
+  - [`close_io_trace`](#close_io_tracetimeout-float--100---none)
+- **Logging:**
+  - [`IOTraceHandler`](#iotracehandler)
+- **Enums:**
+  - [`LogFileSetting`](#logfilesetting)
+  - [`FileWriteMode`](#filewritemode)
+  - [`WindowState`](#windowstate)
+  - [`StatusCode`](#statuscode)
+- **Exceptions:**
+  - [`IoTraceError`](#iotraceerror)
+
+### Functions
+
+#### `get_application_path() -> Path`
+
+Return the filesystem path to the NI IO Trace executable.
+
+**Raises:** `IoTraceError` if NI IO Trace is not installed.
+
+---
+
+#### `launch_io_trace(window_state=WindowState.MINIMIZED) -> subprocess.Popen`
+
+Launch the NI IO Trace application and return the process handle. The application must be running before calling `start_tracing`, `stop_tracing`, `log_message`, or `close_io_trace`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `window_state` | `WindowState` | `MINIMIZED` | Initial window state of the application. |
+
+**Raises:** `RuntimeError` if the process exits immediately. `IoTraceError` if the application path cannot be resolved.
+
+---
+
+#### `start_tracing(log_file_setting=LogFileSetting.NO_FILE, file_path=None, file_write_mode=FileWriteMode.CREATE_ONLY) -> None`
+
+Start tracing NI driver calls. NI IO Trace must already be running.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `log_file_setting` | `LogFileSetting` | `NO_FILE` | Format of the log file. |
+| `file_path` | `str \| Path \| None` | `None` | Path to the log file. Required when `log_file_setting` is not `NO_FILE`. |
+| `file_write_mode` | `FileWriteMode` | `CREATE_ONLY` | How to handle an existing file. |
+
+**Raises:** `IoTraceError` if IO Trace is not running, the file already exists with `CREATE_ONLY`, or the settings are invalid.
+
+---
+
+#### `stop_tracing() -> None`
+
+Stop tracing NI driver calls. The application remains open and tracing can be restarted.
+
+**Raises:** `IoTraceError` if tracing was not active.
+
+---
+
+#### `log_message(message: str) -> None`
+
+Write a custom text entry into the active trace log. Useful for inserting markers to correlate driver calls with application events.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `message` | `str` | The text to write. |
+
+**Raises:** `IoTraceError` if the IO Trace application has been closed.
+
+---
+
+#### `close_io_trace(timeout: float = 10.0) -> None`
+
+Close the NI IO Trace application and wait for the process to exit. The application does not need to have been launched by `launch_io_trace` — it may have been started manually.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `float` | `10.0` | Maximum seconds to wait for the process to exit. |
+
+**Raises:** `IoTraceError` if the close command fails. `RuntimeError` if the process does not exit within the timeout.
+
+### Enums
+
+#### `LogFileSetting`
+
+| Member | Value | Description |
+|---|---|---|
+| `NO_FILE` | -1 | No log file; trace data visible only in the GUI. |
+| `IO_TRACE` | 0 | NI IO Trace binary format (`.iotrace`). |
+| `PLAIN_TEXT` | 1 | Human-readable plain-text file. |
+| `COMMA_SEPARATED` | 2 | Comma-separated values (CSV) file. |
+| `XML` | 3 | XML-formatted file. |
+
+#### `FileWriteMode`
+
+| Member | Value | Description |
+|---|---|---|
+| `CREATE_ONLY` | 0 | Create a new file. Raises `IoTraceError` if the file exists. |
+| `CREATE_OR_APPEND` | 1 | Append to an existing file or create a new one. |
+| `CREATE_OR_OVERWRITE` | 2 | Overwrite an existing file or create a new one. |
+
+#### `WindowState`
+
+| Member | Value | Description |
+|---|---|---|
+| `HIDDEN` | 0 | No visible window. |
+| `NORMAL` | 1 | Default (restored) window state. |
+| `MAXIMIZED` | 2 | Window maximized. |
+| `MINIMIZED` | 3 | Window minimized. |
+
+#### `StatusCode`
+
+| Member | Value | Description |
+|---|---|---|
+| `SUCCESS` | 0 | Call completed successfully. |
+| `FAILED_NO_EXECUTE` | -303200 | Command could not be executed. |
+| `FAILED_INCOMPATIBLE_STATE` | -303201 | Operation not valid in the current state. |
+| `FAILED_UNABLE_TO_OPEN_LOG_FILE` | -303202 | Could not open the specified log file. |
+| `FAILED_GUI_CLOSED` | -303203 | The IO Trace application is not running. |
+| `FAILED_INVALID_SETTINGS` | -303204 | Invalid tracing settings. |
+| `FAILED_BAD_PARAMETER` | -303205 | A parameter value is invalid. |
+| `FAILED_INTERNAL_FAILURE` | -303206 | An internal error occurred. |
+| `FAILED_INVALID_FILE_EXTENSION` | -303207 | The log file extension does not match the format. |
+| `FAILED_BUFFER_TOO_SMALL` | -303208 | The provided buffer is too small. |
+| `FAILED_FILE_ALREADY_EXISTS` | -303209 | The file already exists (with `CREATE_ONLY` mode). |
+
+### Logging
+
+#### `IOTraceHandler`
+
+`iotrace.logging.IOTraceHandler` is a [`logging.Handler`](https://docs.python.org/3/library/logging.html#handler-objects) subclass that forwards Python log records into the NI IO Trace log via `log_message`. If the IO Trace application is not running, the error is passed to `handleError`.
+
+```python
+import logging
+from iotrace.logging import IOTraceHandler
+
+logger = logging.getLogger("my_app")
+handler = IOTraceHandler()
+handler.setFormatter(logging.Formatter("[%(levelname)s] %(name)s - %(message)s"))
+logger.addHandler(handler)
+```
+
+See [`examples/logging_handler.py`](examples/logging_handler.py) for a complete runnable example.
+
+### Exceptions
+
+#### `IoTraceError`
+
+Raised when an API call returns a non-success status.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `status` | `StatusCode` | The status code that triggered the error. |
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

iotrace-0.1.0/README.md

@@ -0,0 +1,246 @@
+# NI IO Trace Python API
+
+A Python library for controlling [NI IO Trace](https://www.ni.com/docs/en-US/bundle/ni-io-trace/page/overview.html) programmatically. Launch the application, start and stop tracing, write log messages, and close IO Trace — all from Python.
+
+## Requirements
+
+- Windows
+- Python 3.10+
+- NI IO Trace installed (part of NI software distributions)
+  - [Where Can I Download NI I/O Trace?](https://knowledge.ni.com/KnowledgeArticleDetails?id=kA00Z000000kJcQSAU)
+
+## Installation
+
+Install from PyPI:
+
+```
+pip install iotrace
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```
+uv add iotrace
+```
+
+Or install directly from GitHub:
+
+```
+pip install git+https://github.com/ktvanzwol/nitrace.git
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+import iotrace
+
+# Launch the application (minimized by default)
+iotrace.launch_io_trace()
+
+# Start tracing to a NI IO Trace log file
+iotrace.start_tracing(
+    log_file_setting=iotrace.LogFileSetting.IO_TRACE,
+    file_path=Path.cwd() / "trace.nitrace",
+    file_write_mode=iotrace.FileWriteMode.CREATE_OR_OVERWRITE,
+)
+
+# Insert a marker into the trace log
+iotrace.log_message("Test started")
+
+# ... run your NI driver calls ...
+
+# Stop tracing and leave the application running to inspect the log.
+iotrace.stop_tracing()
+
+print("Trace complete. Log file saved to:", Path.cwd() / "trace.nitrace")
+```
+
+## CLI
+
+A command-line interface is included:
+
+```
+# Launch IO Trace and start tracing to a CSV file
+iotrace start --log-format csv --file trace.csv --write-mode overwrite
+
+# Stop tracing and close the application
+iotrace stop --close
+```
+
+### `iotrace start`
+
+| Option | Description |
+|---|---|
+| `--log-format` | Log file format: `none`, `io-trace`, `plain-text`, `csv`, `xml` (default: `none`). |
+| `--file` | Path to the log file. |
+| `--write-mode` | File write mode: `create`, `append`, `overwrite` (default: `create`). |
+
+### `iotrace stop`
+
+| Option | Description |
+|---|---|
+| `--close` | Close NI IO Trace after stopping. |
+
+## API Reference
+
+- **Functions:**
+  - [`get_application_path`](#get_application_path---path)
+  - [`launch_io_trace`](#launch_io_tracewindow_statewindowstateminimized---subprocesspopen)
+  - [`start_tracing`](#start_tracinglog_file_settinglogfilesettingno_file-file_pathnone-file_write_modefilewritemodecreate_only---none)
+  - [`stop_tracing`](#stop_tracing---none)
+  - [`log_message`](#log_messagemessage-str---none)
+  - [`close_io_trace`](#close_io_tracetimeout-float--100---none)
+- **Logging:**
+  - [`IOTraceHandler`](#iotracehandler)
+- **Enums:**
+  - [`LogFileSetting`](#logfilesetting)
+  - [`FileWriteMode`](#filewritemode)
+  - [`WindowState`](#windowstate)
+  - [`StatusCode`](#statuscode)
+- **Exceptions:**
+  - [`IoTraceError`](#iotraceerror)
+
+### Functions
+
+#### `get_application_path() -> Path`
+
+Return the filesystem path to the NI IO Trace executable.
+
+**Raises:** `IoTraceError` if NI IO Trace is not installed.
+
+---
+
+#### `launch_io_trace(window_state=WindowState.MINIMIZED) -> subprocess.Popen`
+
+Launch the NI IO Trace application and return the process handle. The application must be running before calling `start_tracing`, `stop_tracing`, `log_message`, or `close_io_trace`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `window_state` | `WindowState` | `MINIMIZED` | Initial window state of the application. |
+
+**Raises:** `RuntimeError` if the process exits immediately. `IoTraceError` if the application path cannot be resolved.
+
+---
+
+#### `start_tracing(log_file_setting=LogFileSetting.NO_FILE, file_path=None, file_write_mode=FileWriteMode.CREATE_ONLY) -> None`
+
+Start tracing NI driver calls. NI IO Trace must already be running.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `log_file_setting` | `LogFileSetting` | `NO_FILE` | Format of the log file. |
+| `file_path` | `str \| Path \| None` | `None` | Path to the log file. Required when `log_file_setting` is not `NO_FILE`. |
+| `file_write_mode` | `FileWriteMode` | `CREATE_ONLY` | How to handle an existing file. |
+
+**Raises:** `IoTraceError` if IO Trace is not running, the file already exists with `CREATE_ONLY`, or the settings are invalid.
+
+---
+
+#### `stop_tracing() -> None`
+
+Stop tracing NI driver calls. The application remains open and tracing can be restarted.
+
+**Raises:** `IoTraceError` if tracing was not active.
+
+---
+
+#### `log_message(message: str) -> None`
+
+Write a custom text entry into the active trace log. Useful for inserting markers to correlate driver calls with application events.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `message` | `str` | The text to write. |
+
+**Raises:** `IoTraceError` if the IO Trace application has been closed.
+
+---
+
+#### `close_io_trace(timeout: float = 10.0) -> None`
+
+Close the NI IO Trace application and wait for the process to exit. The application does not need to have been launched by `launch_io_trace` — it may have been started manually.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `float` | `10.0` | Maximum seconds to wait for the process to exit. |
+
+**Raises:** `IoTraceError` if the close command fails. `RuntimeError` if the process does not exit within the timeout.
+
+### Enums
+
+#### `LogFileSetting`
+
+| Member | Value | Description |
+|---|---|---|
+| `NO_FILE` | -1 | No log file; trace data visible only in the GUI. |
+| `IO_TRACE` | 0 | NI IO Trace binary format (`.iotrace`). |
+| `PLAIN_TEXT` | 1 | Human-readable plain-text file. |
+| `COMMA_SEPARATED` | 2 | Comma-separated values (CSV) file. |
+| `XML` | 3 | XML-formatted file. |
+
+#### `FileWriteMode`
+
+| Member | Value | Description |
+|---|---|---|
+| `CREATE_ONLY` | 0 | Create a new file. Raises `IoTraceError` if the file exists. |
+| `CREATE_OR_APPEND` | 1 | Append to an existing file or create a new one. |
+| `CREATE_OR_OVERWRITE` | 2 | Overwrite an existing file or create a new one. |
+
+#### `WindowState`
+
+| Member | Value | Description |
+|---|---|---|
+| `HIDDEN` | 0 | No visible window. |
+| `NORMAL` | 1 | Default (restored) window state. |
+| `MAXIMIZED` | 2 | Window maximized. |
+| `MINIMIZED` | 3 | Window minimized. |
+
+#### `StatusCode`
+
+| Member | Value | Description |
+|---|---|---|
+| `SUCCESS` | 0 | Call completed successfully. |
+| `FAILED_NO_EXECUTE` | -303200 | Command could not be executed. |
+| `FAILED_INCOMPATIBLE_STATE` | -303201 | Operation not valid in the current state. |
+| `FAILED_UNABLE_TO_OPEN_LOG_FILE` | -303202 | Could not open the specified log file. |
+| `FAILED_GUI_CLOSED` | -303203 | The IO Trace application is not running. |
+| `FAILED_INVALID_SETTINGS` | -303204 | Invalid tracing settings. |
+| `FAILED_BAD_PARAMETER` | -303205 | A parameter value is invalid. |
+| `FAILED_INTERNAL_FAILURE` | -303206 | An internal error occurred. |
+| `FAILED_INVALID_FILE_EXTENSION` | -303207 | The log file extension does not match the format. |
+| `FAILED_BUFFER_TOO_SMALL` | -303208 | The provided buffer is too small. |
+| `FAILED_FILE_ALREADY_EXISTS` | -303209 | The file already exists (with `CREATE_ONLY` mode). |
+
+### Logging
+
+#### `IOTraceHandler`
+
+`iotrace.logging.IOTraceHandler` is a [`logging.Handler`](https://docs.python.org/3/library/logging.html#handler-objects) subclass that forwards Python log records into the NI IO Trace log via `log_message`. If the IO Trace application is not running, the error is passed to `handleError`.
+
+```python
+import logging
+from iotrace.logging import IOTraceHandler
+
+logger = logging.getLogger("my_app")
+handler = IOTraceHandler()
+handler.setFormatter(logging.Formatter("[%(levelname)s] %(name)s - %(message)s"))
+logger.addHandler(handler)
+```
+
+See [`examples/logging_handler.py`](examples/logging_handler.py) for a complete runnable example.
+
+### Exceptions
+
+#### `IoTraceError`
+
+Raised when an API call returns a non-success status.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `status` | `StatusCode` | The status code that triggered the error. |
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

iotrace-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "iotrace"
+version = "0.1.0"
+description = "Python wrapper for NI IO Trace programmatic C API"
+readme = "README.md"
+authors = [
+    { name = "Karsten van Zwol", email = "karsten.van.zwol@gmail.com" }
+]
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = []
+keywords = ["ni", "io-trace", "iotrace", "nitrace", "ni-io-trace", "nimi-python", "nidcpower", "nidmm", "niscope", "niswitch", "nidigital", "nidaqmx", "nifgen", "nirfsa", "nirfsg", "nise", "ni-visa", "pyVISA"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Testing",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/ktvanzwol/nitrace"
+Repository = "https://github.com/ktvanzwol/nitrace"
+Issues = "https://github.com/ktvanzwol/nitrace/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[project.scripts]
+iotrace = "iotrace.__cli__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.11.0",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.pytest.ini_options]
+markers = [
+    "system: tests that require NI IO Trace to be installed",
+]
+
+[tool.ruff.format]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.coverage.run]
+source = ["iotrace"]
+
+[tool.coverage.report]
+omit = ["tests/*"]

iotrace-0.1.0/src/iotrace/__cli__.py

@@ -0,0 +1,75 @@
+import argparse
+import sys
+
+import iotrace
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="iotrace",
+        description="Control NI IO Trace from the command line.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # start
+    start_parser = subparsers.add_parser("start", help="Start tracing driver calls.")
+    start_parser.add_argument(
+        "--log-format",
+        choices=["none", "io-trace", "plain-text", "csv", "xml"],
+        default="none",
+        help="Log file format (default: none).",
+    )
+    start_parser.add_argument(
+        "--file",
+        default=None,
+        help="Path to the log file.",
+    )
+    start_parser.add_argument(
+        "--write-mode",
+        choices=["create", "append", "overwrite"],
+        default="create",
+        help="File write mode (default: create).",
+    )
+
+    # stop
+    stop_parser = subparsers.add_parser("stop", help="Stop tracing driver calls.")
+    stop_parser.add_argument(
+        "--close",
+        action="store_true",
+        help="Close NI IO Trace after stopping.",
+    )
+
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "start":
+            iotrace.launch_io_trace(window_state=iotrace.WindowState.MINIMIZED)
+            log_format_map = {
+                "none": iotrace.LogFileSetting.NO_FILE,
+                "io-trace": iotrace.LogFileSetting.IO_TRACE,
+                "plain-text": iotrace.LogFileSetting.PLAIN_TEXT,
+                "csv": iotrace.LogFileSetting.COMMA_SEPARATED,
+                "xml": iotrace.LogFileSetting.XML,
+            }
+            write_mode_map = {
+                "create": iotrace.FileWriteMode.CREATE_ONLY,
+                "append": iotrace.FileWriteMode.CREATE_OR_APPEND,
+                "overwrite": iotrace.FileWriteMode.CREATE_OR_OVERWRITE,
+            }
+            iotrace.start_tracing(
+                log_file_setting=log_format_map[args.log_format],
+                file_path=args.file,
+                file_write_mode=write_mode_map[args.write_mode],
+            )
+            print("Tracing started.")
+
+        elif args.command == "stop":
+            iotrace.stop_tracing()
+            print("Tracing stopped.")
+            if args.close:
+                iotrace.close_io_trace()
+                print("NI IO Trace closed.")
+
+    except iotrace.IoTraceError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)

iotrace-0.1.0/src/iotrace/__init__.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import ctypes
+import enum
+import subprocess
+import time
+from pathlib import Path
+
+__all__ = [
+    "LogFileSetting",
+    "FileWriteMode",
+    "WindowState",
+    "StatusCode",
+    "IoTraceError",
+    "get_application_path",
+    "launch_io_trace",
+    "start_tracing",
+    "stop_tracing",
+    "log_message",
+    "close_io_trace",
+]
+
+
+class LogFileSetting(enum.IntEnum):
+    """Controls the log file format used when tracing.
+
+    Members:
+        NO_FILE: Do not write a log file. Trace data is only visible in the
+            NI IO Trace GUI.
+        IO_TRACE: Write an NI IO Trace binary log file (``.nitrace``).
+        PLAIN_TEXT: Write a human-readable plain-text log file.
+        COMMA_SEPARATED: Write a comma-separated values (CSV) log file.
+        XML: Write an XML-formatted log file.
+    """
+
+    NO_FILE = -1
+    IO_TRACE = 0
+    PLAIN_TEXT = 1
+    COMMA_SEPARATED = 2
+    XML = 3
+
+
+class FileWriteMode(enum.IntEnum):
+    """Controls how the log file is created or opened.
+
+    Members:
+        CREATE_ONLY: Create a new file. Raises :class:`IoTraceError` if the
+            file already exists.
+        CREATE_OR_APPEND: Open an existing file and append to it, or create a
+            new file if it does not exist.
+        CREATE_OR_OVERWRITE: Overwrite an existing file, or create a new file
+            if it does not exist.
+    """
+
+    CREATE_ONLY = 0
+    CREATE_OR_APPEND = 1
+    CREATE_OR_OVERWRITE = 2
+
+
+class WindowState(enum.IntEnum):
+    """Controls the window state of the NI IO Trace application at launch.
+
+    Members:
+        HIDDEN: Launch the application with no visible window.
+        NORMAL: Launch the application in its default (restored) window state.
+        MAXIMIZED: Launch the application with the window maximized.
+        MINIMIZED: Launch the application with the window minimized.
+    """
+
+    HIDDEN = 0
+    NORMAL = 1
+    MAXIMIZED = 2
+    MINIMIZED = 3
+
+
+class StatusCode(enum.IntEnum):
+    """Status codes returned by NI IO Trace API calls.
+
+    ``SUCCESS`` indicates the call completed without error. All other members
+    represent error conditions and are used to populate
+    :attr:`IoTraceError.status`.
+    """
+
+    SUCCESS = 0
+    FAILED_NO_EXECUTE = -303200
+    FAILED_INCOMPATIBLE_STATE = -303201
+    FAILED_UNABLE_TO_OPEN_LOG_FILE = -303202
+    FAILED_GUI_CLOSED = -303203
+    FAILED_INVALID_SETTINGS = -303204
+    FAILED_BAD_PARAMETER = -303205
+    FAILED_INTERNAL_FAILURE = -303206
+    FAILED_INVALID_FILE_EXTENSION = -303207
+    FAILED_BUFFER_TOO_SMALL = -303208
+    FAILED_FILE_ALREADY_EXISTS = -303209
+
+
+class IoTraceError(Exception):
+    """Raised when an NI IO Trace API call returns a non-success status.
+
+    Attributes:
+        status: The :class:`CommandStatus` that triggered the error.
+    """
+
+    def __init__(self, status: StatusCode) -> None:
+        self.status = status
+        super().__init__(f"NI IO Trace API error: {status.name} ({status.value})")
+
+
+def _check(status_code: int) -> None:
+    status = StatusCode(status_code)
+    if status != StatusCode.SUCCESS:
+        raise IoTraceError(status)
+
+
+def _load_dll() -> ctypes.WinDLL:
+    dll = ctypes.WinDLL("NiSpyLog")
+
+    # nispy_GetApplicationPath(char*, size_t) -> int
+    dll.nispy_GetApplicationPath.argtypes = [ctypes.c_char_p, ctypes.c_size_t]
+    dll.nispy_GetApplicationPath.restype = ctypes.c_int
+
+    # nispy_StartSpying(int, const char*, int) -> int
+    dll.nispy_StartSpying.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int]
+    dll.nispy_StartSpying.restype = ctypes.c_int
+
+    # nispy_StopSpying(void) -> int
+    dll.nispy_StopSpying.argtypes = []
+    dll.nispy_StopSpying.restype = ctypes.c_int
+
+    # nispy_WriteTextEntry(const char*) -> int
+    dll.nispy_WriteTextEntry.argtypes = [ctypes.c_char_p]
+    dll.nispy_WriteTextEntry.restype = ctypes.c_int
+
+    # nispy_CloseSpy(void) -> int
+    dll.nispy_CloseSpy.argtypes = []
+    dll.nispy_CloseSpy.restype = ctypes.c_int
+
+    return dll
+
+
+_dll: ctypes.WinDLL | None = None
+
+
+def _get_dll() -> ctypes.WinDLL:
+    global _dll
+    if _dll is None:
+        _dll = _load_dll()
+    return _dll
+
+
+def get_application_path() -> Path:
+    """Return the filesystem path to the NI IO Trace executable.
+
+    Returns:
+        A :class:`~pathlib.Path` pointing to the executable.
+
+    Raises:
+        IoTraceError: If NI IO Trace is not installed.
+    """
+    buf_size = 1024
+    buf = ctypes.create_string_buffer(buf_size)
+    _check(_get_dll().nispy_GetApplicationPath(buf, buf_size))
+    return Path(buf.value.decode())
+
+
+_WINDOW_STATE_ARGS: dict[WindowState, list[str]] = {
+    WindowState.HIDDEN: ["/hidden"],
+    WindowState.NORMAL: [],
+    WindowState.MAXIMIZED: ["/maximized"],
+    WindowState.MINIMIZED: ["/minimized"],
+}
+
+
+def launch_io_trace(
+    window_state: WindowState = WindowState.MINIMIZED,
+) -> subprocess.Popen:
+    """Launch the NI IO Trace application and return the process handle.
+
+    The application must be running before calls to :func:`start_tracing`,
+    :func:`stop_tracing`, :func:`log_message`, or :func:`close_io_trace` can
+    succeed.
+
+    Args:
+        window_state: The initial window state of the application. Defaults to
+            :attr:`WindowState.MINIMIZED`.
+
+    Returns:
+        The :class:`~subprocess.Popen` instance for the launched process.
+
+    Raises:
+        RuntimeError: If the process exits immediately after being started.
+        IoTraceError: If the application path cannot be resolved.
+    """
+    app_path = get_application_path()
+    cmd = [str(app_path), *_WINDOW_STATE_ARGS[window_state]]
+    process = subprocess.Popen(cmd)
+
+    if process.poll() is not None:
+        raise RuntimeError(f"NI IO Trace exited immediately with code {process.returncode}")
+
+    # Try to start a tracing session to verify that the application is ready to accept commands.
+    # If this fails, wait a moment and try again, as the application may still be finishing its launch process.
+    # This typically happens when the application is launched for the first time.
+    for _ in range(3):
+        try:
+            start_tracing()  # Test that we can communicate with the application
+            stop_tracing()  # Stop the test tracing session immediately
+            break  # Success, exit the loop
+        except IoTraceError as _:
+            time.sleep(1)  # Wait a moment for the application to finish launching
+    else:
+        raise RuntimeError("NI IO Trace failed to respond after multiple attempts")
+
+    return process
+
+
+def start_tracing(
+    log_file_setting: LogFileSetting = LogFileSetting.NO_FILE,
+    file_path: str | Path | None = None,
+    file_write_mode: FileWriteMode = FileWriteMode.CREATE_ONLY,
+) -> None:
+    """Start tracing NI driver calls.
+
+    NI IO Trace must already be running (see :func:`launch_io_trace`) before
+    calling this function.
+
+    Args:
+        log_file_setting: The format of the log file to write. Use
+            :attr:`LogFileSetting.NO_FILE` to trace without writing a file.
+        file_path: The path to the log file. Required when *log_file_setting*
+            is not :attr:`LogFileSetting.NO_FILE`. Can be a string or
+            :class:`~pathlib.Path`.
+        file_write_mode: How to handle an existing file at *file_path*.
+
+    Raises:
+        IoTraceError: If the call fails (e.g. IO Trace is not running,
+            the file already exists with :attr:`FileWriteMode.CREATE_ONLY`,
+            or the settings are invalid).
+    """
+    path_bytes = str(file_path).encode() if file_path is not None else None
+    _check(_get_dll().nispy_StartSpying(int(log_file_setting), path_bytes, int(file_write_mode)))
+
+
+def stop_tracing() -> None:
+    """Stop tracing NI driver calls.
+
+    Tracing must have been started with :func:`start_tracing` before calling
+    this function. The NI IO Trace application remains open and can be
+    restarted with another call to :func:`start_tracing`.
+
+    Raises:
+        IoTraceError: If tracing was not active.
+    """
+    _check(_get_dll().nispy_StopSpying())
+
+
+def log_message(message: str) -> None:
+    """Write a custom text entry into the active NI IO Trace log.
+
+    This is useful for inserting markers or annotations into a trace session
+    to correlate driver calls with application-level events.
+
+    Args:
+        message: The text to write. Will be UTF-8 encoded.
+
+    Raises:
+        IoTraceError: If the IO Trace application has been closed.
+    """
+    _check(_get_dll().nispy_WriteTextEntry(message.encode()))
+
+
+def _find_process_ids(exe_name: str) -> list[int]:
+    """Return PIDs of all running processes matching *exe_name*."""
+    result = subprocess.run(
+        ["tasklist", "/FI", f"IMAGENAME eq {exe_name}", "/FO", "CSV", "/NH"],
+        capture_output=True,
+        text=True,
+    )
+    pids: list[int] = []
+    for line in result.stdout.splitlines():
+        parts = line.strip().strip('"').split('","')
+        if len(parts) >= 2 and parts[0].lower() == exe_name.lower():
+            pids.append(int(parts[1]))
+    return pids
+
+
+def _wait_for_process_exit(exe_name: str, timeout: float) -> None:
+    """Block until no processes named *exe_name* are running, or *timeout* expires."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not _find_process_ids(exe_name):
+            return
+        time.sleep(0.25)
+    raise RuntimeError(f"{exe_name} did not exit within {timeout} seconds")
+
+
+def close_io_trace(timeout: float = 10.0) -> None:
+    """Close the NI IO Trace application and wait for the process to exit.
+
+    Sends the close command and then polls until the NI IO Trace process is
+    no longer running. The application does not need to have been launched by
+    :func:`launch_io_trace` — it may have been started manually.
+
+    After this call, the application must be relaunched before any further
+    tracing can occur.
+
+    Args:
+        timeout: Maximum number of seconds to wait for the process to exit.
+
+    Raises:
+        IoTraceError: If the close command fails.
+        RuntimeError: If the process does not exit within *timeout* seconds.
+    """
+    exe_name = get_application_path().name
+    _check(_get_dll().nispy_CloseSpy())
+    _wait_for_process_exit(exe_name, timeout)

iotrace-0.1.0/src/iotrace/logging.py

@@ -0,0 +1,22 @@
+"""Logging integration for NI IO Trace."""
+
+import logging
+
+from iotrace import IoTraceError, log_message
+
+__all__ = ["IOTraceHandler"]
+
+
+class IOTraceHandler(logging.Handler):
+    """A logging handler that writes log records into the NI IO Trace log.
+
+    Each log record is formatted and passed to :func:`iotrace.log_message`,
+    making Python log entries appear in the IO Trace log alongside NI driver
+    calls.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            log_message(self.format(record))
+        except IoTraceError:
+            self.handleError(record)