Filters

Run or check a subset of the tasks with a filter expression. A filter selects the tasks by name or by group, and the operators combine the selections. The --filter option and the search box of the terminal UI accept the same language.

This example declares a group on each task (see Groups):

examples/ci/workflow.py

from pathlib import Path

from winslow import Workflow, Task

BUILD = Path("build")


class Ci(Workflow):
    """A workflow with task groups, to show the filter expressions. Delete the
    build directory to run it again."""


class MarkerTask(Task):
    """A task that writes one marker file. The check reports the file."""

    class Meta:
        abstract = True

    @property
    def marker_path(self):
        return BUILD / f"{self}.done"

    def run(self):
        BUILD.mkdir(exist_ok=True)
        self.marker_path.write_text("done\n")

    def check(self):
        return self.marker_path.exists()


class Lint(MarkerTask):
    groups = "static"


class Typecheck(MarkerTask):
    groups = "static"


class UnitTest(MarkerTask):
    groups = "tests"
    dependencies = (Lint, Typecheck)


class IntegrationTest(MarkerTask):
    groups = "tests"
    dependencies = UnitTest


class BuildWheel(MarkerTask):
    groups = "release"
    dependencies = IntegrationTest


class PublishWheel(MarkerTask):
    groups = "release"
    dependencies = BuildWheel

Download this example

Select by name

A bare word matches any task name that contains the word. The match is case-insensitive:

winslow run --filter 'lint'    # lint
winslow run --filter 'test'    # unit-test, integration-test

Select by group

The !g command selects every task of a group. The long form is !group:

winslow run --filter '!g static'    # lint, typecheck

Exclude with a negation

The ~ operator excludes instead of includes. It goes directly before the value. For a group, the negation comes after the command:

winslow run --filter '~publish'      # The five tasks that are not publish-wheel.
winslow run --filter '!g ~static'    # The four tasks outside the static group.

Combine the selections

The & operator demands both sides, and the | operator accepts either side. The words and and or are aliases. A comma is a shorthand for |, and parentheses set the evaluation order:

winslow run --filter 'lint,test'                # lint, unit-test, integration-test
winslow run --filter '!g static,tests'          # The four tasks of the two groups.
winslow run --filter '!g tests & ~integration'  # unit-test
winslow run --filter '~(lint | typecheck)'      # The four tasks that are neither.

The search box

The terminal UI has a search box that accepts the same expressions. The task list narrows as you type.

Custom filters

A plugin can add a custom filter command to this language. See Filter plugins.