calkit-python 0.14.5__tar.gz → 0.16.0__tar.gz

{calkit_python-0.14.5 → calkit_python-0.16.0}/.github/workflows/docs.yml

@@ -27,5 +27,5 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material
+      - run: pip install mkdocs-material mkdocs-mermaid2-plugin
       - run: mkdocs gh-deploy --force

{calkit_python-0.14.5 → calkit_python-0.16.0}/.gitignore

@@ -3,3 +3,4 @@ dev.ipynb
 .DS_Store
 .vscode
 site
+.env

{calkit_python-0.14.5 → calkit_python-0.16.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.14.5
+Version: 0.16.0
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
-Project-URL: Repository, https://github.com/calkit/calkit
 Project-URL: Issues, https://github.com/calkit/calkit/issues
+Project-URL: Repository, https://github.com/calkit/calkit
 Author-email: Pete Bachant <petebachant@gmail.com>
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -23,6 +23,7 @@ Requires-Dist: pillow
 Requires-Dist: pydantic-settings
 Requires-Dist: pydantic[email]
 Requires-Dist: pyjwt
+Requires-Dist: python-dotenv>=1
 Requires-Dist: pywin32; platform_system == 'Windows'
 Requires-Dist: requests
 Requires-Dist: typer
@@ -35,6 +36,7 @@ Requires-Dist: pytest; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs; extra == 'docs'
 Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs-mermaid2-plugin; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -43,7 +45,7 @@ Description-Content-Type: text/markdown
   </a>
 </p>
 
-Calkit is a lightweight framework for reproducible research projects.
+Calkit is a framework and toolkit for reproducible research projects.
 It acts as a top-level layer to integrate and simplify the use of enabling
 technologies such as
 [Git](https://git-scm.com/),
@@ -54,22 +56,7 @@ Calkit also adds a domain-specific data model
 such that all aspects of the research process can be fully described in a
 single repository and therefore easily consumed by others.
 
-Our goal is to make reproducibility easier so it becomes more common.
-To do this, we try to make it easy for users to follow two simple rules:
-
-1. **Keep everything in version control.** This includes large files like
-   datasets, enabled by DVC.
-   The [Calkit cloud](https://github.com/calkit/calkit-cloud)
-   serves as a simple default DVC remote storage location for those who do not
-   want to manage their own infrastructure.
-2. **Generate all important artifacts with a single pipeline.** There should be
-   no special instructions required to reproduce a project's artifacts.
-   It should be as simple as calling `calkit run`.
-   The DVC pipeline (in a project's `dvc.yaml` file) is therefore the main
-   thing to "build" throughout a research project.
-   Calkit provides helper functionality to build pipeline stages that
-   keep computational environments up-to-date and label their outputs for
-   convenient reuse.
+To learn more, see the [documentation](https://docs.calkit.org).
 
 ## Installation
 
@@ -145,13 +132,15 @@ This will commit and push to both GitHub and the Calkit Cloud.
 
 ## Tutorials
 
-- [LaTeX collaboration with GitHub Codespaces](https://petebachant.me/latex-collab/)
-- [Jupyter notebook as a DVC pipeline](docs/tutorials/notebook-pipeline.md)
-- [Keeping track of conda environments](docs/tutorials/conda-envs.md)
-- [Defining and executing manual procedures](docs/tutorials/procedures.md)
-- [Adding a new LaTeX-based publication with its own Docker build environment](docs/tutorials/adding-latex-pub-docker.md)
-- [A reproducible workflow using Microsoft Office (Word and Excel)](https://petebachant.me/office-repro/)
-- [Reproducible OpenFOAM simulations](https://petebachant.me/reproducible-openfoam/)
+- [LaTeX collaboration with GitHub Codespaces](https://docs.calkit.org/tutorials/latex-codespaces/)
+- [Jupyter notebook as a DVC pipeline](https://docs.calkit.org/tutorials/notebook-pipeline/)
+- [Keeping track of conda environments](https://docs.calkit.org/tutorials/conda-envs/)
+- [Defining and executing manual procedures](https://docs.calkit.org/tutorials/procedures/)
+- [Adding a new LaTeX-based publication with its own Docker build environment](https://docs.calkit.org/tutorials/adding-latex-pub-docker/)
+- [A reproducible workflow using Microsoft Office (Word and Excel)](https://docs.calkit.org/tutorials/office/)
+- [Reproducible OpenFOAM simulations](https://docs.calkit.org/tutorials/openfoam/)
+
+See more in the [docs](https://docs.calkit.org).
 
 ## Why does reproducibility matter?
 

{calkit_python-0.14.5 → calkit_python-0.16.0}/README.md

@@ -4,7 +4,7 @@
   </a>
 </p>
 
-Calkit is a lightweight framework for reproducible research projects.
+Calkit is a framework and toolkit for reproducible research projects.
 It acts as a top-level layer to integrate and simplify the use of enabling
 technologies such as
 [Git](https://git-scm.com/),
@@ -15,22 +15,7 @@ Calkit also adds a domain-specific data model
 such that all aspects of the research process can be fully described in a
 single repository and therefore easily consumed by others.
 
-Our goal is to make reproducibility easier so it becomes more common.
-To do this, we try to make it easy for users to follow two simple rules:
-
-1. **Keep everything in version control.** This includes large files like
-   datasets, enabled by DVC.
-   The [Calkit cloud](https://github.com/calkit/calkit-cloud)
-   serves as a simple default DVC remote storage location for those who do not
-   want to manage their own infrastructure.
-2. **Generate all important artifacts with a single pipeline.** There should be
-   no special instructions required to reproduce a project's artifacts.
-   It should be as simple as calling `calkit run`.
-   The DVC pipeline (in a project's `dvc.yaml` file) is therefore the main
-   thing to "build" throughout a research project.
-   Calkit provides helper functionality to build pipeline stages that
-   keep computational environments up-to-date and label their outputs for
-   convenient reuse.
+To learn more, see the [documentation](https://docs.calkit.org).
 
 ## Installation
 
@@ -106,13 +91,15 @@ This will commit and push to both GitHub and the Calkit Cloud.
 
 ## Tutorials
 
-- [LaTeX collaboration with GitHub Codespaces](https://petebachant.me/latex-collab/)
-- [Jupyter notebook as a DVC pipeline](docs/tutorials/notebook-pipeline.md)
-- [Keeping track of conda environments](docs/tutorials/conda-envs.md)
-- [Defining and executing manual procedures](docs/tutorials/procedures.md)
-- [Adding a new LaTeX-based publication with its own Docker build environment](docs/tutorials/adding-latex-pub-docker.md)
-- [A reproducible workflow using Microsoft Office (Word and Excel)](https://petebachant.me/office-repro/)
-- [Reproducible OpenFOAM simulations](https://petebachant.me/reproducible-openfoam/)
+- [LaTeX collaboration with GitHub Codespaces](https://docs.calkit.org/tutorials/latex-codespaces/)
+- [Jupyter notebook as a DVC pipeline](https://docs.calkit.org/tutorials/notebook-pipeline/)
+- [Keeping track of conda environments](https://docs.calkit.org/tutorials/conda-envs/)
+- [Defining and executing manual procedures](https://docs.calkit.org/tutorials/procedures/)
+- [Adding a new LaTeX-based publication with its own Docker build environment](https://docs.calkit.org/tutorials/adding-latex-pub-docker/)
+- [A reproducible workflow using Microsoft Office (Word and Excel)](https://docs.calkit.org/tutorials/office/)
+- [Reproducible OpenFOAM simulations](https://docs.calkit.org/tutorials/openfoam/)
+
+See more in the [docs](https://docs.calkit.org).
 
 ## Why does reproducibility matter?
 

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.14.5"
+__version__ = "0.16.0"
 
 from .core import *
 from . import git

calkit_python-0.16.0/calkit/cli/check.py

@@ -0,0 +1,48 @@
+"""CLI for checking things."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Annotated
+
+import typer
+
+from calkit.check import check_reproducibility
+from calkit.cli import raise_error
+
+check_app = typer.Typer(no_args_is_help=True)
+
+
+@check_app.command(name="repro")
+def check_repro(
+    wdir: Annotated[
+        str, typer.Option("--wdir", help="Project working directory.")
+    ] = ".",
+):
+    """Check the reproducibility of a project."""
+    res = check_reproducibility(wdir=wdir, log_func=typer.echo)
+    typer.echo(res.to_pretty().encode("utf-8", errors="replace"))
+
+
+@check_app.command(name="call")
+def check_call(
+    cmd: Annotated[str, typer.Argument(help="Command to check.")],
+    if_error: Annotated[
+        str,
+        typer.Option(
+            "--if-error", help="Command to run if there is an error."
+        ),
+    ],
+):
+    """Check that a command succeeds and run an alternate if not."""
+    try:
+        subprocess.check_call(cmd, shell=True)
+        typer.echo("Command succeeded")
+    except subprocess.CalledProcessError:
+        typer.echo("Command failed")
+        try:
+            typer.echo("Attempting fallback call")
+            subprocess.check_call(if_error, shell=True)
+            typer.echo("Fallback call succeeded")
+        except subprocess.CalledProcessError:
+            raise_error("Fallback call failed")

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/cli/main.py

@@ -12,12 +12,16 @@ import subprocess
 import sys
 import time
 
+import dotenv
+import dvc.repo
 import git
 import typer
+from dvc.exceptions import NotDvcRepoError
+from git.exc import InvalidGitRepositoryError
 from typing_extensions import Annotated, Optional
 
 import calkit
-from calkit.cli import print_sep, raise_error, run_cmd
+from calkit.cli import print_sep, raise_error, run_cmd, warn
 from calkit.cli.check import check_app
 from calkit.cli.config import config_app
 from calkit.cli.import_ import import_app
@@ -57,8 +61,8 @@ def _to_shell_cmd(cmd: list[str]) -> str:
     quoted_cmd = []
     for part in cmd:
         if " " in part or '"' in part or "'" in part:
-            part = part.replace('"', r'\"')
-            quoted_cmd.append(f"\"{part}\"")
+            part = part.replace('"', r"\"")
+            quoted_cmd.append(f'"{part}"')
         else:
             quoted_cmd.append(part)
     return " ".join(quoted_cmd)
@@ -76,6 +80,29 @@ def main(
         raise typer.Exit()
 
 
+@app.command(name="init")
+def init(
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            "-f",
+            help="Force reinitializing DVC if already initialized.",
+        ),
+    ] = False,
+):
+    """Initialize the current working directory."""
+    subprocess.run(["git", "init"])
+    dvc_cmd = ["dvc", "init"]
+    if force:
+        dvc_cmd.append("-f")
+    subprocess.run(dvc_cmd)
+    # TODO: Initialize `calkit.yaml`
+    # TODO: Initialize `dvc.yaml`
+    # TODO: Add a sane .gitignore file
+    # TODO: Add a sane LICENSE file?
+
+
 @app.command(name="clone")
 def clone(
     url: Annotated[str, typer.Argument(help="Repo URL.")],
@@ -183,6 +210,16 @@ def add(
     """
     if to is not None and to not in ["git", "dvc"]:
         raise_error(f"Invalid option for 'to': {to}")
+    try:
+        repo = git.Repo()
+    except InvalidGitRepositoryError:
+        warn("Not currently in a Git repo; initializing")
+        repo = git.Repo.init()
+    try:
+        dvc_repo = dvc.repo.Repo()
+    except NotDvcRepoError:
+        warn("DVC not initialized yet; initializing")
+        dvc_repo = dvc.repo.Repo.init()
     # Ensure autostage is enabled for DVC
     subprocess.call(["dvc", "config", "core.autostage", "true"])
     subprocess.call(["git", "add", ".dvc/config"])
@@ -207,13 +244,11 @@ def add(
             ".doc",
         ]
         dvc_size_thresh_bytes = 1_000_000
+        dvc_paths = [
+            obj.get("path") for obj in dvc_repo.ls(".", dvc_only=True)
+        ]
         if "." in paths and to is None:
             raise_error("Cannot add '.' with calkit; use git or dvc")
-        if to is None:
-            for path in paths:
-                if os.path.isdir(path):
-                    raise_error("Cannot auto-add directories; use git or dvc")
-        repo = git.Repo()
         for path in paths:
             # Detect if this file should be tracked with Git or DVC
             # First see if it's in Git
@@ -222,19 +257,22 @@ def add(
                     f"Adding {path} to Git since it's already in the repo"
                 )
                 subprocess.call(["git", "add", path])
-                continue
-            if os.path.splitext(path)[-1] in dvc_extensions:
+            elif path in dvc_paths:
+                typer.echo(
+                    f"Adding {path} to DVC since it's already tracked with DVC"
+                )
+                subprocess.call(["dvc", "add", path])
+            elif os.path.splitext(path)[-1] in dvc_extensions:
                 typer.echo(f"Adding {path} to DVC per its extension")
                 subprocess.call(["dvc", "add", path])
-                continue
-            if os.path.getsize(path) > dvc_size_thresh_bytes:
+            elif calkit.get_size(path) > dvc_size_thresh_bytes:
                 typer.echo(
                     f"Adding {path} to DVC since it's greater than 1 MB"
                 )
                 subprocess.call(["dvc", "add", path])
-                continue
-            typer.echo(f"Adding {path} to Git")
-            subprocess.call(["git", "add", path])
+            else:
+                typer.echo(f"Adding {path} to Git")
+                subprocess.call(["git", "add", path])
     if commit_message is not None:
         subprocess.call(["git", "commit", "-m", commit_message])
     if push_commit:
@@ -260,6 +298,10 @@ def commit(
     ] = False,
 ):
     """Commit a change to the repo."""
+    if message is None:
+        typer.echo("Please provide a message describing the changes.")
+        typer.echo("Example: Update y-label in scripts/plot-data.py")
+        message = typer.prompt("Message")
     cmd = ["git", "commit"]
     if all:
         cmd.append("-a")
@@ -281,10 +323,12 @@ def save(
             ),
         ),
     ] = None,
-    all: Annotated[
+    save_all: Annotated[
         Optional[bool],
         typer.Option(
-            "--all", "-a", help="Automatically stage all changed files."
+            "--all",
+            "-a",
+            help=("Save all, automatically handling staging and ignoring."),
         ),
     ] = False,
     message: Annotated[
@@ -307,8 +351,56 @@ def save(
 
     This is essentially git/dvc add, commit, and push in one step.
     """
+    if not paths and not save_all:
+        raise_error("Paths must be provided if not using --all")
     if paths is not None:
         add(paths, to=to)
+    elif save_all:
+        # First check to see if we should commit anything to DVC
+        dvc_repo = dvc.repo.Repo()
+        dvc_status = dvc_repo.data_status()
+        for dvc_uncommitted in dvc_status["uncommitted"].get("modified", []):
+            typer.echo(f"Adding {dvc_uncommitted} to DVC")
+            dvc_repo.commit(dvc_uncommitted, force=True)
+        repo = git.Repo()
+        untracked_git_files = repo.untracked_files
+        auto_ignore_suffixes = [".DS_Store", ".env"]
+        auto_ignore_paths = [os.path.join(".dvc", "config.local")]
+        auto_ignore_prefixes = [".venv"]
+        for untracked_file in untracked_git_files:
+            if (
+                any(
+                    [
+                        untracked_file.endswith(suffix)
+                        for suffix in auto_ignore_suffixes
+                    ]
+                )
+                or any(
+                    [
+                        untracked_file.startswith(prefix)
+                        for prefix in auto_ignore_prefixes
+                    ]
+                )
+                or untracked_file in auto_ignore_paths
+            ):
+                typer.echo(f"Automatically ignoring {untracked_file}")
+                with open(".gitignore", "a") as f:
+                    f.write("\n" + untracked_file + "\n")
+        # TODO: Figure out if we should group large folders for dvc
+        # Now add untracked files automatically
+        for untracked_file in repo.untracked_files:
+            add(paths=[untracked_file])
+        # Now add changed files
+        for changed_file in [d.a_path for d in repo.index.diff(None)]:
+            repo.git.add(changed_file)
+    if message is None:
+        typer.echo("No message provided; entering interactive mode")
+        typer.echo("Creating a commit including the following paths:")
+        for path in calkit.git.get_staged_files():
+            typer.echo(f"- {path}")
+        typer.echo("Please provide a message describing the changes.")
+        typer.echo("Example: Add new data to data/raw")
+        message = typer.prompt("Message")
     commit(all=True if paths is None else False, message=message)
     if not no_push:
         push()
@@ -316,7 +408,7 @@ def save(
 
 @app.command(name="pull")
 def pull(
-    no_check_auth: Annotated[bool, typer.Option("--no-check-auth")] = False
+    no_check_auth: Annotated[bool, typer.Option("--no-check-auth")] = False,
 ):
     """Pull with both Git and DVC."""
     typer.echo("Git pulling")
@@ -340,7 +432,7 @@ def pull(
 
 @app.command(name="push")
 def push(
-    no_check_auth: Annotated[bool, typer.Option("--no-check-auth")] = False
+    no_check_auth: Annotated[bool, typer.Option("--no-check-auth")] = False,
 ):
     """Push with both Git and DVC."""
     typer.echo("Pushing to Git remote")
@@ -380,7 +472,7 @@ def run_local_server():
     name="run",
     add_help_option=False,
 )
-def run_dvc_repro(
+def run(
     targets: Optional[list[str]] = typer.Argument(default=None),
     help: Annotated[bool, typer.Option("-h", "--help")] = False,
     quiet: Annotated[bool, typer.Option("-q", "--quiet")] = False,
@@ -410,9 +502,8 @@ def run_dvc_repro(
     no_commit: Annotated[bool, typer.Option("--no-commit")] = False,
     no_run_cache: Annotated[bool, typer.Option("--no-run-cache")] = False,
 ):
-    """Run DVC pipeline and parse Calkit objects from metadata after checking
-    system dependencies.
-    """
+    """Check dependencies, run DVC pipeline, and update Calkit objects."""
+    dotenv.load_dotenv(dotenv_path=".env", verbose=verbose)
     # First check any system-level dependencies exist
     typer.echo("Checking system-level dependencies")
     try:
@@ -596,6 +687,7 @@ def run_in_env(
         bool, typer.Option("--verbose", "-v", help="Print verbose output.")
     ] = False,
 ):
+    dotenv.load_dotenv(dotenv_path=".env", verbose=verbose)
     ck_info = calkit.load_calkit_info(process_includes="environments")
     envs = ck_info.get("environments", {})
     if not envs:
@@ -755,35 +847,6 @@ def run_in_env(
         raise_error("Environment kind not supported")
 
 
-@app.command(
-    name="check-call",
-    help=(
-        "Check that a call to a command succeeds and run another command "
-        "if there is an error."
-    ),
-)
-def check_call(
-    cmd: Annotated[str, typer.Argument(help="Command to check.")],
-    if_error: Annotated[
-        str,
-        typer.Option(
-            "--if-error", help="Command to run if there is an error."
-        ),
-    ],
-):
-    try:
-        subprocess.check_call(cmd, shell=True)
-        typer.echo("Command succeeded")
-    except subprocess.CalledProcessError:
-        typer.echo("Command failed")
-        try:
-            typer.echo("Attempting fallback call")
-            subprocess.check_call(if_error, shell=True)
-            typer.echo("Fallback call succeeded")
-        except subprocess.CalledProcessError:
-            raise_error("Fallback call failed")
-
-
 @app.command(
     name="build-docker",
     help="Build Docker image if missing or different from lock file.",
@@ -900,7 +963,7 @@ def run_procedure(
     # Check to make sure the working tree is clean, so we know we ran the
     # committed version of the procedure
     git_status = git_repo.git.status()
-    if not "working tree clean" in git_status:
+    if "working tree clean" not in git_status:
         raise_error(
             f"Cannot execute procedures unless repo is clean:\n\n{git_status}"
         )
@@ -1079,3 +1142,29 @@ def run_calculation(
             typer.echo(calc.evaluate_and_format(**parsed_inputs))
     except Exception as e:
         raise_error(f"Calculation failed: {e}")
+
+
+@app.command(name="set-env-var")
+def set_env_var(
+    name: Annotated[str, typer.Argument(help="Name of the variable.")],
+    value: Annotated[str, typer.Argument(help="Value of the variable.")],
+):
+    """Set an environmental variable for the project in its '.env' file."""
+    # Ensure that .env is ignored by git
+    repo = git.Repo()
+    if not repo.ignored(".env"):
+        typer.echo("Adding .env to .gitignore")
+        with open(".gitignore", "a") as f:
+            f.write("\n.env\n")
+    dotenv.set_key(dotenv_path=".env", key_to_set=name, value_to_set=value)
+
+
+@app.command(name="upgrade")
+def upgrade():
+    """Upgrade Calkit."""
+    # See if uv is installed first
+    if calkit.check_dep_exists("uv"):
+        cmd = ["uv", "pip", "install", "--system"]
+    else:
+        cmd = ["pip", "install"]
+    subprocess.run(cmd + ["--upgrade", "calkit-python"])

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/cli/new.py

@@ -89,8 +89,7 @@ def new_project(
     ] = False,
 ):
     """Create a new project."""
-    # TODO: Update this when there is a real docs site up
-    docs_url = "https://github.com/calkit/calkit?tab=readme-ov-file#tutorials"
+    docs_url = "https://docs.calkit.org"
     success_message = (
         "\nCongrats on creating your new Calkit project!\n\n"
         "Next, you'll probably want to start building your pipeline.\n\n"

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/core.py

@@ -362,3 +362,21 @@ def read_file(path: str, as_bytes: bool = None) -> str | bytes:
     # Project is None, so let's just read a local file
     with open(path, mode="rb" if as_bytes else "r") as f:
         return f.read()
+
+
+def get_size(path: str):
+    """Get the size of a path in bytes.
+
+    This differs from ``os.path.getsize`` in that it is recursive.
+    """
+    if os.path.isfile(path):
+        return os.path.getsize(path)
+    # From https://stackoverflow.com/a/1392549/2284865
+    total_size = 0
+    for dirpath, dirnames, filenames in os.walk(path):
+        for f in filenames:
+            fp = os.path.join(dirpath, f)
+            # skip if it is symbolic link
+            if not os.path.islink(fp):
+                total_size += os.path.getsize(fp)
+    return total_size

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/dvc.py

@@ -6,6 +6,8 @@ import logging
 import os
 import subprocess
 
+import dvc.repo
+
 import calkit
 from calkit.config import get_app_name
 
@@ -102,3 +104,9 @@ def get_remotes(wdir: str = None) -> dict[str, str]:
         name, url = line.split("\t")
         resp[name] = url
     return resp
+
+
+def list_paths(wdir: str = None) -> list[str]:
+    """List paths tracked with DVC."""
+    dvc_repo = dvc.repo.Repo(wdir)
+    return [p.get("path") for p in dvc_repo.ls(".", dvc_only=True)]

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/git.py

@@ -20,3 +20,13 @@ def detect_project_name(path: str = None) -> str:
     if owner is None:
         owner = owner_name
     return f"{owner}/{name}"
+
+
+def get_staged_files(path: str = None) -> list[str]:
+    repo = git.Repo(path)
+    cmd = ["--staged", "--name-only"]
+    if path is not None:
+        cmd.append(path)
+    diff = repo.git.diff(cmd)
+    paths = diff.split("\n")
+    return paths

{calkit_python-0.14.5 → calkit_python-0.16.0}/calkit/models.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime, timedelta
+from datetime import timedelta
 from typing import Literal
 
 from pydantic import BaseModel
@@ -21,7 +21,7 @@ class _ImportedFromUrl(BaseModel):
 class _CalkitObject(BaseModel):
     path: str
     title: str
-    description: str
+    description: str | None = None
     stage: str | None = None
 
 
@@ -201,6 +201,20 @@ class ModelRelease(Release):
     path: str
 
 
+class ShowcaseFigure(BaseModel):
+    figure: str
+
+
+class ShowcaseText(BaseModel):
+    text: str
+
+
+class DerivedFromProject(BaseModel):
+    project: str
+    git_repo_url: str
+    git_rev: str
+
+
 class ProjectInfo(BaseModel):
     """All of the project's information or metadata, written to the
     ``calkit.yaml`` file.
@@ -226,7 +240,7 @@ class ProjectInfo(BaseModel):
     description: str | None = None
     name: str | None = None
     git_repo_url: str | None = None
-    parent: str | None = None
+    derived_from: DerivedFromProject | None = None
     questions: list[str] = []
     datasets: list[Dataset] = []
     figures: list[Figure] = []
@@ -243,3 +257,4 @@ class ProjectInfo(BaseModel):
         str,
         ProjectRelease | PublicationRelease | DatasetRelease | ModelRelease,
     ] = {}
+    showcase: list[ShowcaseFigure | ShowcaseText] | None = None