lazyscribe package¶

Subpackages¶

Submodules¶

Custom exceptions for lazyscribe.

exception lazyscribe.exception.ArtifactError[source]¶

Bases: LazyscribeError

Base exception for artifact errors.

exception lazyscribe.exception.ArtifactLoadError[source]¶

Bases: ArtifactError

Raised when an artifact cannot be loaded.

exception lazyscribe.exception.ArtifactLogError[source]¶

Bases: ArtifactError

Raised when an artifact cannot be logged.

exception lazyscribe.exception.LazyscribeError[source]¶

Bases: Exception

Base exception for lazyscribe errors.

exception lazyscribe.exception.ReadOnlyError[source]¶

Bases: LazyscribeError

Raised when a project or repository is opened in read-only mode and write operations are tried.

exception lazyscribe.exception.SaveError[source]¶

Bases: LazyscribeError

Raised when a project or repository is unable to save objects to the filesystem.

Experiment dataclass.

class lazyscribe.experiment.Experiment(name: str, project: Path, dir: Path = NOTHING, fs: AbstractFileSystem = NOTHING, author: str = NOTHING, last_updated_by: str = NOTHING, metrics: dict = NOTHING, parameters: dict = NOTHING, created_at: datetime = NOTHING, last_updated: datetime = NOTHING, dependencies: dict = NOTHING, short_slug: str = NOTHING, slug: str = NOTHING, tests: list[Test | ReadOnlyTest] = NOTHING, artifacts: list[Artifact] = NOTHING, tags: list[str] = NOTHING, dirty: bool = NOTHING)[source]¶

Bases: object

Experiment data class.

This class is not meant to be initialized directly. It is meant to be used through the lazyscribe.project.Project class.

Parameters¶

namestr: The name of the experiment.
projectPath: The path to the project JSON associated with the project.
authorstr, optional (default getpass.getuser()): The author of the experiment.
metricsdict, optional (default {}): A dictionary of metric values. Each metric value can be an individual value or a list.
parametersdict, optional (default {}): A dictionary of experiment parameters. The key must be a string but the value can be anything.
created_atdatetime, optional (default utcnow()): When the experiment was created.
last_updateddatetime, optional (default utcnow()): When the experiment was last updated.
dependenciesdict, optional (default None): A dictionary of upstream project experiments. The key is the short slug for the upstream experiment and the value is an Experiment instance.

artifacts: list[Artifact]¶

author: str¶

created_at: datetime¶

dependencies: dict¶

dir: Path¶

dirty: bool¶

fs: AbstractFileSystem¶

last_updated: datetime¶

last_updated_by: str¶

load_artifact(name: str, validate: bool = True, **kwargs) → Any[source]¶

Load a single artifact.

Parameters¶

namestr: The name of the artifact to load.
validatebool, optional (default True): Whether or not to validate the runtime environment against the artifact metadata.
**kwargsdict: Keyword arguments for the handler read function.

Returns¶

object: The artifact.

Raises¶

ArtifactLoadError: If validate and runtime environment does not match artifact metadata. Or if there is no artifact found with the name provided.

log_artifact(name: str, value: Any, handler: str, fname: str | None = None, overwrite: bool = False, **kwargs)[source]¶

Log an artifact to the experiment.

This method associates an artifact with the experiment, but the artifact will not be written until lazyscribe.Project.save() is called.

Parameters¶

namestr: The name of the artifact.
valueAny: The object to persist to the filesystem.
handlerstr: The name of the handler to use for the object.
fnamestr, optional (default None): The filename for the artifact. If not provided, it will be derived from the name of the artifact and the builtin suffix for each handler.
overwritebool, optional (default False): Whether or not to overwrite an existing artifact with the same name. If set to True, the previous artifact will be removed and overwritten with the current artifact.
**kwargsdict: Keyword arguments for the write function of the handler.

Raises¶

ArtifactLogError: Raised if an artifact is supplied with the same name as an existing artifact and overwrite is set to False.

log_metric(name: str, value: float | int)[source]¶

Log a metric to the experiment.

This method will overwrite existing keys.

Parameters¶

namestr: Name of the metric.
valueint or float: Value of the metric.

log_parameter(name: str, value: Any)[source]¶

Log a parameter to the experiment.

This method will overwrite existing keys.

Parameters¶

namestr: The name of the parameter.
valueAny: The parameter itself.

