calkit-python 0.26.5__tar.gz → 0.26.6__tar.gz

{calkit_python-0.26.5 → calkit_python-0.26.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.26.5
+Version: 0.26.6
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -55,21 +55,33 @@ Description-Content-Type: text/markdown
   </a>
 </p>
 
-Calkit's mission is to make every scientific study reproducible.
-That is,
-it should be possible to go from raw data to research article
-by "pressing a single button"
-([Claerbout and Karrenbach (1992)](https://doi.org/10.1190/1.1822162)).
+Calkit makes it easy to create
+["single button"](https://doi.org/10.1190/1.1822162)
+reproducible research projects.
+
+Instead of a loosely related collection of files
+and manual instructions,
+turn your project into a version-controlled,
+self-contained "calculation kit,"
+tying together all phases or stages of the project:
+data collection, analysis, visualization, and writing,
+each of which can make use of the latest and greatest computational
+tools and languages.
+In other words, you, your collaborators, and readers will be able to go
+from raw data to research article with a single command,
+improving efficiency via faster iteration cycle time,
+reducing the likelihood of mistakes,
+and allowing others to more effectively build upon your work.
 
 Calkit makes this level of automation possible without extensive software
 engineering expertise by providing a project framework and toolset that unifies
-and simplifies the use of enabling technologies like Git,
+and simplifies the use of powerful enabling technologies like Git,
 DVC, Conda, Docker, and more,
 while guiding users away from common reproducibility pitfalls.
 
 ## Features
 
-- A declarative pipeline that forces users to define an environment
+- A declarative pipeline that guides users to define an environment
   for every stage, so long lists of instructions in a README and
   "but it works on my machine" are things of the past.
 - A CLI to run the project's pipeline to verify it's reproducible,
@@ -136,6 +148,64 @@ calkit config set token ${YOUR_TOKEN_HERE}
 
 ## Quickstart
 
+### From an existing project
+
+If you want to use Calkit with an existing project,
+navigate into its working directory and run:
+
+```sh
+calkit new project --public --cloud .
+```
+
+Note that the `--public` and `--cloud` options can be omitted,
+but you'll need to configure your own DVC remote or use Git to store
+pipeline outputs.
+
+Next, create your [environment(s)](https://docs.calkit.org/environments).
+In this example, imagine we have a `requirements.txt` file we want to use to
+define a uv virtual environment, or venv:
+
+```sh
+calkit new uv-venv --name main --path requirements.txt --python 3.13
+```
+
+If you're using Conda for environment management,
+e.g., with an `environment.yml` file,
+you can use the `calkit new conda-env` command.
+
+Next, we can start building our [pipeline](https://docs.calkit.org/pipeline).
+Let's say we have a Jupyter notebook called `collect-data.ipynb`
+that produces raw data at `data/raw.h5`.
+We can add a pipeline stage to run this notebook in the `main` environment
+we just created with:
+
+```sh
+calkit new jupyter-notebook-stage \
+    --name collect-data \
+    --environment main \
+    --notebook-path collect-data.ipynb \
+    --output data/raw.h5
+```
+
+We can then run the pipeline with:
+
+```sh
+calkit run
+```
+
+and save and back up our results with:
+
+```sh
+calkit save -am "Run pipeline"
+```
+
+After that,
+you can add more environments, pipeline stages,
+[start a publication with LaTeX](https://docs.calkit.org/tutorials/adding-latex-pub-docker/),
+or [link a publication with Overleaf](https://docs.calkit.org/overleaf/).
+
+### Fresh from a Calkit project template
+
 After installing Calkit and setting your token as described above, run:
 
 ```sh
@@ -157,7 +227,7 @@ cd calkit-project-1
 calkit run
 ```
 
-This will reproduce the project's pipeline.
+This will run the project's pipeline.
 Next, you can start adding stages to the pipeline,
 modifying the Python environments and scripts,
 and editing the paper.

{calkit_python-0.26.5 → calkit_python-0.26.6}/README.md

@@ -17,21 +17,33 @@
   </a>
 </p>
 
-Calkit's mission is to make every scientific study reproducible.
-That is,
-it should be possible to go from raw data to research article
-by "pressing a single button"
-([Claerbout and Karrenbach (1992)](https://doi.org/10.1190/1.1822162)).
+Calkit makes it easy to create
+["single button"](https://doi.org/10.1190/1.1822162)
+reproducible research projects.
+
+Instead of a loosely related collection of files
+and manual instructions,
+turn your project into a version-controlled,
+self-contained "calculation kit,"
+tying together all phases or stages of the project:
+data collection, analysis, visualization, and writing,
+each of which can make use of the latest and greatest computational
+tools and languages.
+In other words, you, your collaborators, and readers will be able to go
+from raw data to research article with a single command,
+improving efficiency via faster iteration cycle time,
+reducing the likelihood of mistakes,
+and allowing others to more effectively build upon your work.
 
 Calkit makes this level of automation possible without extensive software
 engineering expertise by providing a project framework and toolset that unifies
-and simplifies the use of enabling technologies like Git,
+and simplifies the use of powerful enabling technologies like Git,
 DVC, Conda, Docker, and more,
 while guiding users away from common reproducibility pitfalls.
 
 ## Features
 
-- A declarative pipeline that forces users to define an environment
+- A declarative pipeline that guides users to define an environment
   for every stage, so long lists of instructions in a README and
   "but it works on my machine" are things of the past.
 - A CLI to run the project's pipeline to verify it's reproducible,
@@ -98,6 +110,64 @@ calkit config set token ${YOUR_TOKEN_HERE}
 
 ## Quickstart
 
+### From an existing project
+
+If you want to use Calkit with an existing project,
+navigate into its working directory and run:
+
+```sh
+calkit new project --public --cloud .
+```
+
+Note that the `--public` and `--cloud` options can be omitted,
+but you'll need to configure your own DVC remote or use Git to store
+pipeline outputs.
+
+Next, create your [environment(s)](https://docs.calkit.org/environments).
+In this example, imagine we have a `requirements.txt` file we want to use to
+define a uv virtual environment, or venv:
+
+```sh
+calkit new uv-venv --name main --path requirements.txt --python 3.13
+```
+
+If you're using Conda for environment management,
+e.g., with an `environment.yml` file,
+you can use the `calkit new conda-env` command.
+
+Next, we can start building our [pipeline](https://docs.calkit.org/pipeline).
+Let's say we have a Jupyter notebook called `collect-data.ipynb`
+that produces raw data at `data/raw.h5`.
+We can add a pipeline stage to run this notebook in the `main` environment
+we just created with:
+
+```sh
+calkit new jupyter-notebook-stage \
+    --name collect-data \
+    --environment main \
+    --notebook-path collect-data.ipynb \
+    --output data/raw.h5
+```
+
+We can then run the pipeline with:
+
+```sh
+calkit run
+```
+
+and save and back up our results with:
+
+```sh
+calkit save -am "Run pipeline"
+```
+
+After that,
+you can add more environments, pipeline stages,
+[start a publication with LaTeX](https://docs.calkit.org/tutorials/adding-latex-pub-docker/),
+or [link a publication with Overleaf](https://docs.calkit.org/overleaf/).
+
+### Fresh from a Calkit project template
+
 After installing Calkit and setting your token as described above, run:
 
 ```sh
@@ -119,7 +189,7 @@ cd calkit-project-1
 calkit run
 ```
 
-This will reproduce the project's pipeline.
+This will run the project's pipeline.
 Next, you can start adding stages to the pipeline,
 modifying the Python environments and scripts,
 and editing the paper.

{calkit_python-0.26.5 → calkit_python-0.26.6}/calkit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.26.5"
+__version__ = "0.26.6"
 
 from .core import *  # noqa: F403, I001
 from . import git  # noqa: F401

{calkit_python-0.26.5 → calkit_python-0.26.6}/calkit/cli/new.py

@@ -1079,15 +1079,15 @@ def new_publication(
 
 @new_app.command("conda-env")
 def new_conda_env(
-    packages: Annotated[
-        list[str],
-        typer.Argument(help="Packages to include in the environment."),
-    ],
     name: Annotated[
         str, typer.Option("--name", "-n", help="Environment name.")
     ],
+    packages: Annotated[
+        list[str] | None,
+        typer.Argument(help="Packages to include in the environment."),
+    ] = None,
     conda_name: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--conda-name",
             help=(
@@ -1105,10 +1105,11 @@ def new_conda_env(
         list[str], typer.Option("--pip", help="Packages to install with pip.")
     ] = [],
     prefix: Annotated[
-        str, typer.Option("--prefix", help="Prefix for environment location.")
+        str | None,
+        typer.Option("--prefix", help="Prefix for environment location."),
     ] = None,
     description: Annotated[
-        str, typer.Option("--description", help="Description.")
+        str | None, typer.Option("--description", help="Description.")
     ] = None,
     overwrite: Annotated[
         bool,
@@ -1130,8 +1131,10 @@ def new_conda_env(
     ] = False,
 ):
     """Create a new Conda environment."""
-    if os.path.isfile(path) and not overwrite:
+    if packages is not None and os.path.isfile(path) and not overwrite:
         raise_error("Output path already exists (use -f to overwrite)")
+    elif packages is None and not os.path.isfile(path):
+        raise_error("Packages must be provided if path doesn't exist")
     repo = git.Repo()
     # Add environment to Calkit info
     ck_info = calkit.load_calkit_info()
@@ -1150,21 +1153,34 @@ def new_conda_env(
         if project_name is None:
             project_name = os.path.basename(os.getcwd())
         conda_name = calkit.to_kebab_case(project_name) + "-" + name
-    # Write environment to path
-    _check_path_dir(path)
-    conda_env = dict(
-        name=conda_name, channels=["conda-forge"], dependencies=packages
-    )
-    if prefix is not None:
-        from calkit.cli.main import ignore
+    if packages is not None:
+        assert isinstance(packages, list)
+        # Write environment to path
+        _check_path_dir(path)
+        conda_env = dict(
+            name=conda_name, channels=["conda-forge"], dependencies=packages
+        )
+        if prefix is not None:
+            from calkit.cli.main import ignore
 
-        conda_env["prefix"] = prefix
-        ignore(prefix, no_commit=True)
-        repo.git.add(".gitignore")
-    if pip_packages:
-        conda_env["dependencies"].append(dict(pip=pip_packages))
-    with open(path, "w") as f:
-        ryaml.dump(conda_env, f)
+            conda_env["prefix"] = prefix
+            ignore(prefix, no_commit=True)
+            repo.git.add(".gitignore")
+        if pip_packages:
+            conda_env["dependencies"].append(dict(pip=pip_packages))
+        with open(path, "w") as f:
+            ryaml.dump(conda_env, f)
+    elif packages is None and os.path.isfile(path):
+        with open(path) as f:
+            conda_env: dict = ryaml.load(f)
+        # Remove prefix
+        conda_env.pop("prefix", None)
+        if prefix is not None:
+            conda_env["prefix"] = prefix
+        # Rename so we can track it more uniquely
+        conda_env["name"] = conda_name
+        with open(path, "w") as f:
+            ryaml.dump(conda_env, f)
     repo.git.add(path)
     typer.echo("Adding environment to calkit.yaml")
     env = dict(path=path, kind="conda")
@@ -1187,13 +1203,13 @@ def new_conda_env(
 
 @new_app.command("uv-venv")
 def new_uv_venv(
-    packages: Annotated[
-        list[str],
-        typer.Argument(help="Packages to include in the environment."),
-    ],
     name: Annotated[
         str, typer.Option("--name", "-n", help="Environment name.")
     ],
+    packages: Annotated[
+        list[str] | None,
+        typer.Argument(help="Packages to include in the environment."),
+    ] = None,
     path: Annotated[
         str, typer.Option("--path", help="Path for requirements file.")
     ] = "requirements.txt",
@@ -1201,10 +1217,10 @@ def new_uv_venv(
         str, typer.Option("--prefix", help="Prefix for environment location.")
     ] = ".venv",
     python_version: Annotated[
-        str, typer.Option("--python", "-p", help="Python version.")
-    ] = None,
+        str | None, typer.Option("--python", "-p", help="Python version.")
+    ] = "3.13",
     description: Annotated[
-        str, typer.Option("--description", help="Description.")
+        str | None, typer.Option("--description", help="Description.")
     ] = None,
     overwrite: Annotated[
         bool,
@@ -1226,8 +1242,10 @@ def new_uv_venv(
     ] = False,
 ):
     """Create a new uv virtual environment."""
-    if os.path.isfile(path) and not overwrite:
+    if os.path.isfile(path) and packages and not overwrite:
         raise_error("Output path already exists (use -f to overwrite)")
+    elif packages is None and not os.path.isfile(path):
+        raise_error("If path doesn't exist, packages must be specified")
     repo = git.Repo()
     # Add environment to Calkit info
     ck_info = calkit.load_calkit_info()
@@ -1249,11 +1267,12 @@ def new_uv_venv(
                     f"Environment '{env_name}' already exists with "
                     f"prefix '{prefix}'"
                 )
-    packages_txt = "\n".join(packages)
-    # Write environment to path
-    _check_path_dir(path)
-    with open(path, "w") as f:
-        f.write(packages_txt)
+    if packages is not None:
+        packages_txt = "\n".join(packages)
+        # Write environment to path
+        _check_path_dir(path)
+        with open(path, "w") as f:
+            f.write(packages_txt)
     repo.git.add(path)
     typer.echo("Adding environment to calkit.yaml")
     env = dict(path=path, kind="uv-venv", prefix=prefix)

{calkit_python-0.26.5 → calkit_python-0.26.6}/calkit/tests/cli/test_new.py

@@ -212,6 +212,37 @@ def test_new_uv_venv(tmp_dir):
     assert env.kind == "uv-venv"
 
 
+def test_new_conda_env(tmp_dir):
+    with open("environment.yml", "w") as f:
+        calkit.ryaml.dump(
+            {
+                "dependencies": ["python", "requests"],
+                "name": "whatever",
+                "channels": ["conda-forge"],
+            },
+            f,
+        )
+    subprocess.check_call(
+        ["calkit", "new", "project", ".", "--name", "test", "--title", "Test"]
+    )
+    subprocess.check_call(
+        [
+            "calkit",
+            "new",
+            "conda-env",
+            "--path",
+            "environment.yml",
+            "--name",
+            "e1",
+            "--no-check",
+        ]
+    )
+    with open("environment.yml") as f:
+        env = calkit.ryaml.load(f)
+    assert env["name"] == "test-e1"
+    assert env["dependencies"] == ["python", "requests"]
+
+
 def test_new_project(tmp_dir):
     subprocess.check_call(
         ["calkit", "new", "project", ".", "--title", "My new project"]

{calkit_python-0.26.5 → calkit_python-0.26.6}/docs/help.md

@@ -7,9 +7,8 @@ To get in touch with the community,
 check out the
 [discussion forum](https://github.com/orgs/calkit/discussions)
 or the
-[Discord server](https://discord.gg/QHEDz7G6).
+[Discord server](https://discord.gg/ryDkGarc).
 
 If you want to get in touch directly,
 feel free to
-[send an email](mailto:help@calkit.io) or
-[schedule a video chat](https://calendar.app.google/fGDwYrqJm3diKegr8).
+[send an email](mailto:help@calkit.io).

{calkit_python-0.26.5 → calkit_python-0.26.6}/docs/index.md

@@ -1,27 +1,29 @@
 # Home
 
-Calkit's mission is to make every scientific study reproducible.
-That is,
-it should be possible to go from raw data to research article
-by "pressing a single button"
-([Claerbout and Karrenbach (1992)](https://doi.org/10.1190/1.1822162)).
+Calkit makes it easy to create
+["single button"](https://doi.org/10.1190/1.1822162)
+reproducible research projects.
+
+Instead of a loosely related collection of files
+and manual instructions,
+turn your project into a version-controlled,
+self-contained "calculation kit,"
+tying together all phases or stages of the project:
+data collection, analysis, visualization, and writing,
+each of which can make use of the latest and greatest computational
+tools and languages.
+In other words, you, your collaborators, and readers will be able to go
+from raw data to research article with a single command,
+improving efficiency via faster iteration cycle time,
+reducing the likelihood of mistakes,
+and allowing others to more effectively build upon your work.
 
 Calkit makes this level of automation possible without extensive software
 engineering expertise by providing a project framework and toolset that unifies
-and simplifies the use of enabling technologies like Git,
+and simplifies the use of powerful enabling technologies like Git,
 DVC, Conda, Docker, and more,
 while guiding users away from common reproducibility pitfalls.
 
-When your project is reproducible,
-you'll be able to iterate more quickly and more often,
-easily onboard collaborators,
-make fewer mistakes,
-and feel confident sharing all of your project materials
-with your research articles,
-because you'll know the code will actually run!
-This will allow others to reuse parts of your project in their own research,
-accelerating the pace of discovery.
-
 ## Features
 
 - A declarative pipeline that forces users to define an environment

{calkit_python-0.26.5 → calkit_python-0.26.6}/docs/installation.md

@@ -19,6 +19,12 @@ Alternatively, but less ideally, you can install with your system Python:
 pip install calkit-python
 ```
 
+Next,
+[connect to a Calkit Hub](cloud-integration.md)
+for collaboration and backup.
+
+## Calkit Assistant
+
 For Windows users, the
 [Calkit Assistant](https://github.com/calkit/calkit-assistant)
 app is the easiest way to get everything set up and ready to work in

calkit_python-0.26.6/docs/quickstart.md

@@ -0,0 +1,94 @@
+# Quickstart
+
+## From an existing project
+
+If you want to use Calkit with an existing project,
+navigate into its working directory and run:
+
+```sh
+calkit new project --public --cloud .
+```
+
+Note that the `--public` and `--cloud` options can be omitted,
+but then you'll need to configure your own DVC remote or use Git to store
+pipeline outputs.
+
+Next, create your [environment(s)](environments.md).
+In this example, imagine we have a `requirements.txt` file we want to use to
+define a uv virtual environment, or venv:
+
+```sh
+calkit new uv-venv --name main --path requirements.txt --python 3.13
+```
+
+If you're using Conda for environment management,
+e.g., with an `environment.yml` file,
+you can use the `calkit new conda-env` command.
+
+Next, we can start building our [pipeline](pipeline.md).
+Let's say we have a Jupyter notebook called `collect-data.ipynb`
+that produces raw data at `data/raw.h5`.
+We can add a pipeline stage to run this notebook in the `main` environment
+we just created with:
+
+```sh
+calkit new jupyter-notebook-stage \
+    --name collect-data \
+    --environment main \
+    --notebook-path collect-data.ipynb \
+    --output data/raw.h5
+```
+
+We can then run the pipeline with:
+
+```sh
+calkit run
+```
+
+and save and back up our results with:
+
+```sh
+calkit save -am "Run pipeline"
+```
+
+After that,
+you can add more environments, pipeline stages,
+[start a publication with LaTeX](tutorials/adding-latex-pub-docker.md),
+or [link a publication with Overleaf](overleaf.md).
+
+## Fresh from a Calkit project template
+
+After installing Calkit and setting your token as described above, run:
+
+```sh
+calkit new project calkit-project-1 \
+    --title "My first Calkit project" \
+    --template calkit/example-basic \
+    --cloud \
+    --public
+```
+
+This will create a new project from the
+[`calkit/example-basic`](https://github.com/calkit/example-basic)
+template,
+creating it in the cloud and cloning to `calkit-project-1`.
+You should now be able to run:
+
+```sh
+cd calkit-project-1
+calkit run
+```
+
+This will run the project's pipeline.
+Next, you can start adding stages to the pipeline,
+modifying the Python environments and scripts,
+and editing the paper.
+All will be kept in sync with the `calkit run` command.
+
+To back up all of your work, execute:
+
+```sh
+calkit save -am "Run pipeline"
+```
+
+This will commit and push to both GitHub and the Calkit Cloud.

{calkit_python-0.26.5 → calkit_python-0.26.6}/mkdocs.yml

@@ -35,8 +35,8 @@ theme:
         name: Switch to system preference
 nav:
   - Home: index.md
-  - Help and support: help.md
   - Installation: installation.md
+  - Quickstart: quickstart.md
   - Cloud integration: cloud-integration.md
   - Version control: version-control.md
   - The calkit.yaml file: calkit-yaml.md
@@ -68,6 +68,7 @@ nav:
       - tutorials/office.md
       - tutorials/matlab.md
   - CLI reference: cli-reference.md
+  - Help and support: help.md
 markdown_extensions:
   - admonition
   - attr_list