Skip to content

Public API

Tutorial SDK public API.

AuthorSpec

Bases: BaseModel

Tutorial author metadata.

Source code in src/tutorial_sdk/spec.py 
14
15
16
17
18
19
20
class AuthorSpec(BaseModel):
    """Tutorial author metadata."""

    model_config = ConfigDict(extra="forbid")

    name: str
    email: str | None = None

BuildSpec

Bases: BaseModel

Build artifact and container image configuration.

Source code in src/tutorial_sdk/spec.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
class BuildSpec(BaseModel):
    """Build artifact and container image configuration."""

    model_config = ConfigDict(extra="forbid")

    dockerfile: str = "Dockerfile"
    image: str | None = None
    base_image: str = f"python:{_PYTHON_VERSION_STR}-slim"
    copy_repo: bool = True
    preexecute_notebooks: bool = False
    export_devcontainer: bool = False
    export_manifest: bool = True
    cache: bool = True
    custom_sections: DockerfileSections = Field(
        default_factory=DockerfileSections
    )

ContentSpec

Bases: BaseModel

Tutorial content assets copied into the image.

Source code in src/tutorial_sdk/spec.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class ContentSpec(BaseModel):
    """Tutorial content assets copied into the image."""

    model_config = ConfigDict(extra="forbid")

    notebooks: list[str] = Field(default_factory=list)
    scripts: list[str] = Field(default_factory=list)
    data: list[str] = Field(default_factory=list)
    docs: list[str] = Field(default_factory=list)
    exercises: list[str] = Field(default_factory=list)
    solutions: list[str] = Field(default_factory=list)

    def all_paths(self) -> list[str]:
        """Return every declared content path in stable order."""

        return [
            *self.notebooks,
            *self.scripts,
            *self.data,
            *self.docs,
            *self.exercises,
            *self.solutions,
        ]

all_paths 

all_paths() -> list[str]

Return every declared content path in stable order.

Source code in src/tutorial_sdk/spec.py 
58
59
60
61
62
63
64
65
66
67
68
def all_paths(self) -> list[str]:
    """Return every declared content path in stable order."""

    return [
        *self.notebooks,
        *self.scripts,
        *self.data,
        *self.docs,
        *self.exercises,
        *self.solutions,
    ]

DependencySpec

Bases: BaseModel

Package dependencies declared by package manager.

Source code in src/tutorial_sdk/spec.py 
35
36
37
38
39
40
41
42
43
class DependencySpec(BaseModel):
    """Package dependencies declared by package manager."""

    model_config = ConfigDict(extra="forbid")

    apt: list[str] = Field(default_factory=list)
    pip: list[str] = Field(default_factory=list)
    conda: list[str] = Field(default_factory=list)
    local: list[str] = Field(default_factory=list)

DockerfileSections

Bases: BaseModel

Optional user-managed Dockerfile snippets.

Source code in src/tutorial_sdk/spec.py 
71
72
73
74
75
76
77
78
class DockerfileSections(BaseModel):
    """Optional user-managed Dockerfile snippets."""

    model_config = ConfigDict(extra="forbid")

    before_dependencies: str | None = None
    after_dependencies: str | None = None
    before_entrypoint: str | None = None

EntrypointSpec

Bases: BaseModel

Default runtime entrypoint.

Source code in src/tutorial_sdk/spec.py 
110
111
112
113
114
115
116
117
class EntrypointSpec(BaseModel):
    """Default runtime entrypoint."""

    model_config = ConfigDict(extra="forbid")

    kind: Literal["jupyterlab", "shell", "command"] = "jupyterlab"
    default_notebook: str | None = None
    command: list[str] | None = None

RuntimeSpec

Bases: BaseModel

Runtime configuration for a tutorial environment.

Source code in src/tutorial_sdk/spec.py 
23
24
25
26
27
28
29
30
31
32
class RuntimeSpec(BaseModel):
    """Runtime configuration for a tutorial environment."""

    model_config = ConfigDict(extra="forbid")

    language: str = "python"
    python: str = _PYTHON_VERSION_STR
    kernel: str = "python3"
    jupyterlab: bool = True
    expose_port: int = 8888

TutorialProject

High-level API for tutorial projects.

