Writing Scripts¶

Overview¶

Workflow deinitions are text files in YAML format, that are read, compiled, and executed by the Task Runner.

Note

Unless you are a Python programmer, you may have to get used to the fact that whitespace matters in YAML files:
Make sure you indent uniformly. Don’t mix tabs and spaces. We recommend to use an editor that supports the YAML syntax (e.g. VS Code).

A simple confuguration script may look like this:
yabs.yaml:

# Yabs Workflow Definition
# See https://github.com/mar10/yabs
file_version: yabs#1

config:
  repo: 'mar10/test-release-tool'
  version:
    - type: __version__
      file: src/test_release_tool/__init__.py
  branches: main  # or master?


tasks:
  # The following tools are available. They are executed in the order
  # listed here

  # 'check': Assert preconditons and fail otherwise
  - task: check
    build: true             # dist/ folder exists
    can_push: true          # Test if 'git push' would/would not succeed
    clean: true             # Repo must/must not contain modifications
    python: ">=3.9"         # SemVer specifier
    twine: true             # `twine` is available
    up_to_date: true        # everything pulled from remote
    venv: true              # running inside a virtual environment
    version: true           # `setup.py --version` returns the configured version
    # winget: true            # `wingetcreate` is available
    yabs: ">=0.5"           # SemVer specifier

  # 'exec': Run arbitrary shell command
  - task: exec
    args: ["tox", "-e", "lint"]     # shell command and optional arguments
    always: true            # `true`: run even in dry-run mode

  # 'bump': Increment project version (requires argument: `yabs run --inc INC`)
  - task: bump
    inc: null               # Use value passed as 'yabs run --inc INC'

  # 'commit': Commit modified files
  - task: commit
    add_known: true         # Commit with -a flag
    message: |
      Bump version to {version}

  # 'tag': Create an annotated tag
  - task: tag
    name: v{version}
    message: |
      Version {version}

  # 'push': Push changes and tags
  - task: push
    tags: true

  # 'pypi_release': Create a release on PyPI using `twine`
  - task: pypi_release
    build:
      - sdist
      - bdist_wheel
    upload: true

  # 'github_release': Create a release on GitHub
  - task: github_release
    draft: false

  # Bump 'v1.2.3' => 'v1.2.4-a1'
  - task: bump
    inc: "postrelease"

  # Commit using '[ci skip]' as part of the message to prevent CI testing
  - task: commit
    add_known: true
    message: |
      Bump prerelease ({version}) [ci skip]

  # Push to GitHub
  - task: push

See yabs.yaml for a complete configuration with all available options and defaults.

Note

To get started, run yabs init inside your project’s directory. This will prompt for a few details and create a fresh yabs.yaml file.

Task Types¶

Template Macros¶

Some tasks have string options such as tag names, commit messges, etc. These strings may contain inline macros that will be expanded.

Typical macros are version, tag_name, repo, …
Macro names must be embedded in curly braces, for example:

- task: github_release
  name: 'v{version}'
  message: |
    Released {version}

    [Changelog](https://github.com/{repo}/blob/master/CHANGELOG.md),
    [Commit details](https://github.com/{repo}/compare/{org_tag_name}...{tag_name}).

All attributes of the task context are available as macros:

{inc}: Value of the --inc argument.
{org_tag_name}: The repo’s latest tag name (before ‘bump’).
{org_version}: Latest version (before ‘bump’).
{repo}: GitHub repo name, e.g. ‘USER/PROJECT’.
{tag_name}: The current tag name (after ‘bump’).
{version}: Current version (after ‘bump’).

See TaskContext for a complete list.

Version Locations¶

Note

Currently only a small subset is implemented.
Please open an issue if you need another one and are ready to help with testing.

(TODO: verify this section.)

Although there seems to be consent that Python projects should have a version number that is stored at one central location, the community has not agreed upon that location yet.

In order to find and bump this versions, we need to pass a hint in the configuration yabs.yaml like so:

file_version: yabs#1
config:
  ...
  version:
    - type: __version__  # Example!
      file: src/my_project/__init__.py
...

Yabs supports some common approaches.
Following some typical patterns how Python projects store version numbers.

Note

Currently we would recommend this variant (unless Poetry is used):
Store the version in __init__.py of the project’s root folder:

__version__ = "1.2.3"

Then reference this in setup.cfg:

[metadata]
name = my_package
version = attr: my_project.__version__

This would then configured in yabs.yaml like so:

config:
  version:
    - type: __version__
      file: my_project/__init__.py

See below for details about the different use cases.

Poetry¶

Todo

Not yet implemented.

Poetry stores the version number in its own section in pyproject.toml (defined in PEP-518):

pyproject.toml:

[project]
...
[tool.poetry]
name = "my_project"
version =  "1.2.3"

yabs.yaml:

config:
  version:
    - type: poetry

flit¶

Todo

Not yet implemented.

init.py of the project’s root package¶

__init__.py:

__version__ = "1.2.3"

yabs.yaml:

config:
  version:
    - type: __version__
      file: src/my_project/__init__.py

Or a variant the mimics Python’s sys.version_info style:

__init__.py:

version_info = (1, 2, 3)
version = ".".join(str(c) for c in version_info)

yabs.yaml:

config:
  version:
    # TODO

Plain Text File¶

For example a _version.txt file in the project’s src folder containing:

_version.txt:

1.2.3

yabs.yaml:

config:
  version:
    # TODO

setup.cfg¶

Debugging¶

Use the --verbose (short -v) option to generate more console logging.
Use the --dry-run (short -n) option to run all tasks in a simulation mode:

$ yabs run --inc patch -vn

Writing Scripts¶

Overview¶

Task Types¶

Template Macros¶

Version Locations¶

Poetry¶

flit¶

__init__.py of the project’s root package¶

Plain Text File¶

setup.cfg¶

Debugging¶

init.py of the project’s root package¶