log_test(name: str, description: str | None = None) → Iterator[Test][source]¶

Add a test to the experiment using a context handler.

A test is a specific location for non-global metrics.

Parameters¶

namestr: Name of the test.
descriptionstr, optional (default None): An optional description for the test.

Yields¶

Test: The lazyscribe.test.Test dataclass.

metrics: dict¶

name: str¶

parameters: dict¶

property path: Path¶

Path to an experiment folder.

This folder can be used to store any plots or artifacts that you want to associate with the experiment.

Returns¶

Path: The path for the experiment.

project: Path¶

promote_artifact(repository: Repository, name: str)[source]¶

Associate an artifact with a lazyscribe.repository.Repository.

The purpose of this method is to move an artifact from an ephemeral experiment to the versioned repository.

If the artifact does not exist on disk yet, this function is simply a passthrough to lazyscribe.repository.Repository.log_artifact(). If the artifact does exist on disk already, this function will copy the artifact from the experiment directory to the repository, increment the version, and call lazyscribe.repository.Repository.save().

Parameters¶

repositoryRepository: The lazyscribe.repository.Repository to promote the artifact to.
namestr: The artifact to promote.

Raises¶

ArtifactLogError

Raised if the artifact to be promoted is not newer than the latest version available in the repository.

Raised if

the artifact name exists on the filesystem, and
the filesystem protocol does not match between the repository and the experiment.

ArtifactLoadError

Raised if there is no artifact with the name name in the experiment.

short_slug: str¶

slug: str¶

tag(*args, overwrite: bool = False)[source]¶

Add one or more tags to the experiment.

Important

If this function is called with no supplied values for *args _and_ overwrite=True, the result will be that the experiment has no associated tags.

Parameters¶

*args: The tags.
overwritebool, optional (default False): Whether to add or overwrite the new tags.

tags: list[str]¶

tests: list[Test | ReadOnlyTest]¶

to_dict() → dict[source]¶

Serialize the experiment to a dictionary.

Returns¶

dict: The experiment dictionary.

to_tabular() → dict[source]¶

Create a dictionary that can be fed into pandas.

Returns¶

dict

Represent the experiment, with the following keys:

Field	Description
`("name",)`	Name of the experiment
`("short_slug",)`	Short slug for the experiment
`("slug",)`	Full slug for the experiment
`("author",)`	Experiment author
`("last_updated_by",)`	Last author
`("created_at",)`	Created timestamp
`("last_updated",)`	Last update timestammp

as well as one key per parameter in the parameters dictionary (with the format ("parameters", <parameter_name>)) and one key per metric in the metrics dictionary (with the format ("metrics", <metric_name>)) for each experiment.

class lazyscribe.experiment.ReadOnlyExperiment(name: str, project: Path, dir: Path = NOTHING, fs: AbstractFileSystem = NOTHING, author: str = NOTHING, last_updated_by: str = NOTHING, metrics: dict = NOTHING, parameters: dict = NOTHING, created_at: datetime = NOTHING, last_updated: datetime = NOTHING, dependencies: dict = NOTHING, short_slug: str = NOTHING, slug: str = NOTHING, tests: list[Test | ReadOnlyTest] = NOTHING, artifacts: list[Artifact] = NOTHING, tags: list[str] = NOTHING, dirty: bool = NOTHING)[source]¶

Bases: Experiment

Immutable version of an experiment.

Linked list utilities.

The code for this module is lifted from here.

class lazyscribe.linked.LinkedList(head: Any = None)[source]¶

Bases: object

The linked list.

Parameters¶

headany, optional (default None): The start of the list.

append(data: Any)[source]¶

Append a new node to the end of the list.

Parameters¶

dataAny: The new data.

static from_list(data: list) → LinkedList[source]¶: Convert a standard list to a linked list.

head: Any¶

class lazyscribe.linked.Node(data: Any = None, next: Any = None)[source]¶

Bases: object

Node for the linked list.

Parameters¶

dataany, optional (default None): The current data.
nextany, optional (default None): The next data in the chain.

data: Any¶

next: Any¶

to_list() → list[source]¶

Convert the nodes to a de-duped list.

Returns¶

list: A standard list.

lazyscribe.linked.merge(list1: Node, list2: Node) → Any[source]¶

Merge two linked lists.

Parameters¶

list1Node: The head of the first list.
list2Node: The head of the second list.

Returns¶

