From 0b36208fd69f3e69618600b0a8b23d1a7aa66ca8 Mon Sep 17 00:00:00 2001 From: Derek <103802618+leeederek@users.noreply.github.com> Date: Tue, 17 Oct 2023 18:49:08 -0400 Subject: [PATCH] docs: update read_file docs & clarify package restrictions (#1540) ## Description: This pull request clarifies 2 things in the docs: - the returned type from `read_file` function in the Starlark reference - clarifies that resources being used in a Starlark script must themselves be a part of a Kurtosis package (i.e. a starlark script can only read or upload or import resources/starlark scripts/files that are part of other packages) ## Is this change user facing? YES ## References (if applicable): Fixes #1483 --- docs/docs/concepts-reference/locators.md | 12 ++++++------ docs/docs/starlark-reference/plan.md | 2 +- docs/docs/starlark-reference/read-file.md | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/concepts-reference/locators.md b/docs/docs/concepts-reference/locators.md index f7aa3f0ad2..01705f2534 100644 --- a/docs/docs/concepts-reference/locators.md +++ b/docs/docs/concepts-reference/locators.md @@ -36,9 +36,8 @@ github.com/kurtosis-tech/kurtosis/starlark/test.star Only locators pointing to public GitHub repositories are currently allowed. ::: -### Package Restriction -Any Starlark script that wishes to use external resources must be -a part of a [Kurtosis package][packages]. +### Important Package Restriction +If your Starlark script relies on local resources, such as files or packages available on your filesystem, then those resources *must* be part of a [Kurtosis package][packages]. For example, suppose we had a [Kurtosis package][packages] like so: @@ -60,16 +59,17 @@ with a `kurtosis.yml` file like so: name: github.com/package-author/package-repo/my-package ``` -The `main.star` file would import the `random-script.star` from the `helpers` subdirectory of `my-package` like so: +In your `main.star` file, you would be able to import the `random-script.star` from the `helpers` subdirectory of `my-package` like so: ```python +# Valid helpers = import_module("github.com/package-author/package-repo/my-package/helpers/random-script.star") ``` -The import statement below will not succeed, because `main.star` cannot import from non-packages. -(see [how import works][how-do-kurtosis-imports-work-explanation] for more information) +However, if you try to import `package-repo/not-a-package/random-script.star`, then it will not work because `package-repo/not-a-package/random-script.star` is not part of a package. In essence, the import statement below will not succeed, because `main.star` cannot import from non-packages (see [how import works][how-do-kurtosis-imports-work-explanation] for more information): ```python +# Invalid helpers = import_module("github.com/package-author/package-repo/not-a-package/random-script.star") ``` diff --git a/docs/docs/starlark-reference/plan.md b/docs/docs/starlark-reference/plan.md index 514c9b253b..cf3deae6e8 100644 --- a/docs/docs/starlark-reference/plan.md +++ b/docs/docs/starlark-reference/plan.md @@ -602,7 +602,7 @@ The return value is a [future reference][future-references-reference] to the nam upload_files ------------ -`upload_files` instruction packages the files specified by the [locator][locators-reference] into a [files artifact][files-artifacts-reference] that gets stored inside the enclave. This is particularly useful when a static file needs to be loaded to a service container. +The `upload_files` instruction packages the files specified by the [locator][locators-reference] into a [files artifact][files-artifacts-reference] that gets stored inside the enclave. This is particularly useful when a static file needs to be loaded to a service container. ```python artifact_name = plan.upload_files( diff --git a/docs/docs/starlark-reference/read-file.md b/docs/docs/starlark-reference/read-file.md index fd880895fd..9999439c09 100644 --- a/docs/docs/starlark-reference/read-file.md +++ b/docs/docs/starlark-reference/read-file.md @@ -3,7 +3,7 @@ title: read_file sidebar_label: read_file --- -The `read_file` function reads the contents of a file specified by the given [locator][locators-reference], and requires that the Starlark script is part of a [package][packages-reference]. `read_file` executes [at interpretation time][multi-phase-runs-reference] so the file contents won't be displayed in the preview. +The `read_file` function reads the contents of a file specified by the given [locator][locators-reference] and executes [at interpretation time][multi-phase-runs-reference]. This instruction returns the content of the file in a string type. Please note that the files being read from must themselves be part of a Kurtosis package, as explained [here](../concepts-reference/locators.md#important-package-restriction). ```python read_file(