Source code in src/tutorial_sdk/project.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 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
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
class TutorialProject:
    """High-level API for tutorial projects."""

    def __init__(
        self,
        spec: TutorialSpec,
        root: str | Path = ".",
        config_path: str | Path = DEFAULT_CONFIG,
    ) -> None:
        """Create a tutorial project object.

        Args:
            spec: Parsed tutorial specification.
            root: Project root directory.
            config_path: Path to the tutorial
                YAML configuration file.
        """

        self.spec = spec
        self.root = Path(root)
        self.config_path = Path(config_path)

    @classmethod
    def load(cls, path: str | Path) -> "TutorialProject":
        """Load a tutorial project from a YAML specification.

        Args:
            path: Path to a tutorial YAML file.

        Returns:
            A ``TutorialProject`` rooted in the config
            file's parent directory.
        """

        config_path = Path(path)
        spec = TutorialSpec.load(config_path)
        return cls(
            spec,
            config_path.parent,
            config_path,
        )

    @classmethod
    def init(cls, path: str | Path = ".") -> "TutorialProject":
        """Create a minimal tutorial project skeleton.

        Args:
            path: Target directory for the new project.

        Returns:
            A ``TutorialProject`` with a ``minimal``
            template applied.
        """

        from .scaffold import ProjectScaffolder

        return ProjectScaffolder().scaffold(
            "minimal",
            Path(path),
        )

    @classmethod
    def init_from(
        cls,
        source: str | Path,
        target: str | Path | None = None,
    ) -> "TutorialProject":
        """Import an existing directory as a tutorial project.

        Args:
            source: Path to an existing directory containing
                notebooks and associated files.
            target: Optional target directory for the new
                tutorial project.

        Returns:
            A fully initialised ``TutorialProject``.
        """

        from .scaffold import ProjectImporter

        return ProjectImporter().scan(
            source,
            target,
        )

    @classmethod
    def init_from_url(
        cls,
        url: str,
        target: str | Path | None = None,
        remove_clone: bool = False,
    ) -> "TutorialProject":
        """Import a remote repository as a tutorial project.

        Args:
            url: Git-compatible clone URL.
            target: Optional target directory.
            remove_clone: If ``True``, delete the cloned
                repository after importing.

        Returns:
            A ``TutorialProject``.
        """

        from .scaffold import ProjectImporter

        return ProjectImporter().scan_url(
            url,
            target,
            remove_clone=remove_clone,
        )

    @classmethod
    def init_from_github(
        cls,
        org_repo: str,
        target: str | Path | None = None,
        remove_clone: bool = False,
    ) -> "TutorialProject":
        """Import a GitHub repository as a tutorial project.

        Args:
            org_repo: ``ORG/REPO`` shorthand.
            target: Optional target directory.
            remove_clone: If ``True``, delete the cloned
                repository after importing.

        Returns:
            A ``TutorialProject``.
        """

        from .scaffold import ProjectImporter

        return ProjectImporter().scan_github(
            org_repo,
            target,
            remove_clone=remove_clone,
        )

    def resolve(self) -> ResolvedTutorialProject:
        """Resolve the project content graph.

        Returns:
            A ``ResolvedTutorialProject`` with content
            and missing paths populated.
        """

        return TutorialResolver(
            self.spec,
            self.root,
        ).resolve(self.config_path)

    def validate(
        self,
        strict: bool = False,
        container: bool = False,
        image: str | None = None,
    ) -> ValidationReport:
        """Run configured validation checks.

        Args:
            strict: If ``True``, promote warnings to
                failures.
            container: If ``True``, include container
                runtime validation.
            image: Override image tag for container
                validation.

        Returns:
            Combined ``ValidationReport``.
        """

        reports = [
            AssetValidator(self.spec, self.root).validate(),
            NotebookValidator(self.spec, self.root).validate(),
            DependencyValidator(self.spec).validate(),
        ]
        if container:
            reports.append(
                ContainerValidator(
                    self.spec,
                    self.root,
                ).validate(image=image)
            )
        report = ValidationReport.combine(reports)
        if strict and report.warnings:
            report = report.model_copy(update={"passed": False})
        return report

    def inspect(self) -> str:
        """Return resolved tutorial metadata as JSON.

        Returns:
            Pretty-printed JSON string.
        """

        resolved = self.resolve()
        payload = self.spec.to_manifest_dict(image=resolved.image)
        payload["missing_paths"] = [
            str(path.relative_to(self.root)) for path in resolved.missing_paths
        ]
        return json.dumps(payload, indent=2) + "\n"

    def build(
        self,
        image: str | None = None,
        no_cache: bool | None = None,
        platform: str | None = None,
    ) -> BuildResult:
        """Generate a Dockerfile and build the container image.

        Args:
            image: Optional image tag override.
            no_cache: If ``True``, disable Docker
                layer caching.
            platform: Target platform (e.g.
                ``linux/amd64``).

        Returns:
            A ``BuildResult`` with the image tag and
            Dockerfile path.
        """

        return LocalBuilder(
            self.spec,
            self.root,
        ).build(
            image=image,
            no_cache=no_cache,
            platform=platform,
        )

    def run(
        self, image: str | None = None, port: int = 8888, shell: bool = False
    ) -> RunResult:
        """Run the tutorial container locally.

        Args:
            image: Optional image tag override.
            port: Host port to bind.
            shell: If ``True``, override entrypoint
                with an interactive shell.

        Returns:
            A ``RunResult`` with the container exit
            code.
        """

        return RuntimeLauncher(
            self.spec,
            self.root,
        ).run(
            image=image,
            port=port,
            shell=shell,
        )

