Metadata-Version: 2.4
Name: tokamunch-pyuda-datasource
Version: 0.2.0
Summary: Pyuda tokamap data source plugin for tokamunch
Author-email: Stephen Dixon <stephen.dixon@ukaea.uk>
License: MIT
Project-URL: Homepage, https://github.com/stephen-dixon/tokamunch-pyuda-datasource
Project-URL: Repository, https://github.com/stephen-dixon/tokamunch-pyuda-datasource
Project-URL: Issues, https://github.com/stephen-dixon/tokamunch-pyuda-datasource/issues
Keywords: tokamap,libtokamap,pyuda,tokamunch,mappings
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: tokamunch>=0.3.0
Requires-Dist: pyuda
Requires-Dist: typing-extensions
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# tokamunch-pyuda-datasource

![Logo](./docs/logo.png)

Python data source plugin for [tokamunch](https://github.com/stephen-dixon/tokamunch/tree/main).
Fetches data from a UDA server via [pyuda](https://github.com/ukaea/pyuda).

Available on [PyPI](https://pypi.org/project/tokamunch-pyuda-datasource/).

---

## Installation

```sh
pip install tokamunch
pip install tokamunch-pyuda-datasource
```

---

## Configuration

Register the plugin in your `munchi.toml` and supply the connection args. The
table key is the data-source name used in your libtokamap mapping files.

```toml
[data_sources.UDA]
plugin = "tokamunch_pyuda_datasource"
enabled = true

args.host = "localhost"
args.port = 56565
args.plugin_name = "UDA"
```

| Arg | Type | Description |
|---|---|---|
| `host` | string | UDA server hostname or IP (required) |
| `port` | int | UDA server port (required) |
| `plugin_name` | string | UDA plugin name, e.g. `"UDA"` or `"GEOMETRY"` (required) |
| `function` | string | UDA plugin function, defaults to `"get"` |

Any other key in `args` becomes a default for the per-call UDA query args, which
an individual mapping can override.

---

## Mapping example

Per-call arguments come from the mapping's `ARGS` block, plus the runtime
attributes tokamunch passes to `Mapper.map` (notably `shot`):

```json
"ip/data": {
    "MAP_TYPE": "DATA_SOURCE",
    "DATA_SOURCE": "UDA",
    "ARGS": {
        "signal": "AMC_PLASMA CURRENT"
    }
}
```

| Arg | Description |
|---|---|
| `signal` | UDA signal name (required) |
| `source` | Shot/pulse number; defaults to the runtime `shot` |
| `host` / `port` | Default to the config values; override per mapping if needed |
| `time` | If truthy, returns the time dimension instead of the data |
| `error` | If truthy, returns the error dimension instead of the data |

Any additional key/value pairs are passed through as UDA query parameters.

---

## Args: config vs per-call

- **Config args** (`host`, `port`, `plugin_name`, `function`) are set once when the
  plugin is constructed from `munchi.toml`.
- **Per-call args** (`signal`, `source`, and any extra UDA query parameters) are
  supplied per mapping call by the tokamunch mapping engine.

`host` and `port` are forwarded into every UDA query from the plugin config, so
mapping files no longer need to repeat them in their `ARGS` blocks. `source`
falls back to the runtime `shot` when the mapping does not set it. Both remain
overridable per mapping.

---

## Notes on thread safety

**This plugin is not thread-safe.** `pyuda.Client` stores server and port as class-level
attributes, so concurrent threads sharing a process will interfere with each other.
The plugin re-applies its own server/port under a lock before each request — which
keeps several data sources (e.g. `UDA` and `GEOMETRY` on different ports) correct
within one process — but pyuda itself offers no thread-safety guarantee. Use
`run.concurrency.mode = "process"` if you need parallel requests.

| Property | Value |
|---|---|
| Thread-safe | No |
| Process-safe | Yes |
| Reentrant | No |
| Deterministic | No |
| Cacheable | No |
| Requires network | Yes |
