Skip to content

stepup.core.stepinfo

Information about a step in a StepUp build, intended for defining follow-up steps.

StepInfo

The step() function returns an instance of this class to help defining follow-up steps.

This object will not contain any information that is amended while the step is executed. It only holds information known at the time the step is defined.

All paths and environment variables are stored in sorted order to ensure consistency.

Source code in stepup/core/stepinfo.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@attrs.define
class StepInfo:
    """The `step()` function returns an instance of this class to help defining follow-up steps.

    This object will not contain any information that is amended while the step is executed.
    It only holds information known at the time the step is defined.

    All paths and environment variables are stored in sorted order to ensure consistency.
    """

    command: str = attrs.field(converter=str)
    """The command of the step."""

    workdir: Path = attrs.field(converter=Path)
    """The work directory of the step.

    If relative, it is relative to the StepUp root."""

    inp: list[Path] = attrs.field(converter=_convert_to_paths)
    """List of input paths of the step.

    If relative, they are relative to the work directory.
    """

    env: list[str] = attrs.field(converter=_convert_to_strs)
    """List of environment values used by the step."""

    out: list[Path] = attrs.field(converter=_convert_to_paths)
    """List of output paths of the step.

    If relative, they are relative to the work directory.
    """

    vol: list[Path] = attrs.field(converter=_convert_to_paths)
    """List of volatile output paths of the step.

    If relative, they are relative to the work directory.
    """

    def filter_inp(self, *patterns: str, **subs: str):
        """Return an `NGlobMulti` object with matching results from `self.inp`."""
        ngm = NGlobMulti.from_patterns(patterns, subs)
        ngm.extend(self.inp)
        return ngm

    def filter_out(self, *patterns: str, **subs: str):
        """Return an `NGlobMulti` object with matching results from `self.out`."""
        ngm = NGlobMulti.from_patterns(patterns, subs)
        ngm.extend(self.out)
        return ngm

    def filter_vol(self, *patterns: str, **subs: str):
        """Return an `NGlobMulti` object with matching results from `self.vol`."""
        ngm = NGlobMulti.from_patterns(patterns, subs)
        ngm.extend(self.vol)
        return ngm

command = attrs.field(converter=str) class-attribute instance-attribute

The command of the step.

env = attrs.field(converter=_convert_to_strs) class-attribute instance-attribute

List of environment values used by the step.

inp = attrs.field(converter=_convert_to_paths) class-attribute instance-attribute

List of input paths of the step.

If relative, they are relative to the work directory.

out = attrs.field(converter=_convert_to_paths) class-attribute instance-attribute

List of output paths of the step.

If relative, they are relative to the work directory.

vol = attrs.field(converter=_convert_to_paths) class-attribute instance-attribute

List of volatile output paths of the step.

If relative, they are relative to the work directory.

workdir = attrs.field(converter=Path) class-attribute instance-attribute

The work directory of the step.

If relative, it is relative to the StepUp root.

filter_inp(*patterns, **subs)

Return an NGlobMulti object with matching results from self.inp.

Source code in stepup/core/stepinfo.py 
80
81
82
83
84
def filter_inp(self, *patterns: str, **subs: str):
    """Return an `NGlobMulti` object with matching results from `self.inp`."""
    ngm = NGlobMulti.from_patterns(patterns, subs)
    ngm.extend(self.inp)
    return ngm

filter_out(*patterns, **subs)

Return an NGlobMulti object with matching results from self.out.

Source code in stepup/core/stepinfo.py 
86
87
88
89
90
def filter_out(self, *patterns: str, **subs: str):
    """Return an `NGlobMulti` object with matching results from `self.out`."""
    ngm = NGlobMulti.from_patterns(patterns, subs)
    ngm.extend(self.out)
    return ngm

filter_vol(*patterns, **subs)

Return an NGlobMulti object with matching results from self.vol.

Source code in stepup/core/stepinfo.py 
92
93
94
95
96
def filter_vol(self, *patterns: str, **subs: str):
    """Return an `NGlobMulti` object with matching results from `self.vol`."""
    ngm = NGlobMulti.from_patterns(patterns, subs)
    ngm.extend(self.vol)
    return ngm

dump_step_info(filename, step_info)

Dump one or more step info objects to a JSON file.

The file will contain a single JSON object or a JSON array of such objects.

Source code in stepup/core/stepinfo.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
def dump_step_info(filename: str, step_info: StepInfo | list[StepInfo]):
    """Dump one or more step info objects to a JSON file.

    The file will contain a single JSON object or a JSON array of such objects.
    """
    with open(filename, "w") as fh:
        data = (
            attrs.asdict(step_info)
            if isinstance(step_info, StepInfo)
            else [attrs.asdict(si) for si in step_info]
        )
        json.dump(data, fh, indent=2)
        fh.write("\n")

load_step_info(filename)

Load one or more step info object from a JSON file.

The file should contain a single JSON object or a JSON array of such objects.

Source code in stepup/core/stepinfo.py 
 99
100
101
102
103
104
105
106
def load_step_info(filename: str) -> StepInfo | list[StepInfo]:
    """Load one or more step info object from a JSON file.

    The file should contain a single JSON object or a JSON array of such objects.
    """
    with open(filename) as fh:
        data = json.load(fh)
        return StepInfo(**data) if isinstance(data, dict) else [StepInfo(**item) for item in data]