__init__ 

__init__(spec: TutorialSpec, root: str | Path = '.', config_path: str | Path = DEFAULT_CONFIG) -> None

Create a tutorial project object.

Parameters:

Name Type Description Default
spec TutorialSpec

Parsed tutorial specification.

 required
root str | Path

Project root directory.

 '.'
config_path str | Path

Path to the tutorial YAML configuration file.

 DEFAULT_CONFIG
Source code in src/tutorial_sdk/project.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def __init__(
    self,
    spec: TutorialSpec,
    root: str | Path = ".",
    config_path: str | Path = DEFAULT_CONFIG,
) -> None:
    """Create a tutorial project object.

    Args:
        spec: Parsed tutorial specification.
        root: Project root directory.
        config_path: Path to the tutorial
            YAML configuration file.
    """

    self.spec = spec
    self.root = Path(root)
    self.config_path = Path(config_path)

build 

build(image: str | None = None, no_cache: bool | None = None, platform: str | None = None) -> BuildResult

Generate a Dockerfile and build the container image.

Parameters:

Name Type Description Default
image str | None

Optional image tag override.

 None
no_cache bool | None

If True, disable Docker layer caching.

 None
platform str | None

Target platform (e.g. linux/amd64).

 None

Returns:

Type Description
BuildResult

A BuildResult with the image tag and Dockerfile path.
Source code in src/tutorial_sdk/project.py 
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
def build(
    self,
    image: str | None = None,
    no_cache: bool | None = None,
    platform: str | None = None,
) -> BuildResult:
    """Generate a Dockerfile and build the container image.

    Args:
        image: Optional image tag override.
        no_cache: If ``True``, disable Docker
            layer caching.
        platform: Target platform (e.g.
            ``linux/amd64``).

    Returns:
        A ``BuildResult`` with the image tag and
        Dockerfile path.
    """

    return LocalBuilder(
        self.spec,
        self.root,
    ).build(
        image=image,
        no_cache=no_cache,
        platform=platform,
    )

init classmethod 

init(path: str | Path = '.') -> TutorialProject

Create a minimal tutorial project skeleton.

Parameters:

Name Type Description Default
path str | Path

Target directory for the new project.

 '.'

Returns:

Type Description
TutorialProject

A TutorialProject with a minimal template applied.
Source code in src/tutorial_sdk/project.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@classmethod
def init(cls, path: str | Path = ".") -> "TutorialProject":
    """Create a minimal tutorial project skeleton.

    Args:
        path: Target directory for the new project.

    Returns:
        A ``TutorialProject`` with a ``minimal``
        template applied.
    """

    from .scaffold import ProjectScaffolder

    return ProjectScaffolder().scaffold(
        "minimal",
        Path(path),
    )

init_from classmethod 

init_from(source: str | Path, target: str | Path | None = None) -> TutorialProject

Import an existing directory as a tutorial project.

Parameters:

Name Type Description Default
source str | Path

Path to an existing directory containing notebooks and associated files.

 required
target str | Path | None

Optional target directory for the new tutorial project.

 None

Returns:

Type Description
TutorialProject

