Versions¶

Needs the extra scriptt[versions] (DVC).

Versions of a project that git and DVC keep. You can run the steps and keep a version and list versions. You can also read a result as it was in any version. This needs the extra scriptt[versions] (DVC).

from scriptt.world.versions import Project, Result


class ModelScore(Result, path="results/model.json"):
    model: str
    right: int


project = Project(".")
project.run()  # dvc repro: the steps whose inputs changed
project.keep(
    "R3 reads the entry date"
)  # git commit of code, settings, results and dvc.lock
for version in project.versions():
    print(version, version.read(ModelScore))

Result ¶

Bases: BaseModel

A result that a step writes and a version keeps. A result is a frozen Pydantic model.

Declare where the result lives with class Score(Result, path="results/score.json"). The path is relative to the project folder.

Example

from scriptt.world.versions import Result


class Score(Result, path="results/score.json"):
    model: str
    right: int


Score(model="baseline", right=4).right  # -> 4
Score.path  # -> 'results/score.json'

model_config `class-attribute` `instance-attribute` ¶

model_config = ConfigDict(frozen=True)

path `class-attribute` ¶

path: str

save ¶

save(project: Project | str | Path = '.') -> Path

Write the result to the file that its type names, in the project folder.

The folder of the file is made if it does not exist. The file contains JSON.

Parameters:

Name	Type	Description	Default
`project`	`Project \| str \| Path`	A `Project` or the path of the project folder. The default is `"."`. This is the current folder.	`'.'`

Returns:

Type	Description
`Path`	The path of the file.

Example

# project: a Project
# ModelScore: a Result with path="results/score.json"
path = ModelScore(model="baseline", right=5).save(project)
path.name  # -> 'score.json'

Version `dataclass` ¶

Version(
    id: str, time: datetime, message: str, project: Project
)

1 kept version. It is a git commit. Project.versions and Project.keep make versions.

Attributes:

Name	Type	Description
`id`	`str`	The short git hash of the commit.
`time`	`datetime`	The time of the commit. It has no time zone.
`message`	`str`	The message that you gave to `keep`.
`project`	`Project`	The project that keeps the version.

id `instance-attribute` ¶

id: str

time `instance-attribute` ¶

time: datetime

message `instance-attribute` ¶

message: str

project `instance-attribute` ¶

project: Project

read ¶

read(result: type[R]) -> R

Read a result as this version kept it.

Parameters:

Name	Type	Description	Default
`result`	`type[R]`	The `Result` type. Its `path` says which file to read.	required

Returns:

Type	Description
`R`	The result as a `result` object.

Raises:

Type	Description
`ValidationError`	The file of that version does not fit the type.

Example

# project: a Project with 1 kept version
# ModelScore: a Result with path="results/score.json"
first = project.versions()[0]
first.read(ModelScore).right  # -> 4

file ¶

file(path: str) -> bytes

Read any file as this version kept it. This includes code and settings and DVC data.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path of the file, relative to the project folder.	required

Returns:

Type	Description
`bytes`	The content of the file as bytes.

Example

# project: a Project with 1 kept version
project.versions()[0].file("params.yaml").decode().strip()
# -> 'journals: 4'

Kept `dataclass` ¶

Kept(version: Version, result: R, older_forms: int)

1 kept version and its result. Project.results makes it.

Attributes:

Name	Type	Description
`version`	`Version`	The kept version.
`result`	`R`	The result as that version kept it.
`older_forms`	`int`	The number of earlier versions that `Project.results` left out so far. Their file has a form that the type cannot read.

version `instance-attribute` ¶

version: Version

result `instance-attribute` ¶

result: R

older_forms `instance-attribute` ¶

older_forms: int

Run `dataclass` ¶

Run(
    name: str,
    settings: dict[str, Any],
    results: dict[str, Any],
)

1 run that Project.try_settings made and that you have not kept as a version.

Attributes:

Name	Type	Description
`name`	`str`	The name that you gave to the run.
`settings`	`dict[str, Any]`	The settings of the run as a dictionary from name to value.
`results`	`dict[str, Any]`	The results of the run that DVC shows as a dictionary. It can be empty.

name `instance-attribute` ¶

name: str

settings `instance-attribute` ¶

settings: dict[str, Any]

results `instance-attribute` ¶

results: dict[str, Any]

Project `dataclass` ¶

Project(root: str | Path)

A folder with git and DVC. dvc.yaml contains the steps and params.yaml contains the settings.

The folder must be a git repository with DVC set up in that folder (it has .dvc/). Give the path of the folder to the constructor. A project runs DVC and git commands. These change the current folder and print while they run. So use 1 project at a time in a process.

Parameters:

Name	Type	Description	Default
`root`	`str \| Path`	The path of the project folder. `~` is expanded and the path is made absolute.	required

