calkit-python 0.0.1__tar.gz

calkit_python-0.0.1/.github/FUNDING.yml

@@ -0,0 +1,16 @@
+# These are supported funding model platforms
+
+github:
+  - petebachant
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

calkit_python-0.0.1/.github/workflows/publish-test.yml

@@ -0,0 +1,49 @@
+name: Publish to TestPyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install pypa/build
+        run: >-
+          python3 -m
+          pip install
+          build
+          --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+  publish-to-testpypi:
+    name: Publish Python 🐍 distribution 📦 to TestPyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/calkit-python
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

calkit_python-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install pypa/build
+        run: >-
+          python3 -m
+          pip install
+          build
+          --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/calkit
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

calkit_python-0.0.1/.gitignore

@@ -0,0 +1,3 @@
+dev.ipynb
+*.pyc
+.DS_Store

calkit_python-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 Pete Bachant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calkit_python-0.0.1/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.3
+Name: calkit-python
+Version: 0.0.1
+Summary: Reproducibility made easy.
+Project-URL: Homepage, https://github.com/calkit/calkit
+Project-URL: Issues, https://github.com/calkit/calkit/issues
+Author-email: Pete Bachant <petebachant@gmail.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: dvc
+Requires-Dist: fastapi
+Requires-Dist: gitpython
+Requires-Dist: keyring
+Requires-Dist: pandas
+Requires-Dist: polars
+Requires-Dist: pydantic-settings
+Requires-Dist: pydantic[email]
+Requires-Dist: pyjwt
+Requires-Dist: requests
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# Calkit
+
+[Calkit](https://calkit.io) makes reproducible research easy,
+acting as a layer on top of
+[Git](https://git-scm.com/) and [DVC](https://dvc.org/), such that all
+all materials involved in the research process can be fully described in a
+single repository.
+
+## Installation
+
+Simply run
+
+```sh
+pip install calkit-python
+```
+
+## Cloud integration
+
+The Calkit cloud platform (https://calkit.io) serves as a project
+management interface and a DVC remote for easily storing all versions of your
+data/code/figures/publications, interacting with your collaborators,
+reusing others' research artifacts, etc.
+
+After signing up, visit the [settings](https://calkit.io/settings) page
+and create a token.
+Then run
+
+```sh
+calkit config set token ${YOUR_TOKEN_HERE}
+```
+
+Then, inside a project repo you'd like to connect to the cloud, run
+
+```sh
+calkit config setup-remote
+```
+
+This will setup the Calkit DVC remote, such that commands like `dvc push` will
+allow you to push versions of your data or pipeline outputs to the cloud
+for safe storage and sharing with your collaborators.
+
+## How it works
+
+Calkit creates a simple human-readable "database" inside the `calkit.yaml`
+file, which serves as a way to store important information about the project,
+e.g., what question(s) it seeks to answer,
+what files should be considered datasets, figures, publications, etc.
+The Calkit cloud reads this database and registers the various entities
+as part of the entire ecosystem such that if a project is made public,
+other researchers can find and reuse your work to accelerate their own.

calkit_python-0.0.1/README.md

@@ -0,0 +1,50 @@
+# Calkit
+
+[Calkit](https://calkit.io) makes reproducible research easy,
+acting as a layer on top of
+[Git](https://git-scm.com/) and [DVC](https://dvc.org/), such that all
+all materials involved in the research process can be fully described in a
+single repository.
+
+## Installation
+
+Simply run
+
+```sh
+pip install calkit-python
+```
+
+## Cloud integration
+
+The Calkit cloud platform (https://calkit.io) serves as a project
+management interface and a DVC remote for easily storing all versions of your
+data/code/figures/publications, interacting with your collaborators,
+reusing others' research artifacts, etc.
+
+After signing up, visit the [settings](https://calkit.io/settings) page
+and create a token.
+Then run
+
+```sh
+calkit config set token ${YOUR_TOKEN_HERE}
+```
+
+Then, inside a project repo you'd like to connect to the cloud, run
+
+```sh
+calkit config setup-remote
+```
+
+This will setup the Calkit DVC remote, such that commands like `dvc push` will
+allow you to push versions of your data or pipeline outputs to the cloud
+for safe storage and sharing with your collaborators.
+
+## How it works
+
+Calkit creates a simple human-readable "database" inside the `calkit.yaml`
+file, which serves as a way to store important information about the project,
+e.g., what question(s) it seeks to answer,
+what files should be considered datasets, figures, publications, etc.
+The Calkit cloud reads this database and registers the various entities
+as part of the entire ecosystem such that if a project is made public,
+other researchers can find and reuse your work to accelerate their own.

calkit_python-0.0.1/calkit/__init__.py

@@ -0,0 +1,8 @@
+__version__ = "0.0.1"
+
+from .core import *
+from . import git
+from . import dvc
+from . import cloud
+from . import jupyter
+from . import config

calkit_python-0.0.1/calkit/cli.py

@@ -0,0 +1,117 @@
+"""The command line interface."""
+
+import os
+import pty
+import subprocess
+import sys
+
+import typer
+from typing_extensions import Annotated, Optional
+
+import calkit
+
+from . import config
+from .dvc import configure_remote, set_remote_auth
+
+app = typer.Typer()
+config_app = typer.Typer()
+app.add_typer(config_app, name="config", help="Configure Calkit.")
+
+
+@config_app.command(name="set")
+def set_config_value(key: str, value: str):
+    try:
+        cfg = config.read()
+        cfg = config.Settings.model_validate(cfg.model_dump() | {key: value})
+        # Kind of a hack for setting the password computed field
+        # Types have been validated above, so this won't hurt to do again
+        setattr(cfg, key, value)
+    except FileNotFoundError:
+        # TODO: This fails if we try to set password before any config has
+        # been written
+        # Username is fine
+        cfg = config.Settings.model_validate({key: value})
+    cfg.write()
+
+
+@config_app.command(name="get")
+def get_config_value(key: str) -> None:
+    cfg = config.read()
+    val = getattr(cfg, key)
+    if val is not None:
+        print(val)
+    else:
+        print()
+
+
+@config_app.command(name="setup-remote")
+def setup_remote():
+    configure_remote()
+    set_remote_auth()
+
+
+@app.command(name="status")
+def get_status():
+    """Get a unified Git and DVC status."""
+
+    def print_sep(name: str):
+        print(f"------------ {name} ------------")
+
+    print_sep("Code")
+    if os.name == "nt":
+        subprocess.call(["git", "status"])
+        print()
+        print_sep("data")
+        subprocess.call(["dvc", "status"])
+    else:
+        pty.spawn(["git", "status"], lambda fd: os.read(fd, 1024))
+        print()
+        print_sep("Data")
+        pty.spawn(["dvc", "status"], lambda fd: os.read(fd, 1024))
+
+
+@app.command(name="add")
+def add(paths: list[str]):
+    """Add paths to the repo.
+
+    Code will be added to Git and data will be added to DVC.
+    """
+    dvc_extensions = [".png", ".h5", ".parquet", ".pickle"]
+    dvc_size_thresh_bytes = 1_000_000
+    dvc_folders = ["data", "figures"]
+    if "." in paths:
+        print("ERROR: Cannot add '.' with calkit; use git or dvc")
+        sys.exit(1)
+    for path in paths:
+        if os.path.isdir(path):
+            print("ERROR: Cannot add directories with calkit; use git or dvc")
+            sys.exit(1)
+        # Detect if this file should be tracked with Git or DVC
+        # TODO: Add to whatever
+
+
+@app.command(name="commit")
+def commit(
+    all: Annotated[Optional[bool], typer.Option("--all", "-a")] = False,
+    message: Annotated[Optional[str], typer.Option("--message", "-m")] = None,
+):
+    """Commit a change to the repo."""
+    print(all, message)
+    raise NotImplementedError
+
+
+@app.command(name="server")
+def run_server():
+    import uvicorn
+
+    uvicorn.run(
+        "calkit.server:app",
+        port=8866,
+        host="localhost",
+        reload=True,
+        reload_dirs=[os.path.dirname(__file__)],
+    )
+
+
+def run() -> None:
+    app()

calkit_python-0.0.1/calkit/cloud.py

@@ -0,0 +1,95 @@
+"""The REST API client."""
+
+import os
+from functools import partial
+from typing import Literal
+
+import requests
+
+from . import config
+
+# A dictionary of tokens keyed by base URL
+_tokens = {}
+
+
+def get_base_url() -> str:
+    """Get the API base URL."""
+    urls = {
+        "local": "http://api.localhost",
+        "staging": "https://api.staging.calkit.io",
+        "production": "https://api.calkit.io",
+    }
+    return urls[config.get_env()]
+
+
+def get_token() -> str:
+    """Get a token.
+
+    Automatically reauthenticate if the token doesn't exist or has expired.
+    """
+    token = _tokens.get(get_base_url())
+    if token is None:
+        token = config.read().token
+        _tokens[get_base_url()] = token
+    # TODO: Check for expiration
+    if token is None:
+        return auth()
+    return token
+
+
+def get_headers(headers: dict | None = None) -> dict:
+    base_headers = {"Authorization": f"Bearer {get_token()}"}
+    if headers is not None:
+        return base_headers | headers
+    else:
+        return base_headers
+
+
+def auth() -> str:
+    """Authenticate with the server and save a token."""
+    cfg = config.read()
+    base_url = get_base_url()
+    resp = requests.post(
+        base_url + "/login/access-token",
+        data=dict(username=cfg.username, password=cfg.password),
+    )
+    token = resp.json()["access_token"]
+    _tokens[base_url] = token
+    return token
+
+
+def _request(
+    kind: Literal["get", "post", "put", "patch", "delete"],
+    path: str,
+    params: dict | None = None,
+    json: dict | None = None,
+    data: dict | None = None,
+    headers: dict | None = None,
+    as_json=True,
+    **kwargs,
+):
+    func = getattr(requests, kind)
+    resp = func(
+        get_base_url() + path,
+        params=params,
+        json=json,
+        data=data,
+        headers=get_headers(headers),
+        **kwargs,
+    )
+    resp.raise_for_status()
+    if as_json:
+        return resp.json()
+    else:
+        return resp
+
+
+get = partial(_request, "get")
+post = partial(_request, "post")
+patch = partial(_request, "patch")
+put = partial(_request, "put")
+delete = partial(_request, "delete")
+
+
+def get_current_user() -> dict:
+    return get("/user")

calkit_python-0.0.1/calkit/config.py

@@ -0,0 +1,71 @@
+"""Configuration."""
+
+import os
+from typing import Literal
+
+import keyring
+import yaml
+from pydantic import EmailStr, computed_field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def get_env() -> Literal["local", "staging", "production"]:
+    return os.getenv(f"{__package__.upper()}_ENV", "production")
+
+
+def set_env(name: Literal["local", "staging", "production"]) -> None:
+    if name not in ["local", "staging", "production"]:
+        raise ValueError(f"{name} is not a valid environment name")
+    os.environ[f"{__package__.upper()}_ENV"] = name
+
+
+def get_env_suffix() -> str:
+    if get_env() != "production":
+        return "-" + get_env()
+    return ""
+
+
+def get_app_name() -> str:
+    return __package__ + get_env_suffix()
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        yaml_file=os.path.join(
+            os.path.expanduser("~"),
+            "." + __package__,
+            f"config{get_env_suffix()}.yaml",
+        ),
+        extra="ignore",
+    )
+    username: EmailStr | None = None
+    token: str | None = None
+    dvc_token: str | None = None
+    dataframe_engine: Literal["pandas", "polars"] = "pandas"
+
+    @computed_field
+    @property
+    def password(self) -> str:
+        return keyring.get_password(get_app_name(), self.username)
+
+    @password.setter
+    def password(self, value: str) -> None:
+        keyring.set_password(get_app_name(), self.username, value)
+
+    def write(self) -> None:
+        base_dir = os.path.dirname(self.model_config["yaml_file"])
+        os.makedirs(base_dir, exist_ok=True)
+        cfg = self.model_dump()
+        # Remove password
+        _ = cfg.pop("password")
+        with open(self.model_config["yaml_file"], "w") as f:
+            yaml.safe_dump(cfg, f)
+
+
+def read() -> Settings:
+    """Read the config."""
+    fpath = Settings.model_config["yaml_file"]
+    if not os.path.isfile(fpath):
+        return Settings()
+    with open(fpath) as f:
+        return Settings.model_validate(yaml.safe_load(f))

calkit_python-0.0.1/calkit/core.py

@@ -0,0 +1,34 @@
+"""Core functionality."""
+
+import glob
+import os
+
+from git import Repo
+from git.exc import InvalidGitRepositoryError
+
+
+def find_project_dirs(relative=False, max_depth=3) -> list[str]:
+    """Find all Calkit project directories."""
+    if relative:
+        start = ""
+    else:
+        start = os.path.expanduser("~")
+    res = []
+    for i in range(max_depth):
+        pattern = os.path.join(start, *["*"] * (i + 1), "calkit.yaml")
+        res += glob.glob(pattern)
+        # Check GitHub documents for users who use GitHub Desktop
+        pattern = os.path.join(
+            start, "*", "GitHub", *["*"] * (i + 1), "calkit.yaml"
+        )
+        res += glob.glob(pattern)
+    final_res = []
+    for ck_fpath in res:
+        path = os.path.dirname(ck_fpath)
+        # Make sure this path is a Git repo
+        try:
+            Repo(path)
+        except InvalidGitRepositoryError:
+            continue
+        final_res.append(path)
+    return final_res

calkit_python-0.0.1/calkit/data.py

@@ -0,0 +1,53 @@
+"""Functionality for working with datasets."""
+
+from typing import Literal, Union
+
+import pandas as pd
+import polars as pl
+
+import calkit.config
+
+DEFAULT_ENGINE = calkit.config.read().dataframe_engine
+
+
+def list_data():
+    """Read the Calkit metadata file and list out our datasets."""
+    pass
+
+
+def read_data(
+    path: str, engine: Literal["pandas", "polars"] = DEFAULT_ENGINE
+) -> Union[pd.DataFrame, pl.DataFrame]:
+    """Read (tabular) data from dataset with path ``path`` and return a
+    DataFrame.
+
+    If the dataset doesn't exist locally, but is a DVC object, download it
+    first.
+
+    If the dataset path includes a user and project name, we add it to the
+    project as an imported dataset, and therefore DVC import it?
+
+    For example: someuser/someproject:data/somefile.parquet
+
+    We can run a DVC import command if it needs to be imported. We will need to
+    find the Git repo and path within it? Maybe we should require an explicit
+    import of the data.
+    """
+    pass
+
+
+def write_data(
+    data: Union[pd.DataFrame, pl.DataFrame],
+    path: str,
+    filename: str | None = None,
+    commit=False,
+):
+    """Write ``data`` to the dataset with path ``path``.
+
+    If the dataset path is a directory, the filename must be specified.
+
+    If the path is not a Calkit dataset, it will be created.
+
+    If ``commit`` is specified, create a commit for the dataset update.
+    """
+    pass

calkit_python-0.0.1/calkit/dvc.py

@@ -0,0 +1,58 @@
+"""Working with DVC."""
+
+import logging
+import subprocess
+
+import calkit
+from calkit.config import get_app_name
+
+logger = logging.getLogger(__package__)
+logger.setLevel(logging.INFO)
+
+
+def configure_remote():
+    project_name = calkit.git.detect_project_name()
+    base_url = calkit.cloud.get_base_url()
+    remote_url = f"{base_url}/projects/{project_name}/dvc"
+    subprocess.call(
+        ["dvc", "remote", "add", "-d", "-f", get_app_name(), remote_url]
+    )
+    subprocess.call(
+        ["dvc", "remote", "modify", get_app_name(), "auth", "custom"]
+    )
+
+
+def set_remote_auth():
+    """Get a token and set it in the local DVC config so we can interact with
+    the cloud as an HTTP remote.
+    """
+    settings = calkit.config.read()
+    if settings.dvc_token is None:
+        logger.info("Creating token for DVC scope")
+        token = calkit.cloud.post(
+            "/user/tokens", json=dict(expires_days=365, scope="dvc")
+        )["access_token"]
+        settings.dvc_token = token
+        settings.write()
+    subprocess.call(
+        [
+            "dvc",
+            "remote",
+            "modify",
+            "--local",
+            get_app_name(),
+            "custom_auth_header",
+            "Authorization",
+        ]
+    )
+    subprocess.call(
+        [
+            "dvc",
+            "remote",
+            "modify",
+            "--local",
+            get_app_name(),
+            "password",
+            f"Bearer {settings.dvc_token}",
+        ]
+    )

calkit_python-0.0.1/calkit/git.py

@@ -0,0 +1,12 @@
+"""Git-related functionality."""
+
+import git
+
+
+def detect_project_name(path=None) -> str:
+    """Read the project owner and name from the remote.
+
+    TODO: Currently only works with GitHub remotes.
+    """
+    url = git.Repo(path=path).remote().url
+    return url.split("github.com")[-1][1:].removesuffix(".git")

calkit_python-0.0.1/calkit/gui.py

@@ -0,0 +1 @@
+"""An optional GUI."""

calkit_python-0.0.1/calkit/jupyter.py

@@ -0,0 +1,46 @@
+"""Functionality for working with Jupyter."""
+
+import subprocess
+
+from pydantic import BaseModel
+
+
+class Server(BaseModel):
+    url: str
+    wdir: str
+    token: str
+
+
+def get_servers() -> list[Server]:
+    out = (
+        subprocess.check_output(["jupyter", "server", "list"])
+        .decode()
+        .strip()
+        .split("\n")
+    )
+    resp = []
+    for line in out:
+        if line.startswith("http://"):
+            url, wdir = line.split(" :: ")
+            token = url.split("?token=")[-1]
+            resp.append(Server(url=url, wdir=wdir, token=token))
+    return resp
+
+
+def start_server(wdir=None, no_browser=False):
+    """Start a Jupyter server."""
+    subprocess.Popen(
+        [
+            "jupyter",
+            "lab",
+            "-y",
+            "--no-browser" if no_browser else "",
+        ],
+        cwd=wdir,
+    )
+
+
+def stop_server(url: str):
+    # Extract the port from the URL
+    port = url.split(":")[2][:4]
+    subprocess.call(["jupyter", "server", "stop", port])

calkit_python-0.0.1/calkit/server.py

@@ -0,0 +1,201 @@
+"""A local server for interacting with project repos."""
+
+import os
+
+import dvc
+import dvc.repo
+import git
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from starlette.middleware.cors import CORSMiddleware
+
+import calkit
+import calkit.jupyter
+
+app = FastAPI(title="calkit-server")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:5173",
+        "http://localhost",
+        "https://calkit.io",
+        "https://staging.calkit.io",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def get_health() -> str:
+    return "All good!"
+
+
+class LocalProject(BaseModel):
+    owner_name: str
+    project_name: str
+    wdir: str
+    jupyter_url: str | None
+    jupyter_token: str | None
+
+
+@app.get("/")
+def get_root() -> list[LocalProject]:
+    """Return information about the current running server.
+
+    - The project owner
+    - The project name
+    - The current working directory
+    - A Jupyter server running here, if applicable
+    """
+    resp = []
+    project_dirs = calkit.find_project_dirs()
+    servers = calkit.jupyter.get_servers()
+    for pdir in project_dirs:
+        project = calkit.git.detect_project_name(path=pdir)
+        owner, name = project.split("/")
+        url = token = None
+        for server in servers:
+            if server.wdir == pdir:
+                url = server.url
+                token = server.token
+                break
+        resp.append(
+            LocalProject(
+                owner_name=owner,
+                project_name=name,
+                wdir=os.path.abspath(pdir),
+                jupyter_token=token,
+                jupyter_url=url,
+            )
+        )
+    return resp
+
+
+@app.get("/projects/{owner_name}/{project_name}")
+def get_local_project(owner_name: str, project_name: str) -> LocalProject:
+    all_projects = get_root()
+    for project in all_projects:
+        if (
+            project.owner_name == owner_name
+            and project.project_name == project_name
+        ):
+            return project
+    raise HTTPException(404)
+
+
+@app.get("/projects/{owner_name}/{project_name}/jupyter-server")
+def get_project_jupyter_server(
+    owner_name: str,
+    project_name: str,
+    autostart=False,
+    no_browser=False,
+) -> calkit.jupyter.Server | None:
+    project = get_local_project(
+        owner_name=owner_name, project_name=project_name
+    )
+    if project is None:
+        return
+    if project.jupyter_url is not None:
+        return calkit.jupyter.Server(
+            url=project.jupyter_url,
+            token=project.jupyter_token,
+            wdir=project.wdir,
+        )
+    if autostart:
+        calkit.jupyter.start_server(project.wdir, no_browser=no_browser)
+        servers = calkit.jupyter.get_servers()
+        for server in servers:
+            if server.wdir == project.wdir:
+                return server
+
+
+@app.delete("/projects/{owner_name}/{project_name}/jupyter-server")
+def stop_project_jupyter_server(owner_name: str, project_name: str) -> None:
+    project = get_local_project(
+        owner_name=owner_name, project_name=project_name
+    )
+    if project is None:
+        return
+    if project.jupyter_url is not None:
+        calkit.jupyter.stop_server(url=project.jupyter_url)
+
+
+@app.get("/cwd")
+def get_cwd() -> str:
+    return os.getcwd()
+
+
+@app.get("/projects/{owner_name}/{project_name}/ls")
+def get_ls(owner_name: str, project_name: str) -> list[dict]:
+    project = get_local_project(owner_name, project_name)
+    repo = git.Repo(project.wdir)
+    contents = os.listdir(project.wdir)
+    resp = []
+    for item in contents:
+        if item == ".git" or repo.ignored(item):
+            continue
+        if os.path.isfile(os.path.join(project.wdir, item)):
+            kind = "file"
+        else:
+            kind = "dir"
+        resp.append(dict(name=item, type=kind))
+    return sorted(resp, key=lambda item: (item["type"], item["name"]))
+
+
+@app.post("/projects/{owner_name}/{project_name}/git/{command}")
+def run_git_command(
+    owner_name: str, project_name: str, command: str, params: dict = {}
+):
+    project = get_local_project(owner_name, project_name)
+    func = getattr(git.Repo(project.wdir).git, command)
+    return func(**params)
+
+
+@app.get("/diff")
+def get_diff():
+    """Get differences in working directory, from both Git and DVC."""
+    raise HTTPException(501)
+
+
+@app.get("/projects/{owner_name}/{project_name}/status")
+def get_status(owner_name: str, project_name: str):
+    """Get status in working directory, from both Git and DVC."""
+    project = get_local_project(owner_name, project_name)
+    git_repo = git.Repo(project.wdir)
+    untracked_git_files = git_repo.untracked_files
+    # Get a list of diffs of the working tree to the index
+    git_diff = git_repo.index.diff(None)
+    git_diff_files = [d.a_path for d in git_diff]
+    dvc_repo = dvc.repo.Repo(project.wdir)
+    # Get a dictionary of DVC artifacts that have changed, keyed by the DVC
+    # file, where values are a list, which may include a dict with a
+    # 'changed outs' key, e.g.,
+    # {
+    #     "data/jhtdb-transitional-bl/all-stats.h5.dvc": [
+    #         {
+    #             "changed outs": {
+    #                 "data/jhtdb-transitional-bl/all-stats.h5": "modified"
+    #             }
+    #         }
+    #     ]
+    # }
+    dvc_status = dvc.repo.status.status(dvc_repo)
+    # TODO: Structure this in an intelligent way
+    return {
+        "dvc": dvc_status,
+        "git": {"untracked": untracked_git_files, "diff": git_diff_files},
+    }
+
+
+@app.post("/projects/{owner_name}/{project_name}/open/vscode")
+def open_vscode(owner_name: str, project_name: str) -> int:
+    project = get_local_project(owner_name, project_name)
+    return os.system(f"code {project.wdir}")
+
+
+@app.get("/jupyter/servers")
+def get_jupyter_servers() -> list[calkit.jupyter.Server]:
+    return calkit.jupyter.get_servers()

calkit_python-0.0.1/calkit/tests/test_core.py

@@ -0,0 +1,8 @@
+"""Tests for the ``core`` module."""
+
+import calkit
+
+
+def test_find_project_dirs():
+    calkit.find_project_dirs()
+    assert calkit.find_project_dirs(relative=False)

calkit_python-0.0.1/calkit/tests/test_jupyter.py

@@ -0,0 +1,7 @@
+"""Tests for the ``jupyter`` module."""
+
+import calkit
+
+
+def test_get_servers():
+    calkit.jupyter.get_servers()

calkit_python-0.0.1/examples/cfd-study/README.md

@@ -0,0 +1,3 @@
+# Calkit CFD study example
+
+This example is not yet complete!

calkit_python-0.0.1/examples/cfd-study/calkit.yaml

@@ -0,0 +1,9 @@
+questions:
+  - What is the drag coefficient of this shape?
+environments:
+  - path: sim/Dockerfile
+    name: cfd
+    kind: docker
+  - path: environment.yml
+    name: processing
+    kind: conda

calkit_python-0.0.1/examples/cfd-study/config/simulations/runs.csv

@@ -0,0 +1,2 @@
+environment,wind_speed,wind_direction
+cfd,1.0,270.0

calkit_python-0.0.1/examples/cfd-study/notebook.ipynb

@@ -0,0 +1,37 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import calkit\n",
+    "\n",
+    "# Print out the plan of this study\n",
+    "plan = calkit.get_plan()\n",
+    "\n",
+    "# Describe this project\n",
+    "project = calkit.get_project()\n",
+    "\n",
+    "# What are the questions?\n",
+    "print(project.questions)\n",
+    "\n",
+    "# Get the status of the project, i.e., how many more simulations are there\n",
+    "# left to run\n",
+    "# is everything post-processed?\n",
+    "status = calkit.get_status()\n",
+    "\n",
+    "# By default this will run any non-finished simulations locally\n",
+    "calkit.run()"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

calkit_python-0.0.1/examples/ms-office/.gitignore

@@ -0,0 +1,6 @@
+# Keep MS office files out of Git, but still version them
+# maybe they are synced via Dropbox or something, but we still track if
+# they've changed?
+*.docx
+*.xls
+*.xlsx

calkit_python-0.0.1/examples/ms-office/README.md

@@ -0,0 +1,11 @@
+# MS Office user
+
+This example reflects the "non-hacker" researcher who uses Microsoft
+Office (or similar) for a lot of their work.
+Note that there is nothing wrong with this workflow,
+but it is inherently harder for collaboration and reproducibility,
+since version control for MS Office files is tougher.
+
+Our goal with this example is to allow someone who likes Word and Excel
+to keep using those tools, but to still help with organization
+and reproducibility.

calkit_python-0.0.1/examples/ms-office/calkit.yaml

@@ -0,0 +1,2 @@
+questions:
+  - Is it possible to use an office suite in a reproducible way?

calkit_python-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "calkit-python"
+dynamic = ["version"]
+authors = [
+  { name="Pete Bachant", email="petebachant@gmail.com" },
+]
+description = "Reproducibility made easy."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "dvc",
+    "fastapi",
+    "gitpython",
+    "keyring",
+    "pandas",
+    "polars",
+    "pydantic[email]",
+    "pydantic-settings",
+    "pyjwt",
+    "requests",
+    "typer",
+]
+
+[project.urls]
+Homepage = "https://github.com/calkit/calkit"
+Issues = "https://github.com/calkit/calkit/issues"
+
+[project.scripts]
+calkit = "calkit.cli:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["calkit"]
+
+[tool.hatch.version]
+path = "calkit/__init__.py"