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. The History tab has its own search box. It accepts the name and group filters of this page, and it narrows the recorded batches of the session, an ended session included.

Custom filters

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