Metadata-Version: 2.4
Name: pycontrol-manager
Version: 0.1.0a1
Summary: Lifecycle manager for the global pyControl application.
Project-URL: Homepage, https://github.com/karpova-lab/pycontrol-manager
Author: pyControl contributors
License: GPL-3.0-or-later
License-File: LICENSE.txt
Keywords: behaviour,neuroscience,pycontrol,uv
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# pycontrol-manager

`pycontrol-manager` manages the lifecycle of the global pyControl application.
It installs `pycontrol-gui` and the `pycontrol` CLI with `uv`, updates and
uninstalls the app, switches between published and editable sources, manages
optional dependencies, and creates the OS launcher.

Workspace creation and experiment operation are deliberately outside the
manager. Create or open a workspace in the GUI, or use `pycontrol workspace`.

## Quickstart

Install the manager:

```bash
uv tool install --prerelease if-necessary-or-explicit pycontrol-manager
```

Install and launch the app:

```bash
pycontrol-manager app install --launch
```

On first launch, the GUI offers to create or open a workspace. The app is
installed once per computer and can switch among plain-data workspaces.

## Application lifecycle

```bash
pycontrol-manager app install
pycontrol-manager app update
pycontrol-manager app launch
pycontrol-manager app status
pycontrol-manager app uninstall
```

`app install` is safe to repeat. It preserves the current published or editable
source mode and all enabled extras. `app update` installs the newest published
packages and refuses to replace editable local sources.

`app uninstall` removes the `pycontrol-gui` uv tool environment, the OS
shortcut, and GUI preferences. It leaves `pycontrol-manager` installed for
diagnostics or a future reinstall. Remove the manager separately when it is no
longer needed:

```bash
uv tool uninstall pycontrol-manager
```

## Published and local sources

Switch the app to editable sibling `pycontrol-core/` and `pycontrol-gui/`
checkouts:

```bash
pycontrol-manager app source local /path/to/source-root
```

Source edits are immediately live in the global commands and OS launcher.
Switch back to the newest published packages with:

```bash
pycontrol-manager app source pypi
```

## Optional dependencies

Available extras are `analysis`, `notion`, `s3`, and `slack`.

```bash
pycontrol-manager app extras list
pycontrol-manager app extras add slack notion
pycontrol-manager app extras add integrations
pycontrol-manager app extras remove s3
```

`integrations` expands to `notion`, `s3`, and `slack`. Extras are installed into
the global app environment and preserved across installs, updates, and source
switches.

## Status and diagnostics

`app status` reports installed core and GUI versions, Python, source mode,
enabled extras, executable paths, and shortcut state:

```bash
pycontrol-manager app status
```

Run read-only installation diagnostics with:

```bash
pycontrol-manager doctor
```

The doctor checks `uv`, the tool receipt, editable source paths, package
versions, command location, and shortcut state. It does not modify the
installation.

## Installation options

Commands that install or rebuild the app accept:

```text
--python PYTHON
--prerelease {allow,disallow,if-necessary,explicit,if-necessary-or-explicit}
--index-url URL
--extra-index-url URL
```

Index URLs can also be supplied through
`PYCONTROL_MANAGER_INDEX_URL` and
`PYCONTROL_MANAGER_EXTRA_INDEX_URL`.

`app install` additionally accepts `--launch`, `--shortcut`, and
`--no-shortcut`.

## Development

Install this checkout as an editable tool:

```bash
uv tool install --editable /path/to/pycontrol-manager
```

Run checks:

```bash
uv sync --group dev
uv run pytest
uv run ruff check src tests
```