Node: The head of the final, merged list.

Project storing and logging.

class lazyscribe.project.Project(fpath: str | Path = 'project.json', mode: Literal['r', 'a', 'w', 'w+'] = 'w', author: str | None = None, **storage_options)[source]¶

Bases: object

Project class.

Parameters¶

fpathstr, optional (default “project.json”)

The location of the project file. If no project file exists, this will be the location of the output JSON file when save is called.

mode{“r”, “a”, “w”, “w+”}, optional (default “w”)

The mode for opening the project.

r: All existing experiments will be loaded as lazyscribe.experiment.ReadOnlyExperiment and no new experiments can be logged.
a: All existing experiments will be loaded as lazyscribe.experiment.ReadOnlyExperiment and new experiments can be added.
w: No existing experiments will be loaded.
w+: All experiments will be loaded in editable mode as lazyscribe.experiment.Experiment.

authorstr, optional (default None)

The project author. This author will be used for any new experiments or modifications to existing experiments. If not supplied, getpass.getuser() will be used.

storage_optionsdict, optional (default None)

Storage options to pass to the filesystem initialization. Will be passed to fsspec.filesystem.

Attributes¶

experimentslist: The list of experiments in the project.

append(other: Experiment)[source]¶

Append an experiment to the project.

For details on the merging process, see here.

Parameters¶

otherExperiment: The experiment to add.

Raises¶

ReadOnlyError: Raised when trying to log a new experiment when the project is in read-only mode.

filter(func: Callable) → Iterator[Experiment | ReadOnlyExperiment][source]¶

Filter the experiments in the project.

Parameters¶

funcCallable: A callable that takes in a lazyscribe.Experiment object and returns a boolean indicating whether or not it passes the filter.

Yields¶

Experiment: An experiment.

load()[source]¶

Load existing experiments.

If the project is in read-only or append mode, existing experiments will be loaded in read-only mode. If opened in editable mode, existing experiments will be loaded in editable mode.

log(name: str) → Iterator[Experiment][source]¶

Log an experiment to the project.

Parameters¶

namestr: The name of the experiment.

Yields¶

Experiment: A new Experiment data class.

Raises¶

ReadOnlyError: Raised when trying to log a new experiment when the project is in read-only mode.

merge(other: Project) → Project[source]¶

Merge two projects.

The new project will inherit the current project fpath, author, and mode.

For details on the merging process, see here.

Returns¶

Project: A new project.

save()[source]¶

Save the project data.

This includes saving any artifact data.

Raises¶

SaveError: Raised when writing to the filesystem fails.

to_tabular() → tuple[list[dict], list[dict]][source]¶

Create a dictionary that can be fed into pandas.

This method depends on the user consistently logging the same metrics and parameters to each experiment in the project.

Returns¶

list[dict]

The experiments list. Each entry is a result of :py:method:`lazyscribe.Experiment.to_tabular` per project’s experiment.

list[dict]

The tests list. Each entry is a result of :py:method:`lazyscribe.Test.to_tabular` per test per project’s experiment, with the following additional keys:

Field	Description
`("experiment_name",)`	Name of the test’s experiment
`("experiment_short_slug",)`	Short slug for the test’s experiment
`("experiment_slug",)`	Full slug for the test’s experiment
`("test",)`	Test name
`("description",)`	Test description

Repository storing and logging.

class lazyscribe.repository.Repository(fpath: str | Path = 'repository.json', mode: Literal['r', 'a', 'w', 'w+'] = 'w', **storage_options)[source]¶

Bases: object

Repository class for holding versioned artifacts.

Parameters¶

fpathstr | Path, optional (default “repository.json”)

The location of the repository file. If no repository file exists, this will be the location of the output JSON file when save is called.

mode{“r”, “a”, “w”, “w+”}, optional (default “w”)

The mode for opening the repository.

r: No new artifacts can be logged.
a: The same as w+ (deprecated).
w: No existing artifacts will be loaded.
w+: All artifacts will be loaded.

Attributes¶

artifactslist[Artifact]: The list of artifacts in the repository.

get_artifact_metadata(name: str, version: datetime | str | int | None = None, match: Literal['asof', 'exact'] = 'exact') → dict[str, Any][source]¶

Retrieve the metadata for an artifact.

Parameters¶

