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#