A fully initialised TutorialProject.
Source code in src/tutorial_sdk/project.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
@classmethod
def init_from(
    cls,
    source: str | Path,
    target: str | Path | None = None,
) -> "TutorialProject":
    """Import an existing directory as a tutorial project.

    Args:
        source: Path to an existing directory containing
            notebooks and associated files.
        target: Optional target directory for the new
            tutorial project.

    Returns:
        A fully initialised ``TutorialProject``.
    """

    from .scaffold import ProjectImporter

    return ProjectImporter().scan(
        source,
        target,
    )

init_from_github classmethod 

init_from_github(org_repo: str, target: str | Path | None = None, remove_clone: bool = False) -> TutorialProject

Import a GitHub repository as a tutorial project.

Parameters:

Name Type Description Default
org_repo str

ORG/REPO shorthand.

 required
target str | Path | None

Optional target directory.

 None
remove_clone bool

If True, delete the cloned repository after importing.

 False

Returns:

Type Description
TutorialProject

A TutorialProject.
Source code in src/tutorial_sdk/project.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@classmethod
def init_from_github(
    cls,
    org_repo: str,
    target: str | Path | None = None,
    remove_clone: bool = False,
) -> "TutorialProject":
    """Import a GitHub repository as a tutorial project.

    Args:
        org_repo: ``ORG/REPO`` shorthand.
        target: Optional target directory.
        remove_clone: If ``True``, delete the cloned
            repository after importing.

    Returns:
        A ``TutorialProject``.
    """

    from .scaffold import ProjectImporter

    return ProjectImporter().scan_github(
        org_repo,
        target,
        remove_clone=remove_clone,
    )

init_from_url classmethod 

init_from_url(url: str, target: str | Path | None = None, remove_clone: bool = False) -> TutorialProject

Import a remote repository as a tutorial project.

Parameters:

Name Type Description Default
url str

Git-compatible clone URL.

 required
target str | Path | None

Optional target directory.

 None
remove_clone bool

If True, delete the cloned repository after importing.

 False

Returns:

Type Description
TutorialProject

A TutorialProject.
Source code in src/tutorial_sdk/project.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
@classmethod
def init_from_url(
    cls,
    url: str,
    target: str | Path | None = None,
    remove_clone: bool = False,
) -> "TutorialProject":
    """Import a remote repository as a tutorial project.

    Args:
        url: Git-compatible clone URL.
        target: Optional target directory.
        remove_clone: If ``True``, delete the cloned
            repository after importing.

    Returns:
        A ``TutorialProject``.
    """

    from .scaffold import ProjectImporter

    return ProjectImporter().scan_url(
        url,
        target,
        remove_clone=remove_clone,
    )

inspect 

inspect() -> str

Return resolved tutorial metadata as JSON.

Returns:

Type Description
str

Pretty-printed JSON string.
Source code in src/tutorial_sdk/project.py 
210
211
212
213
214
215
216
217
218
219
220
221
222
def inspect(self) -> str:
    """Return resolved tutorial metadata as JSON.

    Returns:
        Pretty-printed JSON string.
    """

    resolved = self.resolve()
    payload = self.spec.to_manifest_dict(image=resolved.image)
    payload["missing_paths"] = [
        str(path.relative_to(self.root)) for path in resolved.missing_paths
    ]
    return json.dumps(payload, indent=2) + "\n"

load classmethod 

load(path: str | Path) -> TutorialProject

Load a tutorial project from a YAML specification.

Parameters:

Name Type Description Default
path str | Path

Path to a tutorial YAML file.

 required

Returns:

Type Description
TutorialProject

A TutorialProject rooted in the config file's parent directory.
Source code in src/tutorial_sdk/project.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
@classmethod
def load(cls, path: str | Path) -> "TutorialProject":
    """Load a tutorial project from a YAML specification.

    Args:
        path: Path to a tutorial YAML file.

    Returns:
        A ``TutorialProject`` rooted in the config
        file's parent directory.
    """

    config_path = Path(path)
    spec = TutorialSpec.load(config_path)
    return cls(
        spec,
        config_path.parent,
        config_path,
    )

resolve 

resolve() -> ResolvedTutorialProject

Resolve the project content graph.

Returns:

Type Description
ResolvedTutorialProject