namestr: The name of the artifact to load.
versiondatetime.datetime | str | int, optional (default None): The version of the artifact to load. Can be provided as a datetime corresponding to the created_at field, a string corresponding to the created_at field in the format "%Y-%m-%dT%H:%M:%S" (e.g. "2025-01-25T12:36:22"), or an integer version. If set to None or not provided, defaults to the most recent version.
match“asof” | “exact”, optional (default “exact”): Matching logic. Only relevant for str and datetime.datetime values for version. exact will provide an artifact with the exact created_at value provided. asof will provide the most recent version as of the version value.

Returns¶

dict: The artifact metadata.

load()[source]¶: Load existing artifacts.

load_artifact(name: str, validate: bool = True, version: datetime | str | int | None = None, match: Literal['asof', 'exact'] = 'exact', **kwargs) → Any[source]¶

Load a single artifact.

Parameters¶

namestr: The name of the artifact to load.
validatebool, optional (default True): Whether or not to validate the runtime environment against the artifact metadata.
versiondatetime.datetime | str | int, optional (default None): The version of the artifact to load. Can be provided as a datetime corresponding to the created_at field, a string corresponding to the created_at field in the format "%Y-%m-%dT%H:%M:%S" (e.g. "2025-01-25T12:36:22"), or an integer version. If set to None or not provided, defaults to the most recent version.
match“asof” | “exact”, optional (default “exact”): Matching logic. Only relevant for str and datetime.datetime values for version. exact will provide an artifact with the exact created_at value provided. asof will provide the most recent version as of the version value.
**kwargsdict: Keyword arguments for the handler read function.

Returns¶

Any: The artifact object.

log_artifact(name: str, value: Any, handler: str, fname: str | None = None, **kwargs)[source]¶

Log an artifact to the repository.

This method associates an artifact with the repository, but the artifact will not be written until lazyscribe.Repository.save() is called.

Parameters¶

namestr: The name of the artifact.
valueAny: The object to persist to the filesystem.
handlerstr: The name of the handler to use for the object.
fnamestr, optional (default None): The filename for the artifact. If set to None or not provided, it will be derived from the name of the artifact and the builtin suffix for each handler.
**kwargsdict: Keyword arguments for the write function of the handler.

Raises¶

ReadOnlyError: If repository is in read-only mode.

save()[source]¶

Save the repository data.

This includes saving any artifact data.

Raises¶

SaveError: Raised when writing to the filesystem fails.

Sub-population tests.

class lazyscribe.test.ReadOnlyTest(name: str, description: str | None = NOTHING, metrics: dict = NOTHING, parameters: dict = NOTHING)[source]¶

Bases: Test

Immutable version of the test.

class lazyscribe.test.Test(name: str, description: str | None = NOTHING, metrics: dict = NOTHING, parameters: dict = NOTHING)[source]¶

Bases: object

Sub-population tests.

These objects should only be instantiated within an experiment. A test is associated with some subset of the entire experiment. For example, a test could be used to evaluate the performance of a model against a specific subpopulation.

Parameters¶

namestr: The name of the test.
descriptionstr, optional (default None): A description of the test.
metricsdict, optional (default {}): A dictionary of metric values. Each metric value can be an individual value or a list.
parametersdict, optional (default {}): A dictionary of test parameters. The key must be a string but the value can be anything.

description: str | None¶

log_metric(name: str, value: float | int)[source]¶

Log a metric to the test.

This method will overwrite existing keys.

Parameters¶

namestr: Name of the metric.
valueint or float: Value of the metric.

log_parameter(name: str, value: Any)[source]¶

Log a parameter to the test.

This method will overwrite existing keys.

Parameters¶

namestr: The name of the parameter.
valueany: The parameter itself.

metrics: dict¶

name: str¶

parameters: dict¶

to_dict() → dict[source]¶

Serialize the test to a dictionary.

Returns¶

dict: The test dictionary.

to_tabular() → dict[source]¶

Create a dictionary that can be fed into pandas.

Returns¶

dict

Represent the test, with the following keys:

Field	Description
`("test",)`	Test name
`("description",)`	Test description

Module contents¶

Import path.

class lazyscribe.Experiment(name: str, project: Path, dir: Path = NOTHING, fs: AbstractFileSystem = NOTHING, author: str = NOTHING, last_updated_by: str = NOTHING, metrics: dict = NOTHING, parameters: dict = NOTHING, created_at: datetime = NOTHING, last_updated: datetime = NOTHING, dependencies: dict = NOTHING, short_slug: str = NOTHING, slug: str = NOTHING, tests: list[Test | ReadOnlyTest] = NOTHING, artifacts: list[Artifact] = NOTHING, tags: list[str] = NOTHING, dirty: bool = NOTHING)[source]¶

