### Install Spin

Source: https://github.com/scientific-python/spin/blob/main/README.md

Installs the 'spin' package using pip. This is the primary method for getting the tool.

```bash
pip install spin
```

--------------------------------

### Basic Spin Configuration

Source: https://github.com/scientific-python/spin/blob/main/README.md

Example of basic 'spin' configuration in pyproject.toml, specifying the package name and the commands to be included.

```toml
[tool.spin]
package = "pkg_importname"
commands = [
  "spin.cmds.meson.build",
  "spin.cmds.meson.test"
]
```

--------------------------------

### Spin Built-in Pip Commands

Source: https://github.com/scientific-python/spin/blob/main/README.md

Highlights the built-in command for managing package installation using pip, including editable installs.

```bash
spin.cmds.pip.install
```

--------------------------------

### Installing Noto Fonts for Emoji Support

Source: https://github.com/scientific-python/spin/blob/main/README.md

A command to install the Noto Fonts package, which includes emoji characters, to resolve issues with emojis not displaying correctly in the terminal.

```bash
sudo pacman -S noto-fonts-emoji
fc-cache -f -v

```

--------------------------------

### Extending Built-in Commands with Decorators

Source: https://github.com/scientific-python/spin/blob/main/README.md

Illustrates how to use the `spin.util.extend_cmd` decorator to add functionality or arguments to existing Spin commands. The example shows adding an `--extra` flag to the `build` command, passing the parent callback, and configuring the extension in pyproject.toml.

```python
import spin


@click.option("-e", "--extra", help="Extra test flag")
@spin.util.extend_command(spin.cmds.meson.build)
def build_extend(*, parent_callback, extra=None, **kwargs):
    """
    This version of build also provides the EXTRA flag, that can be used
    to specify an extra integer argument.
    """
    print(f"Preparing for build with {extra=}")
    parent_callback(**kwargs)
    print("Finalizing build...")

```

```toml
"Build" = [".spin/cmds.py:build_extend"]

```

--------------------------------

### Running Spin

Source: https://github.com/scientific-python/spin/blob/main/README.md

Shows the two primary ways to execute the 'spin' command-line tool.

```bash
spin
```

```bash
python -m spin
```

--------------------------------

### Running Spin Tests with Nox

Source: https://github.com/scientific-python/spin/blob/main/README.md

Demonstrates how to invoke Spin's tests using the Nox test runner, including options for verbose output and targeting specific test files.

```bash
nox -s test

```

```bash
nox -s test -- -v

```

```bash
nox -s test -- -v spin/tests/test_meson.py

```

--------------------------------

### Spin Built-in Meson Commands

Source: https://github.com/scientific-python/spin/blob/main/README.md

Lists the available built-in commands related to Meson, used for building and testing scientific Python packages.

```bash
spin.cmds.meson.build
spin.cmds.meson.ipython
spin.cmds.meson.python
spin.cmds.meson.shell
spin.cmds.meson.test
spin.cmds.meson.run
spin.cmds.meson.docs
spin.cmds.meson.gdb
spin.cmds.meson.lldb
```

--------------------------------

### Autogenerating Release Notes

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

Uses the `changelist` command to autogenerate release notes by comparing two versions of a repository. The output is saved to a version-specific markdown file.

```bash
changelist ${ORG}/${REPO} v${PREVIOUS} main --version ${VERSION} --out ${VERSION}.md
```

--------------------------------

### Organizing Spin Commands into Sections

Source: https://github.com/scientific-python/spin/blob/main/README.md

Demonstrates how to organize 'spin' commands into logical sections within pyproject.toml for better readability and structure.

```toml
[tool.spin.commands]
"Build" = [
  "spin.cmds.meson.build",
  "spin.cmds.meson.test"
]
"Environments" = [
  "spin.cmds.meson.ipython",
  "spin.cmds.meson.run"
]
```

--------------------------------

### Tagging the Release

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

Creates an annotated Git tag for the release. It's recommended to use GPG keys for signing tags, especially for Debian packaging.

