Metadata-Version: 2.4
Name: pycontrol-install
Version: 0.1.0a3
Summary: Lifecycle manager for the global pyControl GUI and its workspaces.
Project-URL: Homepage, https://github.com/karpova-lab/pycontrol-install
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-install

`pycontrol-install` manages the lifecycle of a global pyControl app. It installs
`pycontrol-gui` and the `pycontrol` CLI with `uv tool install`, switches between
published and editable local sources, updates and uninstalls the app, scaffolds
plain-data workspaces, and manages the OS launcher.

## Complete lifecycle

### 1. Install the manager

Install `uv`, then install `pycontrol-install` as a uv tool:

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

For development of the manager itself, install its checkout as editable instead:

```bash
ROOT="/Users/lustiga/HHMI Dropbox/Andy Lustig/Code/karpova_lab/pyControl/rewrite"
uv tool install --editable "$ROOT/pycontrol-install"
```

Edits under `pycontrol-install/src/` are then immediately live.

### 2. Install and launch pyControl

Install the published core and GUI, create a workspace, remember it, optionally
create an OS launcher, and launch:

```bash
pycontrol-install my-workspace --launch
```

The workspace is pure data: it has no virtual environment, lockfile, or
launcher script. After setup, launch the remembered workspace from the OS
launcher or from any terminal:

```bash
pycontrol-gui
```

To initialize the current directory as the workspace, pass `.` explicitly:

```bash
pycontrol-install . --launch
```

To install the app without creating a workspace:

```bash
pycontrol-install
```

### 3. Switch to editable local core and GUI sources

Point the global app at sibling `pycontrol-core/` and `pycontrol-gui/`
checkouts:

```bash
pycontrol-install --use-local "$ROOT"
pycontrol-gui
```

The global commands and OS launcher stay the same. Python source edits in both
checkouts are immediately live; no reinstall is needed. Ordinary
`pycontrol-install` workspace operations preserve this local mode.

`--update-gui` intentionally stops in local mode because replacing editable
sources during an update would be surprising. Use Git to update the checkouts,
or explicitly switch back to PyPI.

### 4. Switch back to published packages

```bash
pycontrol-install --use-pypi
```

This replaces both editable checkouts with the newest published core and GUI,
while preserving installed optional extras.

### 5. Update published pyControl

```bash
pycontrol-install --update-gui
```

This refreshes the package index and reinstalls the newest published packages,
preserving optional extras. It refuses to replace a local editable install;
run `--use-pypi` first. `uv tool upgrade pycontrol-gui` is also available for
published installs.

To update the separately installed manager:

```bash
uv tool upgrade pycontrol-install
```

An editable manager checkout does not need upgrading because its source edits
are already live.

### 6. Uninstall

Remove the pyControl app, OS launcher, and all GUI QSettings:

```bash
pycontrol-install --uninstall
```

This removes the `pycontrol-gui` uv tool environment, including the injected
core CLI. It deliberately leaves `pycontrol-install` available for a future
reinstall. Remove the manager too when it is no longer wanted:

```bash
uv tool uninstall pycontrol-install
```

## Usage

```bash
pycontrol-install [path] [--launch] [--force] [--shortcut | --no-shortcut]
pycontrol-install {--update-gui | --use-local ROOT | --use-pypi | --uninstall}
```

Without `path`, only the app is installed — no workspace is created or
touched. Pass a path (`.` for the current directory) to also scaffold and
remember a workspace; relative paths are resolved from the directory where the
command is run. Re-running `pycontrol-install` is safe: the current PyPI or
local source mode is preserved and workspace scaffolding is a safe merge.

Examples:

```bash
pycontrol-install                         # install/refresh the app only
pycontrol-install my-workspace --launch
pycontrol-install ~/pycontrol-workspaces/ws1 --with-slack
pycontrol-install my-workspace --no-shortcut
```

## Integration helpers

Optional integration dependencies are installed into the global tool
environment:

```bash
pycontrol-install my-workspace --with-slack
pycontrol-install my-workspace --with-notion
pycontrol-install my-workspace --with-s3
pycontrol-install my-workspace --with-integrations
```

To add an integration to an existing install without touching any workspace,
combine it with `--update-gui`:

```bash
pycontrol-install --update-gui --with-slack
```

## Analysis helpers

Install pandas dataframe support into the global app environment with:

```bash
pycontrol-install --with-analysis
```

This is separate from `--with-integrations`, which installs only the Slack,
Notion, and S3 helpers. Re-running the installer or using `--update-gui`
preserves the analysis extra recorded in the uv tool receipt.

## Release smoke tests

Package indexes can be overridden:

```bash
pycontrol-install test-workspace \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/
```

## Development

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