Run a script of the model¶
This guide is for a task you repeat on samples, written once in the model: an attribute filled from a value, a reading corrected, a report printed, a sample made from others. A script runs from the command line or the terminal interface, on the samples you select, and what it changes is shown before it is written.
The examples are the scripts of the home page's tensile example, in its last step.
1. Mark a method @sk.script¶
In the model:
class Specimen(sk.Sample):
# … its properties and formulas …
@sk.script
def classify(self, limit: float = 20.0):
"""Class the specimen's ductility by its elongation at break."""
self.ductility = "high" if self.elongation.value >= limit else "low"
@sk.script
@classmethod
def ranking(cls, samples, by: str = "tensile_strength"):
"""Print the specimens from the highest value of a field to the lowest."""
for rank, specimen in enumerate(samples.sorted(f"-{by}"), start=1):
print(rank, specimen.name, specimen[by])
A method acts on one sample, and runs on each sample selected in turn. Placed above
@classmethod, it receives the selection, a list of samples, once.Its keyword parameters are the command's options, given with
--set: typed by their annotation,int,float,boolorstr, or by their default. A parameter with no default must be given.Its docstring's first paragraph is its description.
list scripts lists them, with their options:
$ samplekit list scripts
classify on each sample
Class the specimen's ductility by its elongation at break.
--set limit=NUMBER 20.0 by default
ranking on the selection
Print the specimens from the highest value of a field to the lowest.
--set by=TEXT tensile_strength by default
2. Run it¶
run runs a script on the samples a command reads: a folder, files, -f, a
query. What it changes in samples, a value set, an attribute, a sample saved
or made, is shown, then written with --write, or on y when it asks:
$ samplekit run classify --set limit=15
run classify · 3 files changed
samples/aluminium-01.md
ductility — → low
samples/copper-01.md
ductility — → high
samples/steel-01.md
ductility — → high
nothing becomes not current
apply these changes? [y/N] n
nothing written
What it writes is one change of the project's history, which restore takes
back. A file someone changed while the script ran is refused, not
overwritten. What the script writes itself, a figure or a CSV file, is its
own: neither shown nor kept in the history.
3. What it prints, and what it returns¶
What a script prints is shown as it prints it:
$ samplekit run ranking
1 steel-01 518 MPa
2 aluminium-01 318 MPa
3 copper-01 221 MPa
A script may ask with input(). On the command line the question is asked in
the terminal, as Python itself would ask it, and the preview lists each
answer, asked Factor? 0.5, before anything is written; the history keeps
them with the command, samplekit run scale --write — answered 'Factor?' 0.5. With no terminal to answer, in a pipe or a scheduled job, the script
fails and says so: give it its values with --set instead. In the terminal
interface the script runs in a window that shows what it prints as it
prints it, and the question is answered on the line at its foot.
What it returns is shown too, each kind as the command line shows it:
It returns |
Shown as |
|---|---|
a text |
the text |
a property |
its value, in |
a table |
the table, as |
a sample |
the sample, as |
a list of samples |
their files' paths, one per line |
a summary |
a row as |
a list of these |
each, in order |
anything else |
its text, |
4. From Python¶
A script is a method of the model, and Python calls it as one: on a sample
for a method, on the model's class with a list for a class method. Nothing is
previewed then, and what it changes is written by save(), as any change
from Python:
"""The model's scripts, called from Python."""
import samplekit as sk
specimens = sk.load("samples")
for specimen in specimens:
specimen.classify(limit=15)
print(specimen.name, specimen.ductility)
type(specimens[0]).ranking(specimens, by="elongation")
$ python scripts/model_scripts.py
aluminium-01 low
copper-01 high
steel-01 high
1 copper-01 44.0 %
2 steel-01 24.0 %
3 aluminium-01 12.0 %
5. In the terminal interface¶
p runs a script on the sample open, on the basket, or on the samples shown:
its menu lists the scripts first, then the figures and the exports, Tab
from one group to the next. Choose the script and change its options; it
runs in a window that shows what it prints, where a question it asks is
answered on the last line. Then read what it changed before y writes it; u takes it back (work in the
terminal interface).
See also¶
Work from Python: a script of your own, outside the model.