calkit-python 0.19.1__tar.gz → 0.20.1__tar.gz

calkit_python-0.20.1/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.4.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.6.3"
+    hooks:
+      - id: ruff
+        args: [--exit-non-zero-on-fix, --config=pyproject.toml]
+        exclude: calkit
+      - id: ruff-format
+        args: [--config=pyproject.toml]
+        exclude: calkit
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.0.3"
+    hooks:
+      - id: prettier
+        exclude: calkit

calkit_python-0.20.1/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to Calkit
+
+Thank you for considering contributing to Calkit!
+We welcome contributions of all kinds, including code, documentation,
+bug reports, and feature suggestions.
+This guide will help you get started.
+
+## 🛠 How to contribute
+
+### 1. Find an issue to work on
+
+- Check the **[backlog](https://github.com/orgs/calkit/projects/1/views/1)**
+  for issues that are ready to be worked on.
+- Look for issues labeled `good first issue` if you're new.
+- If you have an idea, open a new issue and discuss it before coding.
+
+### 2. Set up your development environment
+
+1. [**Fork** the repository](https://github.com/calkit/calkit/fork).
+1. **Clone** your fork locally:
+   ```bash
+   git clone https://github.com/{your-username}/calkit.git
+   cd calkit
+   ```
+1. **Install system-level dependencies:**
+   - [Docker](https://docker.com)
+   - [Miniforge](https://conda-forge.org/download/)
+   - [uv](https://docs.astral.sh/uv/getting-started/installation/)
+1. **Run tests** to ensure everything is working:
+   ```bash
+   uv run pytest
+   ```
+
+### 3. Make your changes
+
+- Create a new branch:
+  ```bash
+  git checkout -b your-feature-name
+  ```
+- Check and fix code formatting:
+  ```bash
+  make format
+  ```
+- Commit your changes
+  (use the imperative mood and capitalize the first letter,
+  but don't use punctuation):
+  ```bash
+  git add .
+  git commit -m "Short description of your change"
+  ```
+- Push your branch:
+  ```bash
+  git push origin your-feature-name -u
+  ```
+
+### 4. Submit a pull request (PR)
+
+- Open a **Pull request** on GitHub.
+- Link the PR to the issue it resolves by adding "resolves #{issue number}"
+  to the description.
+- Wait for a review and make necessary changes.
+
+## 💡 Other ways to contribute
+
+- **Report bugs**: Open an issue with detailed reproduction steps.
+- **Improve documentation**: Help us make Calkit's docs better.
+- **Suggest features**: Share your ideas for improvements.
+
+## 🎉 Join the community
+
+- Participate in **[GitHub Discussions](https://github.com/calkit/discussions)**.
+- Join our [**Discord**](https://discord.gg/ubb7gAXc) for real-time collaboration.
+- Follow our updates on [**LinkedIn**](https://linkedin.com/company/calkit).
+
+We appreciate your help in making Calkit better! 🚀

calkit_python-0.20.1/Makefile

@@ -0,0 +1,36 @@
+.PHONY: help
+help: ## Show this help.
+	@uv run python -c "import re; \
+	[[print(f'\033[36m{m[0]:<20}\033[0m {m[1]}') for m in re.findall(r'^([a-zA-Z_-]+):.*?## (.*)$$', open(makefile).read(), re.M)] for makefile in ('$(MAKEFILE_LIST)').strip().split()]"
+
+.PHONY: install
+install: ## Create the project's virtual environment.
+	@echo "🚀 Creating virtual environment"
+	@uv sync
+
+.PHONY: format
+format: ## Automatically format files.
+	@echo "🚀 Linting code with pre-commit"
+	@uv run pre-commit run -a
+
+.PHONY: check
+check: format ## Run code quality tools.
+	@echo "🚀 Checking lock file consistency with 'pyproject.toml'"
+	@uv lock --locked
+	@echo "🚀 Static type checking with mypy"
+	@uv run mypy .
+	@echo "🚀 Checking for obsolete dependencies with deptry"
+	@uv run deptry .
+
+.PHONY: test
+test: ## Test the code with pytest.
+	@echo "🚀 Testing code with pytest"
+	@uv run pytest --cov --cov-config=pyproject.toml --cov-report=xml
+
+.PHONY: docs-test
+docs-test: ## Test if documentation can be built without warnings or errors.
+	@uv run mkdocs build -s
+
+.PHONY: docs
+docs: ## Build and serve the documentation.
+	@uv run mkdocs serve

{calkit_python-0.19.1 → calkit_python-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.19.1
+Version: 0.20.1
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -10,11 +10,12 @@ License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Requires-Dist: arithmeval
+Requires-Dist: bibtexparser
 Requires-Dist: checksumdir
 Requires-Dist: docx2pdf
-Requires-Dist: dvc
+Requires-Dist: dvc>=3.59.0
 Requires-Dist: eval-type-backport; python_version < '3.10'
 Requires-Dist: fastapi
 Requires-Dist: gitpython
@@ -27,17 +28,12 @@ Requires-Dist: pyjwt
 Requires-Dist: python-dotenv>=1
 Requires-Dist: pywin32; platform_system == 'Windows'
 Requires-Dist: requests
+Requires-Dist: tqdm>=4.67.1
 Requires-Dist: typer
 Requires-Dist: uvicorn
 Provides-Extra: data
-Requires-Dist: pandas; extra == 'data'
-Requires-Dist: polars; extra == 'data'
-Provides-Extra: dev
-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'
+Requires-Dist: pandas>=2.2.3; extra == 'data'
+Requires-Dist: polars>=1.18.0; extra == 'data'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -45,6 +41,19 @@ Description-Content-Type: text/markdown
     <img width="40%" src="docs/img/calkit-no-bg.png" alt="Calkit">
   </a>
 </p>
+<p align="center">
+  <a href="https://docs.calkit.org" target="_blank">
+    Documentation
+  </a>
+  |
+  <a href="https://docs.calkit.org/tutorials" target="_blank">
+    Tutorials
+  </a>
+  |
+  <a href="https://github.com/orgs/calkit/discussions" target="_blank">
+    Discussions
+  </a>
+</p>
 
 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
@@ -57,8 +66,6 @@ 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.
 
-To learn more, see the [documentation](https://docs.calkit.org).
-
 ## Installation
 
 To install Calkit, [Git](https://git-scm.com) and Python must be installed.
@@ -131,17 +138,10 @@ calkit save -am "Run pipeline"
 
 This will commit and push to both GitHub and the Calkit Cloud.
 
-## Tutorials
-
-- [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/)
+## Get involved
 
-See more in the [docs](https://docs.calkit.org).
+We welcome all kinds of contributions!
+See [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to get involved.
 
 ## Why does reproducibility matter?
 

{calkit_python-0.19.1 → calkit_python-0.20.1}/README.md

@@ -3,6 +3,19 @@
     <img width="40%" src="docs/img/calkit-no-bg.png" alt="Calkit">
   </a>
 </p>
+<p align="center">
+  <a href="https://docs.calkit.org" target="_blank">
+    Documentation
+  </a>
+  |
+  <a href="https://docs.calkit.org/tutorials" target="_blank">
+    Tutorials
+  </a>
+  |
+  <a href="https://github.com/orgs/calkit/discussions" target="_blank">
+    Discussions
+  </a>
+</p>
 
 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
@@ -15,8 +28,6 @@ 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.
 
-To learn more, see the [documentation](https://docs.calkit.org).
-
 ## Installation
 
 To install Calkit, [Git](https://git-scm.com) and Python must be installed.
@@ -89,17 +100,10 @@ calkit save -am "Run pipeline"
 
 This will commit and push to both GitHub and the Calkit Cloud.
 
-## Tutorials
-
-- [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/)
+## Get involved
 
-See more in the [docs](https://docs.calkit.org).
+We welcome all kinds of contributions!
+See [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to get involved.
 
 ## Why does reproducibility matter?
 

{calkit_python-0.19.1 → calkit_python-0.20.1}/calkit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.19.1"
+__version__ = "0.20.1"
 
 from .core import *
 from . import git
@@ -12,3 +12,6 @@ from . import templates
 from . import conda
 from . import calc
 from . import check
+from . import github
+from . import zenodo
+from . import releases

calkit_python-0.20.1/calkit/cli/import_.py

@@ -0,0 +1,247 @@
+"""CLI for importing objects."""
+
+from __future__ import annotations
+
+import base64
+import os
+import subprocess
+from typing import Annotated
+
+import git
+import requests
+import typer
+from tqdm import tqdm
+
+import calkit
+from calkit.cli import raise_error
+
+import_app = typer.Typer(no_args_is_help=True)
+
+
+@import_app.command(name="dataset")
+def import_dataset(
+    src_path: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "Location of dataset, including project owner and name, e.g., "
+                "someone/some-project/data/some-data.csv"
+            )
+        ),
+    ],
+    dest_path: Annotated[
+        str,
+        typer.Argument(help="Output path at which to save."),
+    ] = None,
+    filter_paths: Annotated[
+        list[str],
+        typer.Option(
+            "--filter-paths",
+            help="Filter paths in target dataset if it's a folder.",
+        ),
+    ] = None,
+    no_commit: Annotated[
+        bool,
+        typer.Option("--no-commit", help="Do not commit changes to repo."),
+    ] = False,
+    no_dvc_pull: Annotated[
+        bool,
+        typer.Option(
+            "--no-dvc-pull", help="Do not pull imported dataset with DVC."
+        ),
+    ] = False,
+    overwrite: Annotated[
+        bool,
+        typer.Option(
+            "--overwrite",
+            "-f",
+            help="Force adding the dataset even if it already exists.",
+        ),
+    ] = False,
+):
+    """Import a dataset.
+
+    Currently only supports datasets kept in DVC, not Git.
+    """
+    # Ensure we don't already have a dataset at this path
+    path_split = src_path.split("/")
+    owner_name = path_split[0]
+    project_name = path_split[1]
+    path = "/".join(path_split[2:])
+    if dest_path is None:
+        ds_dest_path = path
+    else:
+        ds_dest_path = dest_path
+    ck_info = calkit.load_calkit_info()
+    datasets = ck_info.get("datasets", [])
+    ds_paths = [ds["path"] for ds in datasets]
+    if not overwrite and ds_dest_path in ds_paths:
+        raise_error("A dataset already exists in this project at this path")
+    elif overwrite and ds_dest_path in ds_paths:
+        datasets = [ds for ds in datasets if ds["path"] != ds_dest_path]
+    repo = git.Repo()
+    # Obtain, save, and commit the .dvc file for the dataset, or if this is
+    # kept in Git, just download the files and commit them here
+    typer.echo("Fetching import info")
+    params = None
+    if filter_paths is not None:
+        params = {"filter_paths": filter_paths}
+    try:
+        resp = calkit.cloud.get(
+            f"/projects/{owner_name}/{project_name}/datasets/{path}",
+            params=params,
+        )
+    except Exception as e:
+        raise_error(f"Failed to fetch dataset info from cloud: {e}")
+    dvc_import, git_import = resp["dvc_import"], resp["git_import"]
+    if dest_path is not None:
+        typer.echo(f"Importing to destination path: {dest_path}")
+    if dvc_import is not None:
+        if dest_path is not None and len(dvc_import["outs"]) > 1:
+            raise_error(
+                "Cannot specify destination path when importing multiple "
+                "DVC files"
+            )
+        # Ensure we have a DVC remote corresponding to this project, and that we
+        # have a token set for that remote
+        typer.echo("Adding new DVC remote")
+        remote = calkit.dvc.add_external_remote(
+            owner_name=owner_name, project_name=project_name
+        )
+        repo.git.add(".dvc/config")
+        # Import this data with DVC
+        dvc_fpath = ds_dest_path + ".dvc"
+        dvc_dir = os.path.dirname(dvc_fpath)
+        os.makedirs(dvc_dir, exist_ok=True)
+        # Update paths in .dvc file so they are relative to the DVC file
+        if len(dvc_import["outs"]) > 1:
+            for n, out in enumerate(dvc_import["outs"]):
+                dvc_import["outs"][n]["path"] = os.path.relpath(
+                    out["path"], dvc_dir
+                )
+                dvc_import["outs"][n]["remote"] = remote["name"]
+        else:
+            dvc_import["outs"][0]["path"] = os.path.basename(
+                dvc_import["outs"][0]["path"]
+            )
+            dvc_import["outs"][0]["remote"] = remote["name"]
+        typer.echo("Saving .dvc file")
+        with open(dvc_fpath, "w") as f:
+            calkit.ryaml.dump(dvc_import, f)
+        repo.git.add(dvc_fpath)
+        # Add to .gitignore
+        typer.echo("Checking .gitignore")
+        if os.path.isfile(".gitignore"):
+            with open(".gitignore") as f:
+                gitignore = f.read()
+        else:
+            gitignore = ""
+        if ds_dest_path not in gitignore.split("\n"):
+            typer.echo(f"Adding {ds_dest_path} to .gitignore")
+            gitignore = gitignore.rstrip() + "\n" + ds_dest_path + "\n"
+            with open(".gitignore", "w") as f:
+                f.write(gitignore)
+            repo.git.add(".gitignore")
+    elif git_import is not None:
+        typer.echo("Fetching files directly since they're kept in Git")
+        files = git_import["files"]
+        if dest_path is not None:
+            os.makedirs(dest_path, exist_ok=True)
+        for f in tqdm(files):
+            # Fetch content from API
+            resp_i = calkit.cloud.get(
+                f"/projects/{owner_name}/{project_name}/contents/{f}"
+            )
+            content = resp_i.get("content")
+            fname = os.path.basename(f)
+            dirname = os.path.dirname(f) if dest_path is None else dest_path
+            os.makedirs(dirname, exist_ok=True)
+            out_path = os.path.join(dirname, fname)
+            if content is not None:
+                # Decode base64 content and save locally
+                with open(out_path, "wb") as f:
+                    f.write(base64.b64decode(content))
+            else:
+                url = resp_i.get("url")
+                if url is None:
+                    raise_error(f"Could not fetch {f}")
+                # Download from URL
+                resp_dl = requests.get(url, stream=True)
+                try:
+                    resp_dl.raise_for_status()
+                except Exception as e:
+                    raise_error(f"Failed to download {f} from {url}: {e}")
+                with open(out_path, "wb") as f:
+                    for chunk in resp_dl.iter_content(chunk_size=8192):
+                        f.write(chunk)
+            repo.git.add(out_path)
+    else:
+        raise_error("Could not fetch import info from Calkit Cloud")
+    # Add to datasets in calkit.yaml
+    typer.echo("Adding dataset to calkit.yaml")
+    new_ds = calkit.models.ImportedDataset(
+        path=ds_dest_path,
+        title=resp.get("title"),
+        description=resp.get("description"),
+        stage=None,
+        imported_from=calkit.models._ImportedFromProject(
+            project=f"{owner_name}/{project_name}",
+            path=path,
+            git_rev=None,  # TODO?
+            filter_paths=filter_paths,
+        ),
+    )
+    datasets.append(new_ds.model_dump())
+    ck_info["datasets"] = datasets
+    with open("calkit.yaml", "w") as f:
+        calkit.ryaml.dump(ck_info, f)
+    repo.git.add("calkit.yaml")
+    if not no_commit:
+        # Commit any necessary changes
+        typer.echo("Committing changes")
+        repo.git.commit(["-m", f"Import dataset {src_path}"])
+    if not no_dvc_pull and dvc_import is not None:
+        # Run dvc pull
+        typer.echo("Running dvc pull")
+        subprocess.call(["dvc", "pull", dvc_fpath])
+
+
+@import_app.command(name="environment")
+def import_environment(
+    src_path: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "Environment location and name, e.g., "
+                "someone/some-project:env-name. If not present, the Calkit "
+                "Cloud will be queried."
+            )
+        ),
+    ],
+    dest_path: Annotated[
+        str,
+        typer.Option("--path", help="Output path at which to save."),
+    ] = None,
+    dest_name: Annotated[
+        str,
+        typer.Option(
+            "--name", "-n", help="Name to use in the destination project."
+        ),
+    ] = None,
+    overwrite: Annotated[
+        bool,
+        typer.Option(
+            "--overwrite",
+            "-f",
+            help="Force adding the dataset even if it already exists.",
+        ),
+    ] = False,
+) -> None:
+    project, env_name = src_path.split(":")
+    if os.path.isdir(project):
+        cloud = False
+        typer.echo("Importing from local project directory")
+    else:
+        cloud = True
+        typer.echo("Importing from Cloud project")
+    raise_error("Not yet implemented")  # TODO