Bases: object

Experiment data class.

This class is not meant to be initialized directly. It is meant to be used through the lazyscribe.project.Project class.

Parameters¶

namestr: The name of the experiment.
projectPath: The path to the project JSON associated with the project.
authorstr, optional (default getpass.getuser()): The author of the experiment.
metricsdict, optional (default {}): A dictionary of metric values. Each metric value can be an individual value or a list.
parametersdict, optional (default {}): A dictionary of experiment parameters. The key must be a string but the value can be anything.
created_atdatetime, optional (default utcnow()): When the experiment was created.
last_updateddatetime, optional (default utcnow()): When the experiment was last updated.
dependenciesdict, optional (default None): A dictionary of upstream project experiments. The key is the short slug for the upstream experiment and the value is an Experiment instance.

artifacts: list[Artifact]¶

author: str¶

created_at: datetime¶

dependencies: dict¶

dir: Path¶

dirty: bool¶

fs: AbstractFileSystem¶

last_updated: datetime¶

last_updated_by: str¶

load_artifact(name: str, validate: bool = True, **kwargs) → Any[source]¶

Load a single artifact.

Parameters¶

namestr: The name of the artifact to load.
validatebool, optional (default True): Whether or not to validate the runtime environment against the artifact metadata.
**kwargsdict: Keyword arguments for the handler read function.

Returns¶

object: The artifact.

Raises¶

ArtifactLoadError: If validate and runtime environment does not match artifact metadata. Or if there is no artifact found with the name provided.

log_artifact(name: str, value: Any, handler: str, fname: str | None = None, overwrite: bool = False, **kwargs)[source]¶

Log an artifact to the experiment.

This method associates an artifact with the experiment, but the artifact will not be written until lazyscribe.Project.save() is called.

Parameters¶

namestr: The name of the artifact.
valueAny: The object to persist to the filesystem.
handlerstr: The name of the handler to use for the object.
fnamestr, optional (default None): The filename for the artifact. If not provided, it will be derived from the name of the artifact and the builtin suffix for each handler.
overwritebool, optional (default False): Whether or not to overwrite an existing artifact with the same name. If set to True, the previous artifact will be removed and overwritten with the current artifact.
**kwargsdict: Keyword arguments for the write function of the handler.

Raises¶

ArtifactLogError: Raised if an artifact is supplied with the same name as an existing artifact and overwrite is set to False.

log_metric(name: str, value: float | int)[source]¶

Log a metric to the experiment.

This method will overwrite existing keys.

Parameters¶

namestr: Name of the metric.
valueint or float: Value of the metric.

log_parameter(name: str, value: Any)[source]¶

Log a parameter to the experiment.

This method will overwrite existing keys.

Parameters¶

namestr: The name of the parameter.
valueAny: The parameter itself.

log_test(name: str, description: str | None = None) → Iterator[Test][source]¶

Add a test to the experiment using a context handler.

A test is a specific location for non-global metrics.

Parameters¶

namestr: Name of the test.
descriptionstr, optional (default None): An optional description for the test.

Yields¶

Test: The lazyscribe.test.Test dataclass.

metrics: dict¶

name: str¶

parameters: dict¶

property path: Path¶

Path to an experiment folder.

This folder can be used to store any plots or artifacts that you want to associate with the experiment.

Returns¶

Path: The path for the experiment.

project: Path¶

promote_artifact(repository: Repository, name: str)[source]¶

Associate an artifact with a lazyscribe.repository.Repository.

The purpose of this method is to move an artifact from an ephemeral experiment to the versioned repository.

Parameters¶

repositoryRepository: The lazyscribe.repository.Repository to promote the artifact to.
namestr: The artifact to promote.

Raises¶

ArtifactLogError

Raised if the artifact to be promoted is not newer than the latest version available in the repository.

Raised if

the artifact name exists on the filesystem, and
the filesystem protocol does not match between the repository and the experiment.

ArtifactLoadError

Raised if there is no artifact with the name name in the experiment.

short_slug: str¶

slug: str¶

tag(*args, overwrite: bool = False)[source]¶

Add one or more tags to the experiment.