A ResolvedTutorialProject with content and missing paths populated.
Source code in src/tutorial_sdk/project.py 
160
161
162
163
164
165
166
167
168
169
170
171
def resolve(self) -> ResolvedTutorialProject:
    """Resolve the project content graph.

    Returns:
        A ``ResolvedTutorialProject`` with content
        and missing paths populated.
    """

    return TutorialResolver(
        self.spec,
        self.root,
    ).resolve(self.config_path)

run 

run(image: str | None = None, port: int = 8888, shell: bool = False) -> RunResult

Run the tutorial container locally.

Parameters:

Name Type Description Default
image str | None

Optional image tag override.

 None
port int

Host port to bind.

 8888
shell bool

If True, override entrypoint with an interactive shell.

 False

Returns:

Type Description
RunResult

A RunResult with the container exit code.
Source code in src/tutorial_sdk/project.py 
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def run(
    self, image: str | None = None, port: int = 8888, shell: bool = False
) -> RunResult:
    """Run the tutorial container locally.

    Args:
        image: Optional image tag override.
        port: Host port to bind.
        shell: If ``True``, override entrypoint
            with an interactive shell.

    Returns:
        A ``RunResult`` with the container exit
        code.
    """

    return RuntimeLauncher(
        self.spec,
        self.root,
    ).run(
        image=image,
        port=port,
        shell=shell,
    )

validate 

validate(strict: bool = False, container: bool = False, image: str | None = None) -> ValidationReport

Run configured validation checks.

Parameters:

Name Type Description Default
strict bool

If True, promote warnings to failures.

 False
container bool

If True, include container runtime validation.

 False
image str | None

Override image tag for container validation.

 None

Returns:

Type Description
ValidationReport

Combined ValidationReport.
Source code in src/tutorial_sdk/project.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
def validate(
    self,
    strict: bool = False,
    container: bool = False,
    image: str | None = None,
) -> ValidationReport:
    """Run configured validation checks.

    Args:
        strict: If ``True``, promote warnings to
            failures.
        container: If ``True``, include container
            runtime validation.
        image: Override image tag for container
            validation.

    Returns:
        Combined ``ValidationReport``.
    """

    reports = [
        AssetValidator(self.spec, self.root).validate(),
        NotebookValidator(self.spec, self.root).validate(),
        DependencyValidator(self.spec).validate(),
    ]
    if container:
        reports.append(
            ContainerValidator(
                self.spec,
                self.root,
            ).validate(image=image)
        )
    report = ValidationReport.combine(reports)
    if strict and report.warnings:
        report = report.model_copy(update={"passed": False})
    return report

TutorialSpec

Bases: BaseModel

Source-of-truth tutorial specification.

Source code in src/tutorial_sdk/spec.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
class TutorialSpec(BaseModel):
    """Source-of-truth tutorial specification."""

    model_config = ConfigDict(extra="forbid")

    name: str
    version: str = "0.1.0"
    title: str | None = None
    description: str = ""
    authors: list[AuthorSpec] = Field(default_factory=list)
    license: str | None = None
    runtime: RuntimeSpec = Field(default_factory=RuntimeSpec)
    dependencies: DependencySpec = Field(default_factory=DependencySpec)
    content: ContentSpec = Field(default_factory=ContentSpec)
    build: BuildSpec = Field(default_factory=BuildSpec)
    validation: ValidationSpec = Field(default_factory=ValidationSpec)
    entrypoint: EntrypointSpec = Field(default_factory=EntrypointSpec)

    @field_validator("name")
    @classmethod
    def validate_name(
        cls,
        value: str,
    ) -> str:
        """Validate the spec name used for files and image tags."""

        cleaned = value.strip()
        if not cleaned:
            raise ValueError("name must not be empty")
        return cleaned

    @property
    def display_title(self) -> str:
        """Return the title exposed in generated metadata."""

        return self.title or self.name

    @classmethod
    def load(cls, path: str | Path) -> "TutorialSpec":
        """Load a tutorial specification from YAML.

        Args:
            path: Path to a tutorial YAML file.

        Returns:
            Parsed tutorial specification.

        Raises:
            ConfigError: If the file cannot be read or validated.
        """

        spec_path = Path(path)
        try:
            raw = yaml.safe_load(spec_path.read_text()) or {}
        except OSError as exc:
            raise ConfigError(f"Unable to read {spec_path}: {exc}") from exc
        except yaml.YAMLError as exc:
            raise ConfigError(f"Unable to parse {spec_path}: {exc}") from exc

        try:
            return cls.model_validate(raw)
        except ValueError as exc:
            raise ConfigError(str(exc)) from exc

    def write(self, path: str | Path) -> None:
        """Write this specification as YAML.

        Args:
            path: Destination file path.
        """

        spec_path = Path(path)
        data = self.model_dump(mode="json", exclude_none=True)
        spec_path.write_text(yaml.safe_dump(data, sort_keys=False))

    def to_manifest_dict(
        self,
        image: str | None = None,
    ) -> dict[str, Any]:
        """Return the reproducibility manifest payload.

        Args:
            image: Override image tag.  Falls back to
                the build spec's configured image.

        Returns:
            Dictionary suitable for JSON serialisation.
        """

        return {
            "name": self.name,
            "version": self.version,
            "title": self.display_title,
            "description": self.description,
            "base_image": self.build.base_image,
            "image": image or self.build.image,
            "runtime": self.runtime.model_dump(mode="json"),
            "content": self.content.model_dump(mode="json"),
            "dependencies": self.dependencies.model_dump(mode="json"),
            "entrypoint": self.entrypoint.model_dump(mode="json"),
        }

