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

`pycontrol-init` is a small `uvx` installer for pyControl. It installs
`pycontrol-gui` (and the `pycontrol` CLI) **once per machine** with
`uv tool install`, scaffolds plain-data workspace folders, and remembers the
workspace so the global `pycontrol-gui` command opens it on the next launch.

Install `uv`, then install pyControl and create a workspace:

```bash
uvx pycontrol-init my-workspace --launch
```

This:

1. runs `uv tool install pycontrol-gui` into a self-contained, uv-managed
   environment, putting `pycontrol-gui` and `pycontrol` on your PATH,
2. scaffolds the `my-workspace` data folder (no `pyproject.toml`, `.venv`, or
   lockfile — workspaces are pure data),
3. remembers it as the GUI's current workspace,
4. offers to create an OS shortcut (macOS `~/Applications`, Windows Start
   menu, Linux application menu), and
5. launches the GUI (`--launch`).

After setup, launch the GUI from anywhere with `pycontrol-gui`.

To initialize the current directory instead:

```bash
uvx pycontrol-init . --launch
```

This package intentionally uses `uv`. Users who prefer pip can still install
and run pyControl manually from a Python 3.11+ virtual environment; see the
`pycontrol-core` getting-started guide for the pip/venv workflow.

## Usage

```bash
pycontrol-init [path] [--launch] [--force] [--shortcut | --no-shortcut] [--update-gui]
```

`path` defaults to the current directory. Relative paths are resolved from the
directory where the command is run. Re-running `pycontrol-init` is safe: the
global install is refreshed (`--reinstall`) and workspace scaffolding is a safe
merge.

Examples:

```bash
pycontrol-init
pycontrol-init my-workspace --launch
pycontrol-init ~/pycontrol-workspaces/ws1 --with-slack
pycontrol-init my-workspace --no-shortcut
```

## Updating the GUI

```bash
uvx pycontrol-init --update-gui
```

Reinstalls the newest `pycontrol-gui` against a freshly refreshed package
index, preserving integration extras recorded in the uv tool receipt.
(`uv tool upgrade pycontrol-gui` also works; `--update-gui` additionally
guarantees the index is revalidated and the pyControl resolution strategy is
applied.)

## Integration helpers

Optional integration dependencies are installed into the global tool
environment:

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

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

```bash
uvx pycontrol-init --update-gui --with-slack
```

## Release smoke tests

Package indexes can be overridden:

```bash
pycontrol-init 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
```