Important

If this function is called with no supplied values for *args _and_ overwrite=True, the result will be that the experiment has no associated tags.

Parameters¶

*args: The tags.
overwritebool, optional (default False): Whether to add or overwrite the new tags.

tags: list[str]¶

tests: list[Test | ReadOnlyTest]¶

to_dict() → dict[source]¶

Serialize the experiment to a dictionary.

Returns¶

dict: The experiment dictionary.

to_tabular() → dict[source]¶

Create a dictionary that can be fed into pandas.

Returns¶

dict

Represent the experiment, with the following keys:

Field	Description
`("name",)`	Name of the experiment
`("short_slug",)`	Short slug for the experiment
`("slug",)`	Full slug for the experiment
`("author",)`	Experiment author
`("last_updated_by",)`	Last author
`("created_at",)`	Created timestamp
`("last_updated",)`	Last update timestammp

class lazyscribe.Project(fpath: str | Path = 'project.json', mode: Literal['r', 'a', 'w', 'w+'] = 'w', author: str | None = None, **storage_options)[source]¶

Bases: object

Project class.

Parameters¶

fpathstr, optional (default “project.json”)

The location of the project file. If no project file exists, this will be the location of the output JSON file when save is called.

mode{“r”, “a”, “w”, “w+”}, optional (default “w”)

The mode for opening the project.

r: All existing experiments will be loaded as lazyscribe.experiment.ReadOnlyExperiment and no new experiments can be logged.
a: All existing experiments will be loaded as lazyscribe.experiment.ReadOnlyExperiment and new experiments can be added.
w: No existing experiments will be loaded.
w+: All experiments will be loaded in editable mode as lazyscribe.experiment.Experiment.

authorstr, optional (default None)

The project author. This author will be used for any new experiments or modifications to existing experiments. If not supplied, getpass.getuser() will be used.

storage_optionsdict, optional (default None)

Storage options to pass to the filesystem initialization. Will be passed to fsspec.filesystem.

Attributes¶

experimentslist: The list of experiments in the project.

append(other: Experiment)[source]¶

Append an experiment to the project.

For details on the merging process, see here.

Parameters¶

otherExperiment: The experiment to add.

Raises¶

ReadOnlyError: Raised when trying to log a new experiment when the project is in read-only mode.

filter(func: Callable) → Iterator[Experiment | ReadOnlyExperiment][source]¶

Filter the experiments in the project.

Parameters¶

funcCallable: A callable that takes in a lazyscribe.Experiment object and returns a boolean indicating whether or not it passes the filter.

Yields¶

Experiment: An experiment.

load()[source]¶

Load existing experiments.

If the project is in read-only or append mode, existing experiments will be loaded in read-only mode. If opened in editable mode, existing experiments will be loaded in editable mode.

log(name: str) → Iterator[Experiment][source]¶

Log an experiment to the project.

Parameters¶

namestr: The name of the experiment.

Yields¶

Experiment: A new Experiment data class.

Raises¶

ReadOnlyError: Raised when trying to log a new experiment when the project is in read-only mode.

merge(other: Project) → Project[source]¶

Merge two projects.

The new project will inherit the current project fpath, author, and mode.

For details on the merging process, see here.

Returns¶

Project: A new project.

save()[source]¶

Save the project data.

This includes saving any artifact data.

Raises¶

SaveError: Raised when writing to the filesystem fails.

to_tabular() → tuple[list[dict], list[dict]][source]¶

Create a dictionary that can be fed into pandas.

This method depends on the user consistently logging the same metrics and parameters to each experiment in the project.

Returns¶

list[dict]

The experiments list. Each entry is a result of :py:method:`lazyscribe.Experiment.to_tabular` per project’s experiment.

list[dict]

The tests list. Each entry is a result of :py:method:`lazyscribe.Test.to_tabular` per test per project’s experiment, with the following additional keys:

Field	Description
`("experiment_name",)`	Name of the test’s experiment
`("experiment_short_slug",)`	Short slug for the test’s experiment
`("experiment_slug",)`	Full slug for the test’s experiment
`("test",)`	Test name
`("description",)`	Test description

class lazyscribe.Repository(fpath: str | Path = 'repository.json', mode: Literal['r', 'a', 'w', 'w+'] = 'w', **storage_options)[source]¶

Bases: object

Repository class for holding versioned artifacts.

Parameters¶