display_title property 

display_title: str

Return the title exposed in generated metadata.

load classmethod 

load(path: str | Path) -> TutorialSpec

Load a tutorial specification from YAML.

Parameters:

Name Type Description Default
path str | Path

Path to a tutorial YAML file.

 required

Returns:

Type Description
TutorialSpec

Parsed tutorial specification.

Raises:

Type Description
ConfigError

If the file cannot be read or validated.
Source code in src/tutorial_sdk/spec.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
@classmethod
def load(cls, path: str | Path) -> "TutorialSpec":
    """Load a tutorial specification from YAML.

    Args:
        path: Path to a tutorial YAML file.

    Returns:
        Parsed tutorial specification.

    Raises:
        ConfigError: If the file cannot be read or validated.
    """

    spec_path = Path(path)
    try:
        raw = yaml.safe_load(spec_path.read_text()) or {}
    except OSError as exc:
        raise ConfigError(f"Unable to read {spec_path}: {exc}") from exc
    except yaml.YAMLError as exc:
        raise ConfigError(f"Unable to parse {spec_path}: {exc}") from exc

    try:
        return cls.model_validate(raw)
    except ValueError as exc:
        raise ConfigError(str(exc)) from exc

to_manifest_dict 

to_manifest_dict(image: str | None = None) -> dict[str, Any]

Return the reproducibility manifest payload.

Parameters:

Name Type Description Default
image str | None

Override image tag. Falls back to the build spec's configured image.

 None

Returns:

Type Description
dict[str, Any]

Dictionary suitable for JSON serialisation.
Source code in src/tutorial_sdk/spec.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def to_manifest_dict(
    self,
    image: str | None = None,
) -> dict[str, Any]:
    """Return the reproducibility manifest payload.

    Args:
        image: Override image tag.  Falls back to
            the build spec's configured image.

    Returns:
        Dictionary suitable for JSON serialisation.
    """

    return {
        "name": self.name,
        "version": self.version,
        "title": self.display_title,
        "description": self.description,
        "base_image": self.build.base_image,
        "image": image or self.build.image,
        "runtime": self.runtime.model_dump(mode="json"),
        "content": self.content.model_dump(mode="json"),
        "dependencies": self.dependencies.model_dump(mode="json"),
        "entrypoint": self.entrypoint.model_dump(mode="json"),
    }

validate_name classmethod 

validate_name(value: str) -> str

Validate the spec name used for files and image tags.

Source code in src/tutorial_sdk/spec.py 
138
139
140
141
142
143
144
145
146
147
148
149
@field_validator("name")
@classmethod
def validate_name(
    cls,
    value: str,
) -> str:
    """Validate the spec name used for files and image tags."""

    cleaned = value.strip()
    if not cleaned:
        raise ValueError("name must not be empty")
    return cleaned

write 

write(path: str | Path) -> None

Write this specification as YAML.

Parameters:

Name Type Description Default
path str | Path

Destination file path.

 required
Source code in src/tutorial_sdk/spec.py 
184
185
186
187
188
189
190
191
192
193
def write(self, path: str | Path) -> None:
    """Write this specification as YAML.

    Args:
        path: Destination file path.
    """

    spec_path = Path(path)
    data = self.model_dump(mode="json", exclude_none=True)
    spec_path.write_text(yaml.safe_dump(data, sort_keys=False))

