pycontrol-gui 3.0.0a1__tar.gz

pycontrol_gui-3.0.0a1/.gitignore

@@ -0,0 +1,29 @@
+### macOS
+# Finder metadata
+.DS_Store
+
+# Thumbnails
+._*
+
+# Custom folder icons
+Icon
+
+# Volume root files
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+### Python / uv
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

pycontrol_gui-3.0.0a1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: pycontrol-gui
+Version: 3.0.0a1
+Summary: Qt desktop frontend for pycontrol-core.
+Author: Karpova Lab contributors
+License: GPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: pycontrol-core<3.1,>=3.0.0a1
+Requires-Dist: pyqtgraph>=0.13.7
+Requires-Dist: pyside6>=6.8
+Provides-Extra: test
+Requires-Dist: pytest-qt>=4.4; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pycontrol-gui
+
+`pycontrol-gui` is the Qt desktop frontend for `pycontrol-core`.
+
+It provides the main pyControl operator workflows:
+
+- Run one task on one setup.
+- Edit and run multi-subject experiments.
+- Manage setup names, ports, auto-detected MCU cache, and setup variables.
+- View live logs and plots.
+- Use workspace task extensions, experiment extensions, task plotters, task
+  controls, and extension settings.
+
+## Install From PyPI Alpha
+
+For the `3.0.0a1` alpha, pin the prerelease:
+
+```bash
+uv add "pycontrol-gui==3.0.0a1"
+# or
+pip install --pre "pycontrol-gui==3.0.0a1"
+```
+
+To accept the newest available alpha with uv, use:
+
+```bash
+uv add pycontrol-gui --prerelease allow
+```
+
+## Install For Development
+
+Install the sibling core package first:
+
+```bash
+cd ../pycontrol-core
+pip install -e ".[test,lint]"
+
+cd ../pycontrol-gui
+pip install -e ".[test]"
+```
+
+With `uv`, `pycontrol-gui/pyproject.toml` points `pycontrol-core` at the
+sibling `../pycontrol-core` path.
+
+Run the app:
+
+```bash
+pycontrol-gui
+pycontrol-gui /path/to/workspace
+# or
+python -m pycontrol_gui
+python -m pycontrol_gui /path/to/workspace
+```
+
+Run tests with Python's module form so stale local script shebangs do not get in
+the way:
+
+```bash
+uv run python -m pytest
+```
+
+## Workspaces
+
+Open a workspace with **Workspace -> Open Workspace...**, create one with
+**Workspace -> New Workspace...**, or pass a workspace path on the command line.
+If no path is supplied, the GUI uses the last-opened workspace from application
+preferences, then falls back to discovering a workspace from the current working
+directory. Use **Workspace -> Reload workspace** to refresh selectors after
+external file changes.
+
+The GUI uses the standard `pycontrol-core` workspace layout:
+
+| Path | GUI use |
+| --- | --- |
+| `tasks/` | Task selector in Run task and Experiments. |
+| `hardware_definitions/` | Hardware-definition selector and setup validation. |
+| `devices/` | Workspace-local device drivers for task sharing and setup maintenance. |
+| `plugins/task_extensions/` | Host-side task automation. |
+| `plugins/experiment_extensions/` | Whole-experiment automation. |
+| `plugins/task_plotters/` | Custom live plot widgets. |
+| `plugins/task_controls/` | Declarative or Python task-control panels. |
+| `experiments/*.json` | Experiment editor and run view. |
+| `settings.json` / `setups.json` | Workspace settings and setup registry. |
+
+Workspace `settings.json` includes the default data directory plus GUI settings
+such as startup tab, plot update frequency, font sizes, and whether task
+controls are mounted by default. Relative data paths are resolved against the
+workspace root, and users can still override the data directory for an
+individual run. GUI application preferences (`QSettings`) store process-local
+state such as the selected workspace root, splitter layouts, and update-check
+timestamps.
+
+## Run Task
+
+The Run task tab connects to one setup, uploads an optional hardware definition,
+loads a task, starts/stops a session, writes data through core loggers, and
+routes board events into logs, controls, and plots.
+
+The live log view supports filtering and autoscroll, and task extensions can
+publish status snapshots with `TaskExtension.update_status(...)` for the Run
+task and experiment status panels.
+
+Task files can select optional GUI helpers:
+
+```python
+v.task_extension = "sequence"
+v.task_plotter = "SequencePlotter"
+v.task_controls = "reward_panel"
+```
+
+If a helper is missing or fails to load, the task can still run with the default
+plotter and no custom controls.
+
+## Experiments
+
+The Experiments tab edits experiment JSON files and creates one subject panel
+per active subject/setup assignment. Each subject panel owns its own
+`SessionRuntime`, `SessionController`, `QThread`, `QtBusAdapter`, logger,
+controls, and plot widget so one rig's failure does not directly own another
+rig's state.
+
+Experiments can also select an optional hardware-test task. When enabled, the
+run view uploads and runs that task for each subject before preparing the main
+experiment task.
+
+Active Run task sessions lock the Experiments and Setups tabs; active
+experiment runs lock Run task and Setups so one workflow owns the shared
+application runtime at a time.
+
+The Qt experiment editor exposes hardware definitions as first-class fields. For
+tasks that import `hardware_definition`, the editor shows a hardware-definition
+selector (saved to the experiment's `hardware_definition` field) and the
+subjects table previews the effective hwdef per subject. The effective hwdef is
+the experiment override, else the setup's `hardware_definition` default. Run
+task offers the same selector, and Setups store a default hwdef per setup.
+
+## Plugins And Trusted Code
+
+Workspace plugins are trusted Python and execute in the GUI process.
+
+- Task plotters live in `plugins/task_plotters/` and subclass
+  `pycontrol_gui.plotting.TaskPlotter`.
+- Task controls live in `plugins/task_controls/` and can be declarative JSON or
+  custom Python widgets exporting `build_controls(parent, context)`. The GUI
+  renders JSON specs with `TaskControlsPanel` and embeds Python widgets directly.
+- Task and experiment extensions are loaded through `pycontrol-core`.
+- `SETTINGS` declarations for task extensions, experiment extensions, and task
+  plotters are edited in the GUI Settings dialog and saved under
+  `settings.extensions.*`. Task controls are configured through task variables
+  or declarative control defaults instead.
+- The Settings dialog shows a configurable-file page for built-in plotting
+  defaults and each plugin file with valid `SETTINGS`. Each page has a
+  `Use defaults` button that resets only that file's settings before saving.
+
+Secret settings are masked in the GUI but still saved in `settings.json`.
+
+## Plotting Diagnostics
+
+The workspace `GUI.plot_update_frequency_hz` setting controls live plot redraws;
+new workspaces default to `35 Hz`. Plot data ingestion still happens through the
+session event stream, so lowering the redraw rate reduces GUI paint work without
+dropping incoming events.
+
+For hardware performance checks, launch with plot profiling enabled:
+
+```bash
+PYCONTROL_PLOT_PROFILE=1 pycontrol-gui /path/to/workspace
+```
+
+Set `PYCONTROL_PLOT_PROFILE_INTERVAL_S` to change the reporting interval. The
+GUI logs `[plot-profile]` lines with call counts plus average and maximum
+latency for `process_batch()` and `update_plot()` spans.
+
+## Import Stability
+
+The supported import surfaces are:
+
+- `pycontrol_gui.plotting`
+- `pycontrol_gui.error_logging`
+- `pycontrol_gui.resources`
+
+Widgets, controllers, and workspace models are application internals. Tests may
+import them, but downstream code should not treat them as stable.
+
+## Error Logging
+
+`pycontrol-gui` writes host-side diagnostics to a rotating `ErrorLog.txt` file:
+
+1. `<workspace root>/ErrorLog.txt`
+2. `~/.pycontrol-gui/logs/ErrorLog.txt`
+3. `./ErrorLog.txt`
+
+Open **View -> Error log** (`Ctrl+E`) to inspect or clear the current log.
+Run/session `.tsv` files are separate and remain in the experiment data
+directory.
+
+## Documentation
+
+New to the project? Start with the repo-level guides:
+
+- [Documentation index](../rewrite-docs/README.md) - map of everything, with a reading order.
+- [Architecture tour](../rewrite-docs/md-viewer.html?doc=ARCHITECTURE-TOUR.md) - learn core and GUI end to end.
+- [Why the rewrite](../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md) - what changed versus pyControl v2 and why.
+
+GUI guides:
+
+- [Architecture, threading, and data flow](docs/architecture.md)
+- [Task sharing and sandboxes](docs/task-sharing.md)
+- [Task plotter plugins](docs/plot-plugins.md)
+- [Task controls](docs/task-controls.md)
+- [Extensions in the GUI](docs/extensions.md)
+- [Current code review backlog](docs/code-review.md)
+- [Shared contributor workflow](../CONTRIBUTING.md)

pycontrol_gui-3.0.0a1/README.md

@@ -0,0 +1,213 @@
+# pycontrol-gui
+
+`pycontrol-gui` is the Qt desktop frontend for `pycontrol-core`.
+
+It provides the main pyControl operator workflows:
+
+- Run one task on one setup.
+- Edit and run multi-subject experiments.
+- Manage setup names, ports, auto-detected MCU cache, and setup variables.
+- View live logs and plots.
+- Use workspace task extensions, experiment extensions, task plotters, task
+  controls, and extension settings.
+
+## Install From PyPI Alpha
+
+For the `3.0.0a1` alpha, pin the prerelease:
+
+```bash
+uv add "pycontrol-gui==3.0.0a1"
+# or
+pip install --pre "pycontrol-gui==3.0.0a1"
+```
+
+To accept the newest available alpha with uv, use:
+
+```bash
+uv add pycontrol-gui --prerelease allow
+```
+
+## Install For Development
+
+Install the sibling core package first:
+
+```bash
+cd ../pycontrol-core
+pip install -e ".[test,lint]"
+
+cd ../pycontrol-gui
+pip install -e ".[test]"
+```
+
+With `uv`, `pycontrol-gui/pyproject.toml` points `pycontrol-core` at the
+sibling `../pycontrol-core` path.
+
+Run the app:
+
+```bash
+pycontrol-gui
+pycontrol-gui /path/to/workspace
+# or
+python -m pycontrol_gui
+python -m pycontrol_gui /path/to/workspace
+```
+
+Run tests with Python's module form so stale local script shebangs do not get in
+the way:
+
+```bash
+uv run python -m pytest
+```
+
+## Workspaces
+
+Open a workspace with **Workspace -> Open Workspace...**, create one with
+**Workspace -> New Workspace...**, or pass a workspace path on the command line.
+If no path is supplied, the GUI uses the last-opened workspace from application
+preferences, then falls back to discovering a workspace from the current working
+directory. Use **Workspace -> Reload workspace** to refresh selectors after
+external file changes.
+
+The GUI uses the standard `pycontrol-core` workspace layout:
+
+| Path | GUI use |
+| --- | --- |
+| `tasks/` | Task selector in Run task and Experiments. |
+| `hardware_definitions/` | Hardware-definition selector and setup validation. |
+| `devices/` | Workspace-local device drivers for task sharing and setup maintenance. |
+| `plugins/task_extensions/` | Host-side task automation. |
+| `plugins/experiment_extensions/` | Whole-experiment automation. |
+| `plugins/task_plotters/` | Custom live plot widgets. |
+| `plugins/task_controls/` | Declarative or Python task-control panels. |
+| `experiments/*.json` | Experiment editor and run view. |
+| `settings.json` / `setups.json` | Workspace settings and setup registry. |
+
+Workspace `settings.json` includes the default data directory plus GUI settings
+such as startup tab, plot update frequency, font sizes, and whether task
+controls are mounted by default. Relative data paths are resolved against the
+workspace root, and users can still override the data directory for an
+individual run. GUI application preferences (`QSettings`) store process-local
+state such as the selected workspace root, splitter layouts, and update-check
+timestamps.
+
+## Run Task
+
+The Run task tab connects to one setup, uploads an optional hardware definition,
+loads a task, starts/stops a session, writes data through core loggers, and
+routes board events into logs, controls, and plots.
+
+The live log view supports filtering and autoscroll, and task extensions can
+publish status snapshots with `TaskExtension.update_status(...)` for the Run
+task and experiment status panels.
+
+Task files can select optional GUI helpers:
+
+```python
+v.task_extension = "sequence"
+v.task_plotter = "SequencePlotter"
+v.task_controls = "reward_panel"
+```
+
+If a helper is missing or fails to load, the task can still run with the default
+plotter and no custom controls.
+
+## Experiments
+
+The Experiments tab edits experiment JSON files and creates one subject panel
+per active subject/setup assignment. Each subject panel owns its own
+`SessionRuntime`, `SessionController`, `QThread`, `QtBusAdapter`, logger,
+controls, and plot widget so one rig's failure does not directly own another
+rig's state.
+
+Experiments can also select an optional hardware-test task. When enabled, the
+run view uploads and runs that task for each subject before preparing the main
+experiment task.
+
+Active Run task sessions lock the Experiments and Setups tabs; active
+experiment runs lock Run task and Setups so one workflow owns the shared
+application runtime at a time.
+
+The Qt experiment editor exposes hardware definitions as first-class fields. For
+tasks that import `hardware_definition`, the editor shows a hardware-definition
+selector (saved to the experiment's `hardware_definition` field) and the
+subjects table previews the effective hwdef per subject. The effective hwdef is
+the experiment override, else the setup's `hardware_definition` default. Run
+task offers the same selector, and Setups store a default hwdef per setup.
+
+## Plugins And Trusted Code
+
+Workspace plugins are trusted Python and execute in the GUI process.
+
+- Task plotters live in `plugins/task_plotters/` and subclass
+  `pycontrol_gui.plotting.TaskPlotter`.
+- Task controls live in `plugins/task_controls/` and can be declarative JSON or
+  custom Python widgets exporting `build_controls(parent, context)`. The GUI
+  renders JSON specs with `TaskControlsPanel` and embeds Python widgets directly.
+- Task and experiment extensions are loaded through `pycontrol-core`.
+- `SETTINGS` declarations for task extensions, experiment extensions, and task
+  plotters are edited in the GUI Settings dialog and saved under
+  `settings.extensions.*`. Task controls are configured through task variables
+  or declarative control defaults instead.
+- The Settings dialog shows a configurable-file page for built-in plotting
+  defaults and each plugin file with valid `SETTINGS`. Each page has a
+  `Use defaults` button that resets only that file's settings before saving.
+
+Secret settings are masked in the GUI but still saved in `settings.json`.
+
+## Plotting Diagnostics
+
+The workspace `GUI.plot_update_frequency_hz` setting controls live plot redraws;
+new workspaces default to `35 Hz`. Plot data ingestion still happens through the
+session event stream, so lowering the redraw rate reduces GUI paint work without
+dropping incoming events.
+
+For hardware performance checks, launch with plot profiling enabled:
+
+```bash
+PYCONTROL_PLOT_PROFILE=1 pycontrol-gui /path/to/workspace
+```
+
+Set `PYCONTROL_PLOT_PROFILE_INTERVAL_S` to change the reporting interval. The
+GUI logs `[plot-profile]` lines with call counts plus average and maximum
+latency for `process_batch()` and `update_plot()` spans.
+
+## Import Stability
+
+The supported import surfaces are:
+
+- `pycontrol_gui.plotting`
+- `pycontrol_gui.error_logging`
+- `pycontrol_gui.resources`
+
+Widgets, controllers, and workspace models are application internals. Tests may
+import them, but downstream code should not treat them as stable.
+
+## Error Logging
+
+`pycontrol-gui` writes host-side diagnostics to a rotating `ErrorLog.txt` file:
+
+1. `<workspace root>/ErrorLog.txt`
+2. `~/.pycontrol-gui/logs/ErrorLog.txt`
+3. `./ErrorLog.txt`
+
+Open **View -> Error log** (`Ctrl+E`) to inspect or clear the current log.
+Run/session `.tsv` files are separate and remain in the experiment data
+directory.
+
+## Documentation
+
+New to the project? Start with the repo-level guides:
+
+- [Documentation index](../rewrite-docs/README.md) - map of everything, with a reading order.
+- [Architecture tour](../rewrite-docs/md-viewer.html?doc=ARCHITECTURE-TOUR.md) - learn core and GUI end to end.
+- [Why the rewrite](../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md) - what changed versus pyControl v2 and why.
+
+GUI guides:
+
+- [Architecture, threading, and data flow](docs/architecture.md)
+- [Task sharing and sandboxes](docs/task-sharing.md)
+- [Task plotter plugins](docs/plot-plugins.md)
+- [Task controls](docs/task-controls.md)
+- [Extensions in the GUI](docs/extensions.md)
+- [Current code review backlog](docs/code-review.md)
+- [Shared contributor workflow](../CONTRIBUTING.md)