fpathstr | Path, optional (default “repository.json”)

The location of the repository file. If no repository file exists, this will be the location of the output JSON file when save is called.

mode{“r”, “a”, “w”, “w+”}, optional (default “w”)

The mode for opening the repository.

r: No new artifacts can be logged.
a: The same as w+ (deprecated).
w: No existing artifacts will be loaded.
w+: All artifacts will be loaded.

Attributes¶

artifactslist[Artifact]: The list of artifacts in the repository.

get_artifact_metadata(name: str, version: datetime | str | int | None = None, match: Literal['asof', 'exact'] = 'exact') → dict[str, Any][source]¶

Retrieve the metadata for an artifact.

Parameters¶

namestr: The name of the artifact to load.
versiondatetime.datetime | str | int, optional (default None): The version of the artifact to load. Can be provided as a datetime corresponding to the created_at field, a string corresponding to the created_at field in the format "%Y-%m-%dT%H:%M:%S" (e.g. "2025-01-25T12:36:22"), or an integer version. If set to None or not provided, defaults to the most recent version.
match“asof” | “exact”, optional (default “exact”): Matching logic. Only relevant for str and datetime.datetime values for version. exact will provide an artifact with the exact created_at value provided. asof will provide the most recent version as of the version value.

Returns¶

dict: The artifact metadata.

load()[source]¶: Load existing artifacts.

load_artifact(name: str, validate: bool = True, version: datetime | str | int | None = None, match: Literal['asof', 'exact'] = 'exact', **kwargs) → Any[source]¶

Load a single artifact.

Parameters¶

namestr: The name of the artifact to load.
validatebool, optional (default True): Whether or not to validate the runtime environment against the artifact metadata.
versiondatetime.datetime | str | int, optional (default None): The version of the artifact to load. Can be provided as a datetime corresponding to the created_at field, a string corresponding to the created_at field in the format "%Y-%m-%dT%H:%M:%S" (e.g. "2025-01-25T12:36:22"), or an integer version. If set to None or not provided, defaults to the most recent version.
match“asof” | “exact”, optional (default “exact”): Matching logic. Only relevant for str and datetime.datetime values for version. exact will provide an artifact with the exact created_at value provided. asof will provide the most recent version as of the version value.
**kwargsdict: Keyword arguments for the handler read function.

Returns¶

Any: The artifact object.

log_artifact(name: str, value: Any, handler: str, fname: str | None = None, **kwargs)[source]¶

Log an artifact to the repository.

This method associates an artifact with the repository, but the artifact will not be written until lazyscribe.Repository.save() is called.

Parameters¶

namestr: The name of the artifact.
valueAny: The object to persist to the filesystem.
handlerstr: The name of the handler to use for the object.
fnamestr, optional (default None): The filename for the artifact. If set to None or not provided, it will be derived from the name of the artifact and the builtin suffix for each handler.
**kwargsdict: Keyword arguments for the write function of the handler.

Raises¶

ReadOnlyError: If repository is in read-only mode.

save()[source]¶

Save the repository data.

This includes saving any artifact data.

Raises¶

SaveError: Raised when writing to the filesystem fails.

class lazyscribe.Test(name: str, description: str | None = NOTHING, metrics: dict = NOTHING, parameters: dict = NOTHING)[source]¶

Bases: object

Sub-population tests.

Parameters¶

namestr: The name of the test.
descriptionstr, optional (default None): A description of the test.
metricsdict, optional (default {}): A dictionary of metric values. Each metric value can be an individual value or a list.
parametersdict, optional (default {}): A dictionary of test parameters. The key must be a string but the value can be anything.

description: str | None¶

log_metric(name: str, value: float | int)[source]¶

Log a metric to the test.

This method will overwrite existing keys.

Parameters¶

namestr: Name of the metric.
valueint or float: Value of the metric.

log_parameter(name: str, value: Any)[source]¶

Log a parameter to the test.

This method will overwrite existing keys.

Parameters¶

namestr: The name of the parameter.
valueany: The parameter itself.

metrics: dict¶

name: str¶

parameters: dict¶

to_dict() → dict[source]¶

Serialize the test to a dictionary.

Returns¶

dict: The test dictionary.

to_tabular() → dict[source]¶

Create a dictionary that can be fed into pandas.

Returns¶

dict

Represent the test, with the following keys:

Field	Description
`("test",)`	Test name
`("description",)`	Test description