ValidationCheck

Bases: BaseModel

A single validation check result.

Source code in src/tutorial_sdk/validator/report.py 
 9
10
11
12
13
14
15
16
class ValidationCheck(BaseModel):
    """A single validation check result."""

    model_config = ConfigDict(extra="forbid")

    name: str
    passed: bool
    message: str

ValidationReport

Bases: BaseModel

Machine-readable tutorial validation report.

Source code in src/tutorial_sdk/validator/report.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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
class ValidationReport(BaseModel):
    """Machine-readable tutorial validation report."""

    model_config = ConfigDict(extra="forbid")

    passed: bool
    checks: list[ValidationCheck] = Field(default_factory=list)
    errors: list[str] = Field(default_factory=list)
    warnings: list[str] = Field(default_factory=list)

    @classmethod
    def combine(
        cls,
        reports: list["ValidationReport"],
    ) -> "ValidationReport":
        """Combine several reports into one report.

        Args:
            reports: List of reports to merge.

        Returns:
            A single ``ValidationReport`` with all
            checks, errors, and warnings aggregated.
        """

        checks: list[ValidationCheck] = []
        errors: list[str] = []
        warnings: list[str] = []
        for report in reports:
            checks.extend(report.checks)
            errors.extend(report.errors)
            warnings.extend(report.warnings)
        return cls(
            passed=all(report.passed for report in reports),
            checks=checks,
            errors=errors,
            warnings=warnings,
        )

    def render_json(self) -> str:
        """Render report as stable JSON.

        Returns:
            Pretty-printed JSON string.
        """

        return json.dumps(self.model_dump(mode="json"), indent=2) + "\n"

    def write(
        self,
        path: str | Path,
    ) -> None:
        """Write report JSON to disk.

        Args:
            path: Destination file path.
        """

        Path(path).write_text(self.render_json())

combine classmethod 

combine(reports: list[ValidationReport]) -> ValidationReport

Combine several reports into one report.

Parameters:

Name Type Description Default
reports list[ValidationReport]

List of reports to merge.

 required

Returns:

Type Description
ValidationReport

A single ValidationReport with all checks, errors, and warnings aggregated.
Source code in src/tutorial_sdk/validator/report.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
@classmethod
def combine(
    cls,
    reports: list["ValidationReport"],
) -> "ValidationReport":
    """Combine several reports into one report.

    Args:
        reports: List of reports to merge.

    Returns:
        A single ``ValidationReport`` with all
        checks, errors, and warnings aggregated.
    """

    checks: list[ValidationCheck] = []
    errors: list[str] = []
    warnings: list[str] = []
    for report in reports:
        checks.extend(report.checks)
        errors.extend(report.errors)
        warnings.extend(report.warnings)
    return cls(
        passed=all(report.passed for report in reports),
        checks=checks,
        errors=errors,
        warnings=warnings,
    )

render_json 

render_json() -> str

Render report as stable JSON.

Returns:

Type Description
str

Pretty-printed JSON string.
Source code in src/tutorial_sdk/validator/report.py 
58
59
60
61
62
63
64
65
def render_json(self) -> str:
    """Render report as stable JSON.

    Returns:
        Pretty-printed JSON string.
    """

    return json.dumps(self.model_dump(mode="json"), indent=2) + "\n"

write 

write(path: str | Path) -> None

Write report JSON to disk.

Parameters:

Name Type Description Default
path str | Path

Destination file path.

 required
Source code in src/tutorial_sdk/validator/report.py 
67
68
69
70
71
72
73
74
75
76
77
def write(
    self,
    path: str | Path,
) -> None:
    """Write report JSON to disk.

    Args:
        path: Destination file path.
    """

    Path(path).write_text(self.render_json())

ValidationSpec

Bases: BaseModel

Validation checks enabled for a tutorial.

Source code in src/tutorial_sdk/spec.py 
 99
100
101
102
103
104
105
106
107
class ValidationSpec(BaseModel):
    """Validation checks enabled for a tutorial."""

    model_config = ConfigDict(extra="forbid")

    execute_notebooks: bool = False
    check_imports: bool = True
    check_links: bool = True
    require_clean_execution: bool = True