```git
git tag -s v${VERSION} -m "signed ${VERSION} tag"
```

--------------------------------

### Setting Release Variables

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

Exports environment variables required for the release process, including version numbers, repository organization, repository name, and the changelog file.

```bash
export VERSION=<version number>
export PREVIOUS=<previous version number>
export ORG="scientific-python"
export REPO="spin"
export LOG="CHANGELOG.md"
```

--------------------------------

### Adding Custom Spin Commands

Source: https://github.com/scientific-python/spin/blob/main/README.md

Illustrates how to include custom commands in 'spin' by referencing a Python file and function within the pyproject.toml configuration.

```toml
commands = [..., '.spin/cmds.py:example']
```

--------------------------------

### Spin Built-in Build (PEP 517) Commands

Source: https://github.com/scientific-python/spin/blob/main/README.md

Details the built-in command for building source distributions using the PEP 517 build backend.

```bash
spin.cmds.build.sdist
```

--------------------------------

### Pushing Tags and Main Branch

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

Pushes the newly created Git tags and the main branch to the remote repository (origin).

```git
git push --tags origin main
```

--------------------------------

### Updating Changelog

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

Concatenates the newly generated release notes with the existing `CHANGELOG.md` file, placing the new notes at the top.

```bash
cat ${VERSION}.md | cat - ${LOG} > temp && mv temp ${LOG}
```

--------------------------------

### Spin Built-in Meta Commands

Source: https://github.com/scientific-python/spin/blob/main/README.md

Describes the meta-commands provided by 'spin' for introspection and command management.

```bash
spin.cmds.meta.introspect
```

--------------------------------

### Committing Release Changes

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

Stages and commits the updated `spin/__init__.py` and `CHANGELOG.md` files with a descriptive commit message indicating the release version.

```git
git add spin/__init__.py CHANGELOG.md
git commit -m "Designate ${VERSION} release"
```

--------------------------------

### Accessing pyproject.toml Configuration

Source: https://github.com/scientific-python/spin/blob/main/README.md

Demonstrates how to access the pyproject.toml configuration within a custom Spin command using the `util.get_config()` function. This allows custom commands to read project-specific settings.

```python
from spin import util


@click.command()
def example():
    """Command that accesses `pyproject.toml` configuration"""
    config = util.get_config()
    print(config["tool.spin"])

```

--------------------------------

### Enabling Shell Auto-completion (Bash)

Source: https://github.com/scientific-python/spin/blob/main/README.md

Provides instructions for enabling shell auto-completion for Spin commands. This involves creating a completion file and sourcing it in the user's bash configuration.

```bash
_SPIN_COMPLETE=bash_source spin > ~/.spin-complete.bash

```

```bash
source ~/.spin-complete.bash

```

--------------------------------

### Committing Version Bump

Source: https://github.com/scientific-python/spin/blob/main/RELEASE.md

After pushing tags, this step commits and pushes the updated version number in `spin/__init__.py` to the main branch.

```git
git add spin/__init__.py
git commit -m 'Bump version'
git push origin main
```

--------------------------------

### Overriding Meson CLI Path

Source: https://github.com/scientific-python/spin/blob/main/README.md

Explains how to specify a custom path to the Meson CLI in the `pyproject.toml` file. This is useful for projects that use a vendored version of Meson.

```toml
[tool.spin.meson]
cli = 'path/to/custom/meson'

```

--------------------------------

### Overriding Default Arguments

Source: https://github.com/scientific-python/spin/blob/main/README.md

Shows how to override default arguments for custom commands by specifying values in the `[tool.spin.kwargs]` section of pyproject.toml. This allows for setting default values for click options or function keywords.

```python
@click.command()
@click.option("-f", "--flag")
@click.option("-t", "--test", default="not set")
def example(flag, test, default_kwd=None):
    """🧪 Example custom command.
    ...
    """

```

```toml
[tool.spin.kwargs]
".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.