spin

Warnings

• breaking Support for `setup.py` was completely removed in version 0.16.0. All project configuration and `spin` task definitions must now reside in `pyproject.toml`.
  Fix: Migrate your project's build backend and metadata from `setup.py` to `pyproject.toml` (PEP 517/621). Ensure all `[tool.spin]` configurations are defined in `pyproject.toml`.
• breaking The way arguments are passed to tasks changed significantly in version 0.10.0. Tasks now receive arguments as a list of strings directly, rather than a single concatenated string.
  Fix: Review any `spin` task definitions that process command-line arguments. Update the task implementation in `pyproject.toml` (e.g., in a script) to correctly parse or utilize a list of string arguments.
• gotcha By default, `spin install` attempts to use `conda` for environment creation if a `conda` executable is found in the system's PATH. If `conda` is not available, it falls back to `pip`.
  Fix: If you require a specific environment manager, explicitly configure it in your `pyproject.toml` under `[tool.spin.install]`, for example, `manager = "pip"` or `manager = "conda"`. Ensure the chosen manager is installed and accessible.
• gotcha spin commands must be executed from the root directory of a project that contains a `pyproject.toml` file with a valid `[tool.spin]` section. Running `spin` from a subdirectory or without this configuration will lead to errors.
  Fix: Always change your current working directory to the project root before running any `spin` commands. Verify your `pyproject.toml` includes a `[tool.spin]` table with at least one defined task or configuration.

Install

• pip install spin Install spin

Imports

• run_spin

  from spin.app import run_spin

  This is the primary programmatic entry point for invoking spin commands, typically used for testing or integrating spin into automated workflows rather than general application usage. Note that `run_spin` often calls `sys.exit()`.

Quickstart

This quickstart demonstrates how to set up a minimal `spin` project (a `pyproject.toml` with a task) and then programmatically invoke a `spin` command using `subprocess`. While `spin` has a Python API (`spin.app.run_spin`), direct `subprocess` invocation is often more robust for quickstarts and automation, as `run_spin` can cause `sys.exit()`.

import os
import subprocess
import sys
import tempfile
from pathlib import Path

# Create a temporary project directory to run spin in
with tempfile.TemporaryDirectory() as tmpdir_name:
    project_path = Path(tmpdir_name)
    os.chdir(project_path)

    # Define a simple pyproject.toml with a 'hello' task
    pyproject_content = """
[project]
name = "my-spin-project"
version = "0.1.0"

[tool.spin]
tasks.hello = "echo Hello from spin!"
"""
    (project_path / "pyproject.toml").write_text(pyproject_content)

    print(f"Temporary project created at: {project_path}")
    print("Attempting to run 'spin hello' via subprocess...")

    try:
        # Invoke spin using `python -m spin` to simulate CLI execution
        # and allow the Python script to continue after spin completes.
        result = subprocess.run([sys.executable, '-m', 'spin', 'hello'],
                                capture_output=True, text=True, check=True)
        
        print("\n--- spin output ---")
        print(result.stdout.strip())
        print("--- end spin output ---")
        
        assert "Hello from spin!" in result.stdout
        print("Quickstart successful: 'spin hello' task executed and verified.")

    except subprocess.CalledProcessError as e:
        print(f"Error running spin command (exit code {e.returncode}):")
        print(f"Stdout: {e.stdout}")
        print(f"Stderr: {e.stderr}")
        sys.exit(1)
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
        sys.exit(1)