---
name: pytools
description: >-
  CI Server R1.05 pyTOOLS: Python scripts that use the `dss` module (dss.pyd) to read or change
  CI Server data. Use when the user wants to install or set up Python for CI Server (64-bit
  Python 3.12, PYTHONPATH, import dss), write a Python script that connects to DSS
  (dss.connect, logon, logout, close), lists datasets or fields, opens a dataset and reads
  records (readNext, readEqual, readRecords, ITEM_VAL, ITEM_DF, LOCAL_NODE_DF), reads item
  history or aggregates from Python (getItemHistory, getHisGroupItems, interpolation, AGGR_MAX,
  aggr_period), filters or sorts records (createFilter, activateFilter, filter expression,
  setIndex, getIndex), waits for value or record changes (datasetEventNotify,
  recordEventNotify, eventRead), inserts, updates or deletes records or locks them
  (insertRecord, updateRecord, deleteRecord, lockRecords), sends or receives BUS Service
  messages (busSetName, busSend, busReceive, busSnap, durstp a script), converts DSS times
  (dateString, dateDSS, dateRelDSS, dateConvert), handles dss.error / DSS-E-EOS /
  PY_DSS_* exceptions, or checks the server side (DSSSDAPY, PYDSS, dssana.sup Python Interface
  login method). Source IM 36K10P40-01EN (new in R1.04).
---

# pyTOOLS (R1.05)

pyTOOLS is the Python module `dss` (`%TLS_ROOT_PATH%\tls\exe\dss.pyd`). A script attaches to the
BUS Service and DSS **of the local node** (CI Core or CI Portal; not CI View) and works with
datasets like any other DSS client. Item history has two fast functions that go straight to
ITEM Service.

Written 2026-10-09 for R1.05. **No Python is installed on the R1.05 test server**, so no script
was run there: all tasks are *from docs, not tested*. Checked read-only on the R1.05 test server:
`dss.pyd` (module 3.6.1), the dedicated DSS server `DSSSDAPY`, the `dss.sup` routing and the
*Python Interface* login lines in `dssana.sup`. On the development machine (R1.03) the R1.03
module imports under Python 3.12 (`version()`, `busGetDirs()`).

Background: `knowledge/manuals/IM36K10P40-01EN.md` (every function, filter syntax, exceptions).
Known issues: `knowledge/manuals/IM36K01A50-01EN.md`. Server side of DSS: skill
`system-management` (`tasks/dss-tools.md`). Login methods: skill `authorization`
(`tasks/login-methods.md`).

Rules for every task:
- Run the `system-check` skill first. pyTOOLS is a product function from R1.04; R1.03 ships an
  older, undocumented `dss.pyd` without the dedicated server — do not rely on it.
- Installing Python, setting the system variable `PYTHONPATH` and changing `dssana.sup` need
  administrator rights: hand them to the user (direct vs prepare only as agreed).
- Log on as a CI Server user with only the rights the script needs (pyTOOLS supports only the
  *Manual CI Server* login method). Never hard-code a real password in a file in the repo; read
  it from an environment variable or prompt (`getpass`).
- Scripts that write (insert / update / delete / lock) change the running system and are
  recorded in the audit trail (source `PYTOOLS`): only on test systems or with the user's
  approval. Prefer read-only modes (`'r'`).
- Always stop event notifications, close datasets and `dss.close(conn)` in a `finally:` block;
  a script left running keeps a BUS process (`PYDSS_<n>`) and a DSS session.
- Run scripts from a scratch folder; examples use `CI-Eng-Sample` names
  (`examples/CI-Eng-Sample/`), replace them with `<Section>.<Tag>` names of the user's system.

| Task | File | Status |
|---|---|---|
| Set up Python and pyTOOLS, check the server side, first read-only script (version, `LOCAL_NODE_DF`, one item value) | `tasks/setup-first-script.md` | from docs, not tested (no Python on the R1.05 test server); server-side files verified read-only 2026-10-09 |
| Read items (`ITEM_VAL`, `ITEM_DF`) and item history / aggregates (`getItemHistory`) | `tasks/read-items-history.md` | from docs, not tested (no Python on the R1.05 test server) |
| Filter and sort records (filter expressions, indexes) | `tasks/filter-index.md` | from docs, not tested (no Python on the R1.05 test server) |
| Wait for changes: event notification on records or datasets | `tasks/event-notification.md` | from docs, not tested (no Python on the R1.05 test server) |
| Insert, update, delete and lock records | `tasks/modify-datasets.md` | from docs, not tested (writes; no Python on the R1.05 test server) |

BUS Service messages (`busSend`, `busReceive`, `busReply`, `busSnap`, stopping a named script
with `durstp`), date/time helpers and setup-file reading are described in the manual summary
(§3.11, §3.12, §3.14); no task file yet.