pycontrol-install 0.1.0a1__py3-none-any.whl

pycontrol_install/__init__.py

@@ -0,0 +1,5 @@
+"""pyControl global installer."""
+
+__version__ = "0.1.0a1"
+
+__all__ = ["__version__"]

pycontrol_install/cli.py

@@ -0,0 +1,334 @@
+"""Command-line installer for the global pyControl app and its workspaces.
+
+``pycontrol-install`` installs ``pycontrol-gui`` once per machine with
+``uv tool install``, scaffolds plain-data workspace folders, and remembers the
+workspace so the globally installed ``pycontrol-gui`` command opens it on the
+next launch.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from pycontrol_install.shortcuts import create_shortcut
+
+GUI_PACKAGE = "pycontrol-gui"
+CORE_PACKAGE = "pycontrol-core"
+_INTEGRATION_EXTRAS = ("notion", "s3", "slack")
+_PRERELEASE_CHOICES = ("allow", "disallow", "if-necessary", "explicit", "if-necessary-or-explicit")
+
+
+class BootstrapError(RuntimeError):
+    """Expected bootstrap failure suitable for a one-line CLI error."""
+
+
+class CommandRunner(Protocol):
+    """Small abstraction for testing command construction without invoking uv."""
+
+    def has_command(self, name: str) -> bool: ...
+
+    def run(self, cwd: Path, command: Sequence[str]) -> None: ...
+
+    def run_capture(self, cwd: Path, command: Sequence[str]) -> str: ...
+
+
+@dataclass(frozen=True)
+class BootstrapConfig:
+    """Parsed bootstrap options."""
+
+    target: Path
+    launch: bool
+    force: bool
+    python: str
+    prerelease: str
+    index_url: str | None
+    extra_index_url: str | None
+    integration_extras: tuple[str, ...]
+    update_gui: bool
+    shortcut: bool | None
+
+
+class SubprocessRunner:
+    """Run commands on the local machine."""
+
+    def has_command(self, name: str) -> bool:
+        return shutil.which(name) is not None
+
+    def run(self, cwd: Path, command: Sequence[str]) -> None:
+        print(f"Running in {cwd}: {shlex.join(command)}")
+        try:
+            subprocess.run(command, cwd=cwd, check=True)
+        except FileNotFoundError as exc:
+            raise BootstrapError(f"command not found: {command[0]}") from exc
+        except subprocess.CalledProcessError as exc:
+            raise BootstrapError(f"command failed with exit code {exc.returncode}: {shlex.join(command)}") from exc
+
+    def run_capture(self, cwd: Path, command: Sequence[str]) -> str:
+        try:
+            completed = subprocess.run(command, cwd=cwd, check=True, capture_output=True, text=True)
+        except FileNotFoundError as exc:
+            raise BootstrapError(f"command not found: {command[0]}") from exc
+        except subprocess.CalledProcessError as exc:
+            raise BootstrapError(f"command failed with exit code {exc.returncode}: {shlex.join(command)}") from exc
+        return completed.stdout.strip()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pycontrol-install",
+        description="Install the pyControl GUI globally with uv and create a workspace data folder.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Workspace path to create or initialize (default: current directory).",
+    )
+    parser.add_argument(
+        "--launch",
+        action="store_true",
+        help="Launch the pyControl GUI after the workspace is ready.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Pass --force to workspace scaffolding so differing bundled files are overwritten.",
+    )
+    parser.add_argument(
+        "--update-gui",
+        action="store_true",
+        help="Reinstall the newest pyControl GUI (preserving installed integration extras) and exit.",
+    )
+    parser.add_argument(
+        "--shortcut",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Create (or skip) an OS shortcut for the pyControl GUI without prompting.",
+    )
+    parser.add_argument(
+        "--python",
+        default="3.12",
+        help="Python version request for the global tool environment (default: 3.12).",
+    )
+    parser.add_argument(
+        "--prerelease",
+        choices=_PRERELEASE_CHOICES,
+        default="if-necessary-or-explicit",
+        help=(
+            "uv prerelease resolution strategy (default: if-necessary-or-explicit, which selects pyControl "
+            "alphas because no stable release exists yet while keeping third-party dependencies stable)."
+        ),
+    )
+    parser.add_argument(
+        "--index-url",
+        default=None,
+        help="Package index URL for uv tool install, or PYCONTROL_INSTALL_INDEX_URL.",
+    )
+    parser.add_argument(
+        "--extra-index-url",
+        default=None,
+        help="Extra package index URL for uv tool install, or PYCONTROL_INSTALL_EXTRA_INDEX_URL.",
+    )
+    parser.add_argument(
+        "--with-slack",
+        action="store_true",
+        help="Install Slack notification dependencies into the global tool environment.",
+    )
+    parser.add_argument(
+        "--with-notion",
+        action="store_true",
+        help="Install Notion helper dependencies into the global tool environment.",
+    )
+    parser.add_argument(
+        "--with-s3",
+        action="store_true",
+        help="Install S3 export helper dependencies into the global tool environment.",
+    )
+    parser.add_argument(
+        "--with-integrations",
+        action="store_true",
+        help="Install all optional integration helper dependencies into the global tool environment.",
+    )
+    return parser
+
+
+def config_from_args(args: argparse.Namespace) -> BootstrapConfig:
+    selected = set(_INTEGRATION_EXTRAS if args.with_integrations else ())
+    if args.with_notion:
+        selected.add("notion")
+    if args.with_s3:
+        selected.add("s3")
+    if args.with_slack:
+        selected.add("slack")
+
+    return BootstrapConfig(
+        target=Path(args.path),
+        launch=bool(args.launch),
+        force=bool(args.force),
+        python=str(args.python),
+        prerelease=str(args.prerelease),
+        index_url=args.index_url or os.environ.get("PYCONTROL_INSTALL_INDEX_URL") or None,
+        extra_index_url=args.extra_index_url or os.environ.get("PYCONTROL_INSTALL_EXTRA_INDEX_URL") or None,
+        integration_extras=tuple(extra for extra in _INTEGRATION_EXTRAS if extra in selected),
+        update_gui=bool(args.update_gui),
+        shortcut=args.shortcut,
+    )
+
+
+def bootstrap(config: BootstrapConfig, runner: CommandRunner | None = None) -> Path | None:
+    """Install the GUI globally, then scaffold and remember the workspace.
+
+    Returns the workspace path, or ``None`` for ``--update-gui`` runs.
+    """
+    runner = runner or SubprocessRunner()
+    if not runner.has_command("uv"):
+        raise BootstrapError(
+            "uv is required because pycontrol-install uses uv; install it from "
+            "https://docs.astral.sh/uv/getting-started/installation/"
+        )
+
+    cwd = Path.cwd()
+    receipt = _receipt_path(runner, cwd)
+
+    if config.update_gui:
+        if receipt is None or not receipt.is_file():
+            raise BootstrapError(
+                f"{GUI_PACKAGE} is not installed as a uv tool yet; run pycontrol-install without --update-gui first."
+            )
+        extras = tuple(sorted({*_extras_from_receipt(receipt), *config.integration_extras}))
+        runner.run(cwd, _install_command(config, extras=extras, reinstall=True))
+        print(f"{GUI_PACKAGE} reinstalled at the newest version.")
+        return None
+
+    reinstall = receipt is not None and receipt.is_file()
+    runner.run(cwd, _install_command(config, extras=config.integration_extras, reinstall=reinstall))
+
+    bin_dir = Path(runner.run_capture(cwd, ["uv", "tool", "dir", "--bin"]))
+    target = _prepare_target(config.target)
+
+    workspace_init = [str(bin_dir / "pycontrol"), "workspace", "init", str(target)]
+    if config.force:
+        workspace_init.append("--force")
+    runner.run(target, workspace_init)
+
+    runner.run(target, [str(bin_dir / GUI_PACKAGE), "--set-workspace", str(target)])
+
+    if _shortcut_wanted(config.shortcut):
+        _create_shortcut_nonfatal(bin_dir)
+
+    if config.launch:
+        runner.run(target, [str(bin_dir / GUI_PACKAGE), str(target)])
+
+    return target
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        workspace = bootstrap(config_from_args(args))
+    except BootstrapError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if workspace is not None:
+        print(f"Workspace ready: {workspace}")
+        if not args.launch:
+            print(f"Launch anytime with: {GUI_PACKAGE}")
+        print(f"If the {GUI_PACKAGE} command is not found in new terminals, run: uv tool update-shell")
+    return 0
+
+
+def _install_command(config: BootstrapConfig, *, extras: tuple[str, ...], reinstall: bool) -> list[str]:
+    # --refresh: resolve against a revalidated index so a release published
+    # moments ago is picked up instead of a cached older version.
+    # --force: claim the pycontrol/pycontrol-gui executables even when a stale
+    # shim or an older tool install already provides them.
+    command = [
+        "uv",
+        "tool",
+        "install",
+        "--refresh",
+        "--force",
+        "--python",
+        config.python,
+        "--prerelease",
+        config.prerelease,
+    ]
+    if config.index_url:
+        command.extend(["--index-url", config.index_url])
+    if config.extra_index_url:
+        command.extend(["--extra-index-url", config.extra_index_url])
+    if extras:
+        command.extend(["--with", f"{CORE_PACKAGE}[{','.join(sorted(extras))}]"])
+    command.extend(["--with-executables-from", CORE_PACKAGE])
+    if reinstall:
+        command.append("--reinstall")
+    command.append(GUI_PACKAGE)
+    return command
+
+
+def _receipt_path(runner: CommandRunner, cwd: Path) -> Path | None:
+    try:
+        tool_dir = runner.run_capture(cwd, ["uv", "tool", "dir"])
+    except BootstrapError:
+        return None
+    if not tool_dir:
+        return None
+    return Path(tool_dir) / GUI_PACKAGE / "uv-receipt.toml"
+
+
+def _extras_from_receipt(receipt: Path) -> tuple[str, ...]:
+    """Recover ``pycontrol-core`` extras from the uv tool receipt so an update
+    reinstall keeps previously chosen integrations."""
+    try:
+        data = tomllib.loads(receipt.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return ()
+    requirements = data.get("tool", {}).get("requirements", [])
+    for requirement in requirements:
+        if isinstance(requirement, dict) and requirement.get("name") == CORE_PACKAGE:
+            extras = requirement.get("extras", [])
+            return tuple(sorted(str(extra) for extra in extras if str(extra) in _INTEGRATION_EXTRAS))
+    return ()
+
+
+def _prepare_target(raw_target: Path) -> Path:
+    target = raw_target.expanduser().resolve()
+    if target.exists() and not target.is_dir():
+        raise BootstrapError(f"target exists and is not a directory: {target}")
+    target.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def _shortcut_wanted(shortcut: bool | None) -> bool:
+    if shortcut is not None:
+        return shortcut
+    if not sys.stdin.isatty():
+        return False
+    answer = input("Create an OS shortcut for the pyControl GUI? [Y/n] ").strip().lower()
+    return answer in ("", "y", "yes")
+
+
+def _create_shortcut_nonfatal(bin_dir: Path) -> None:
+    try:
+        created = create_shortcut(bin_dir)
+    except Exception as exc:  # noqa: BLE001 - shortcuts are a nicety, never fatal.
+        print(f"warning: could not create a shortcut: {exc}", file=sys.stderr)
+        return
+    if created is not None:
+        print(f"Shortcut created: {created}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

pycontrol_install/shortcuts.py

@@ -0,0 +1,116 @@
+"""Optional OS shortcuts pointing at the globally installed ``pycontrol-gui``.
+
+All variants target the stable uv tool shim (``<uv tool bin dir>/pycontrol-gui``),
+which survives upgrades, so shortcuts never need regeneration.
+"""
+
+from __future__ import annotations
+
+import plistlib
+import subprocess
+import sys
+from pathlib import Path
+
+APP_NAME = "pyControl GUI"
+_BUNDLE_IDENTIFIER = "org.pycontrol.gui-launcher"
+
+
+def create_shortcut(bin_dir: Path, home: Path | None = None, platform: str | None = None) -> Path | None:
+    """Create a double-clickable shortcut for the current OS.
+
+    Returns the created shortcut path, or ``None`` when the platform has no
+    shortcut support. Raises on failure; callers treat that as non-fatal.
+    """
+    home = home or Path.home()
+    platform = platform or sys.platform
+    if platform == "darwin":
+        return create_macos_app_bundle(bin_dir, home)
+    if platform == "win32":
+        return create_windows_start_menu_shortcut(bin_dir)
+    if platform.startswith("linux"):
+        return create_linux_desktop_entry(bin_dir, home)
+    return None
+
+
+def create_macos_app_bundle(bin_dir: Path, home: Path) -> Path:
+    """Minimal ~/Applications app bundle wrapping the pycontrol-gui shim."""
+    bundle = home / "Applications" / f"{APP_NAME}.app"
+    macos_dir = bundle / "Contents" / "MacOS"
+    macos_dir.mkdir(parents=True, exist_ok=True)
+
+    info = {
+        "CFBundleName": APP_NAME,
+        "CFBundleDisplayName": APP_NAME,
+        "CFBundleIdentifier": _BUNDLE_IDENTIFIER,
+        "CFBundlePackageType": "APPL",
+        "CFBundleExecutable": "pycontrol-gui-launcher",
+    }
+    with (bundle / "Contents" / "Info.plist").open("wb") as stream:
+        plistlib.dump(info, stream)
+
+    launcher = macos_dir / "pycontrol-gui-launcher"
+    launcher.write_text(macos_launcher_script(bin_dir), encoding="utf-8", newline="\n")
+    launcher.chmod(launcher.stat().st_mode | 0o111)
+    return bundle
+
+
+def macos_launcher_script(bin_dir: Path) -> str:
+    return f'#!/bin/sh\nexec "{bin_dir / "pycontrol-gui"}" "$@"\n'
+
+
+def create_windows_start_menu_shortcut(bin_dir: Path) -> Path:
+    """Start-menu .lnk via the WScript.Shell COM object (no extra dependencies)."""
+    completed = subprocess.run(
+        ["powershell", "-NoProfile", "-Command", windows_shortcut_command(bin_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    link_path = completed.stdout.strip().splitlines()[-1] if completed.stdout.strip() else ""
+    if not link_path:
+        raise RuntimeError("PowerShell did not report the created shortcut path")
+    return Path(link_path)
+
+
+def windows_shortcut_command(bin_dir: Path) -> str:
+    target = bin_dir / "pycontrol-gui.exe"
+    return (
+        "$programs = [Environment]::GetFolderPath('Programs'); "
+        f"$link = Join-Path $programs '{APP_NAME}.lnk'; "
+        "$shell = New-Object -ComObject WScript.Shell; "
+        "$shortcut = $shell.CreateShortcut($link); "
+        f"$shortcut.TargetPath = '{target}'; "
+        "$shortcut.Save(); "
+        "Write-Output $link"
+    )
+
+
+def create_linux_desktop_entry(bin_dir: Path, home: Path) -> Path:
+    applications = home / ".local" / "share" / "applications"
+    applications.mkdir(parents=True, exist_ok=True)
+    entry = applications / "pycontrol-gui.desktop"
+    entry.write_text(linux_desktop_entry(bin_dir), encoding="utf-8", newline="\n")
+    return entry
+
+
+def linux_desktop_entry(bin_dir: Path) -> str:
+    return (
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        f"Name={APP_NAME}\n"
+        f'Exec="{bin_dir / "pycontrol-gui"}"\n'
+        "Terminal=false\n"
+        "Categories=Science;\n"
+    )
+
+
+__all__ = [
+    "APP_NAME",
+    "create_linux_desktop_entry",
+    "create_macos_app_bundle",
+    "create_shortcut",
+    "create_windows_start_menu_shortcut",
+    "linux_desktop_entry",
+    "macos_launcher_script",
+    "windows_shortcut_command",
+]

pycontrol_install-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: pycontrol-install
+Version: 0.1.0a1
+Summary: uvx installer 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` 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-install 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-install . --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-install [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-install` is safe: the
+global install is refreshed (`--reinstall`) and workspace scaffolding is a safe
+merge.
+
+Examples:
+
+```bash
+pycontrol-install
+pycontrol-install my-workspace --launch
+pycontrol-install ~/pycontrol-workspaces/ws1 --with-slack
+pycontrol-install my-workspace --no-shortcut
+```
+
+## Updating the GUI
+
+```bash
+uvx pycontrol-install --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-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
+uvx pycontrol-install --update-gui --with-slack
+```
+
+## 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
+```

pycontrol_install-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,8 @@
+pycontrol_install/__init__.py,sha256=cAUQjIarvq-QPQrG7Zxt6AWRdXVXG2jKz34jpBZbAXg,86
+pycontrol_install/cli.py,sha256=pPDPKXU86kv0R6-JOPX0i-1knrroxLhostjr1OB8QS0,11787
+pycontrol_install/shortcuts.py,sha256=RqWUBtPbdXt33c-kZRH67U3mk-gx1PoVDN8GiC1B67A,3925
+pycontrol_install-0.1.0a1.dist-info/METADATA,sha256=SfTF2leLzJaGa2ZGOTy3XapMtLJZF_8z5QoldgROVwk,3686
+pycontrol_install-0.1.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pycontrol_install-0.1.0a1.dist-info/entry_points.txt,sha256=Ijc_DZaKwhox1CJLjnD30GnM57_Eu7mduHQ473GL0V0,65
+pycontrol_install-0.1.0a1.dist-info/licenses/LICENSE.txt,sha256=eOoHjIIzecTuMO3xRRPSEAWfIBYJquFE5X7iS3NJYNk,1453
+pycontrol_install-0.1.0a1.dist-info/RECORD,,

pycontrol_install-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pycontrol_install-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pycontrol-install = pycontrol_install.cli:main

pycontrol_install-0.1.0a1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,8 @@
+Copyright © 2026 Howard Hughes Medical Institute
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+Neither the name of HHMI nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.