Raises:

Type	Description
`ValueError`	The folder has no `.dvc/` folder. (DVC would use a parent project instead.)

Example

from scriptt.world.versions import Project

Project(".").root.is_absolute()  # -> True

root `instance-attribute` ¶

root: Path

run ¶

run() -> Self

Run the steps whose inputs changed (dvc repro).

The steps run in the project folder. The current folder does not matter.

Returns:

Type	Description
`Self`	The same project. So you can chain calls.

Raises:

Type	Description
`StageFileDoesNotExistError`	The project folder has no `dvc.yaml`.

Example

# project: a Project with 1 kept version
project.run().root == project.root  # -> True

try_settings ¶

try_settings(name: str, **settings: Any) -> Run

Run the steps with changed settings (dvc exp run -S). This does not make a new version. DVC keeps the run.

Write a dotted setting name with __. For example the keyword e3__journals sets e3.journals. The steps run in the project folder. DVC leaves the trial settings in the working params.yaml. Set them back before keep.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the run.	required
`**settings`	`Any`	The settings to change as keyword arguments.	`{}`

Returns:

Type	Description
`Run`	The `Run`.

Example

# project: a Project with 1 kept version and a setting called journals
run = project.try_settings("more", journals=8)
run.name, run.settings["journals"]  # -> ('more', 8.0)

keep ¶

keep(message: str, *new_files: str | Path) -> Version

Keep a new version: make a git commit.

The commit contains these files.

Every file that git already tracks and that changed (code, settings, results and dvc.lock).
The new files that you name.

Other new files stay out.

Parameters:

Name	Type	Description	Default
`message`	`str`	The commit message. It is the message of the version.	required
`*new_files`	`str \| Path`	Paths of new files to add to git. The default is none.	`()`

Returns:

Type	Description
`Version`	The new `Version`.

Example

# project: a Project with 1 kept version and a setting called journals
from pathlib import Path

Path("params.yaml").write_text("journals: 6")
project.run()
project.keep("more journals").message  # -> 'more journals'

versions ¶

versions(of: type[Result] | None = None) -> Facts[Version]

List the kept versions, oldest first.

Parameters:

Name	Type	Description	Default
`of`	`type[Result] \| None`	A `Result` type. The default `None` means every version. A type limits the list to the versions that changed that result file.	`None`

Returns:

Type	Description
`Facts[Version]`	A collection of `Version` objects.

Example

# project: a Project with 1 kept version
# ModelScore: a Result with path="results/score.json"
[version.message for version in project.versions()]  # -> ['first run']
[version.message for version in project.versions(of=ModelScore)]
# -> ['first run']

results ¶

results(of: type[R]) -> Facts[Kept[R]]

List each version that changed a result. The result is read as a type. The oldest version comes first.

A version whose file has an older form that the type cannot read is left out. older_forms on each Kept counts those versions so far.

Parameters:

Name	Type	Description	Default
`of`	`type[R]`	The `Result` type to read.	required

Returns:

Type	Description
`Facts[Kept[R]]`	A collection of `Kept` objects.

Example

# project: a Project with 1 kept version
# ModelScore: a Result with path="results/score.json"
[kept.result.right for kept in project.results(ModelScore)]  # -> [4]

runs ¶

runs() -> Facts[Run]

List the runs from try_settings that you have not kept as versions.

Returns:

Type	Description
`Facts[Run]`	A collection of `Run` objects.

Example

# project: a Project with 1 kept version and a setting called journals
project.try_settings("more", journals=8)
[run.name for run in project.runs()]  # -> ['more']

Versions¶

Result ¶

model_config class-attribute instance-attribute ¶

path class-attribute ¶

save ¶

Version dataclass ¶

id instance-attribute ¶

time instance-attribute ¶

message instance-attribute ¶

project instance-attribute ¶

read ¶

file ¶

Kept dataclass ¶

version instance-attribute ¶

result instance-attribute ¶

older_forms instance-attribute ¶

Run dataclass ¶

name instance-attribute ¶

settings instance-attribute ¶

results instance-attribute ¶

Project dataclass ¶

root instance-attribute ¶

run ¶

try_settings ¶

keep ¶

versions ¶

results ¶

runs ¶

model_config `class-attribute` `instance-attribute` ¶

path `class-attribute` ¶

Version `dataclass` ¶

id `instance-attribute` ¶

time `instance-attribute` ¶

message `instance-attribute` ¶

project `instance-attribute` ¶

Kept `dataclass` ¶

version `instance-attribute` ¶

result `instance-attribute` ¶

older_forms `instance-attribute` ¶

Run `dataclass` ¶

name `instance-attribute` ¶

settings `instance-attribute` ¶

results `instance-attribute` ¶

Project `dataclass` ¶

root `instance-attribute` ¶