calkit-python 0.32.8__tar.gz → 0.32.10__tar.gz

calkit_python-0.32.10/CODE_OF_CONDUCT.md

@@ -0,0 +1,125 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body size,
+visible or invisible disability, ethnicity, sex characteristics, gender identity
+and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and
+  learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive, or
+harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are not
+aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed representative
+at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at info@calkit.org.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+Community Impact: Use of inappropriate language or other behavior deemed unprofessional or
+unwelcome in the community.
+
+Consequence: A private, written warning from community leaders, providing clarity around
+the nature of the violation and an explanation of why the behavior was
+inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+Community Impact: A violation through a single incident or series of actions.
+
+Consequence: A warning with consequences for continued behavior. No interaction with the
+people involved, including unsolicited interaction with those enforcing the Code
+of Conduct, for a specified period of time. This includes avoiding interactions
+in community spaces as well as external channels like social media. Violating
+these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+Community Impact: A serious violation of community standards, including sustained inappropriate
+behavior.
+
+Consequence: A temporary ban from any sort of interaction or public communication with the
+community for a specified period of time. No public or private interaction with
+the people involved, including unsolicited interaction with those enforcing the Code of Conduct,
+is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+Community Impact: Demonstrating a pattern of violation of community standards, including
+sustained inappropriate behavior, harassment of an individual, or aggression toward or
+disparagement of classes of individuals.
+
+Consequence: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1,
+available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

{calkit_python-0.32.8 → calkit_python-0.32.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.32.8
+Version: 0.32.10
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -15,14 +15,15 @@ Requires-Dist: arithmeval
 Requires-Dist: bibtexparser
 Requires-Dist: checksumdir
 Requires-Dist: docx2pdf
-Requires-Dist: dvc==3.64.0
+Requires-Dist: dvc==3.64.2
 Requires-Dist: fastapi
 Requires-Dist: gitpython
-Requires-Dist: json2latex>=0.0.2
+Requires-Dist: json2latex>=0.0.3
 Requires-Dist: jupyterlab>=4.4.5
 Requires-Dist: keyring
 Requires-Dist: nbconvert
 Requires-Dist: papermill>=2.6.0
+Requires-Dist: pathspec<1.0.0
 Requires-Dist: pillow
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: pydantic-settings

{calkit_python-0.32.8 → calkit_python-0.32.10}/calkit/__init__.py

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

{calkit_python-0.32.8 → calkit_python-0.32.10}/calkit/models/pipeline.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import Any, Literal
 
 from pydantic import (
+    AfterValidator,
     BaseModel,
     ConfigDict,
     Discriminator,
@@ -30,6 +31,32 @@ from calkit.notebooks import (
 )
 
 
+def _check_path_relative_and_child_of_cwd(s: str) -> str:
+    p = Path(s)
+    # Enforce that the path is relative
+    if p.is_absolute():
+        raise ValueError(f"Path must be relative: {p}")
+    # Enforce that the path is a child of the (resolved) CWD
+    cwd = Path.cwd().resolve()
+    # Resolve the path relative to the resolved CWD to get a full path for
+    # comparison
+    absolute_path = p.resolve(strict=False)
+    # Check if the absolute path starts with the resolved CWD, ensuring it's a
+    # child
+    try:
+        absolute_path.relative_to(cwd)
+    except ValueError:
+        raise ValueError(
+            f"Path is not a child of the current working directory: {p}"
+        )
+    return p.as_posix()
+
+
+RelativeChildPathString = Annotated[
+    str, AfterValidator(_check_path_relative_and_child_of_cwd)
+]
+
+
 class StageIteration(BaseModel):
     """A model for the ``iterate_over`` key in a stage definition.
 
@@ -194,7 +221,7 @@ class Stage(BaseModel):
 
 class PythonScriptStage(Stage):
     kind: Literal["python-script"] = "python-script"
-    script_path: str
+    script_path: RelativeChildPathString
     args: list[str] = []
 
     @property
@@ -379,7 +406,8 @@ class JsonToLatexStage(Stage):
 
 class MatlabScriptStage(Stage):
     kind: Literal["matlab-script"]
-    script_path: str
+    script_path: RelativeChildPathString
+    matlab_path: RelativeChildPathString | None = None
 
     @property
     def dvc_deps(self) -> list[str]:
@@ -390,7 +418,11 @@ class MatlabScriptStage(Stage):
         cmd = self.xenv_cmd
         if self.environment == "_system":
             cmd += "matlab -batch"
-        cmd += f" \"run('{self.script_path}');\""
+        matlab_cmd = ""
+        if self.matlab_path is not None:
+            matlab_cmd += f"addpath(genpath('{self.matlab_path}')); "
+        matlab_cmd += f"run('{self.script_path}');"
+        cmd += f' "{matlab_cmd}"'
         return cmd
 
 
@@ -428,7 +460,7 @@ class ShellCommandStage(Stage):
 
 class ShellScriptStage(Stage):
     kind: Literal["shell-script"]
-    script_path: str
+    script_path: RelativeChildPathString
     args: list[str] = []
     shell: Literal["sh", "bash", "zsh"] = "bash"
 
@@ -460,7 +492,7 @@ class DockerCommandStage(Stage):
 
 class RScriptStage(Stage):
     kind: Literal["r-script"]
-    script_path: str
+    script_path: RelativeChildPathString
     args: list[str] = []
 
     @property
@@ -479,7 +511,7 @@ class RScriptStage(Stage):
 
 class JuliaScriptStage(Stage):
     kind: Literal["julia-script"] = "julia-script"
-    script_path: str
+    script_path: RelativeChildPathString
     args: list[str] = []
 
     @property
@@ -508,7 +540,7 @@ class JuliaCommandStage(Stage):
 
 class SBatchStage(Stage):
     kind: Literal["sbatch"] = "sbatch"
-    script_path: str
+    script_path: RelativeChildPathString
     args: list[str] = []
     sbatch_options: list[str] = []
     log_storage: Literal["git", "dvc"] | None = "git"

{calkit_python-0.32.8 → calkit_python-0.32.10}/calkit/tests/models/test_pipeline.py

@@ -11,6 +11,7 @@ from calkit.models.pipeline import (
     LatexStage,
     MapPathsStage,
     MatlabCommandStage,
+    MatlabScriptStage,
     PythonScriptStage,
     SBatchStage,
     StageIteration,
@@ -186,6 +187,39 @@ def test_matlabcommandstage():
     assert sd["cmd"] == 'matlab -batch "disp(\\"Hello, MATLAB!\\");"'
 
 
+def test_matlabscriptstage():
+    s = MatlabScriptStage(
+        name="a",
+        kind="matlab-script",
+        environment="_system",
+        script_path="scripts/my_script.m",
+        matlab_path="scripts",
+    )
+    sd = s.to_dvc()
+    print(sd)
+    assert (
+        sd["cmd"]
+        == "matlab -batch \"addpath(genpath('scripts')); run('scripts/my_script.m');\""
+    )
+    with pytest.raises(ValidationError):
+        s = MatlabScriptStage(
+            name="b",
+            kind="matlab-script",
+            environment="_system",
+            script_path="scripts/my_script.m",
+            matlab_path="/some/abs/path",
+        )
+    # Ensure we can't use a relative path outside the project folder
+    with pytest.raises(ValidationError):
+        s = MatlabScriptStage(
+            name="b",
+            kind="matlab-script",
+            environment="_system",
+            script_path="scripts/my_script.m",
+            matlab_path="../up/a/dir",
+        )
+
+
 def test_sbatchstage():
     s = SBatchStage(
         name="job1",

{calkit_python-0.32.8 → calkit_python-0.32.10}/docs/calkit-yaml.md

@@ -3,8 +3,8 @@
 The `calkit.yaml` file serves as a small "database"
 for the project's important metadata, which includes its:
 
-- Global or system-level [dependencies](dependencies.md)
-  (applications, libraries, environmental variables)
+- Global or system-level [dependencies](dependencies.md) or requirements
+  (applications, environmental variables, or other configuration steps)
 - Questions the project seeks to answer
 - [Environments](environments.md)
 - [The pipeline](pipeline/index.md)

calkit_python-0.32.10/docs/governance.md

@@ -0,0 +1,125 @@
+# Governance
+
+Calkit is a free, open-source, and openly-governed project.
+All [issues and ideas](https://github.com/calkit/calkit/issues)
+are discussed publicly and are open to input from anyone.
+Because the project is still early-stage,
+the [founder](https://github.com/petebachant)
+serves as the primary maintainer and decision maker.
+As the number of
+[contributors](https://github.com/calkit/calkit/graphs/contributors) grows,
+maintainers will be added to share review and release duties.
+The contributor's guide can be found
+[here](https://github.com/calkit/calkit/blob/main/CONTRIBUTING.md)
+and our code of conduct can be found
+[here](https://github.com/calkit/calkit/blob/main/CODE_OF_CONDUCT.md).
+
+## Vision
+
+We envision a future where nearly every research article is delivered as part
+of a [single-button](https://petebachant.me/single-button/)
+reproducible
+[compendium](https://book.the-turing-way.org/reproducible-research/compendia/)
+(or ["repro pack"](https://lorenabarba.com/blog/how-repro-packs-can-save-your-future-self/)).
+That is, all primary artifacts like source code and raw data are available,
+and all secondary artifacts like figures and article PDFs
+can be produced with a single command.
+
+![The single-button reproducible future.](img/calkit-fragmentation-compendium.png)
+
+<!-- Source: https://docs.google.com/drawings/d/1vAjGju_MOLD40oMXBTvIQfG-eZt9SRhEW9SDBzUt6xI/edit -->
+
+We believe that this will increase the pace of collective knowledge creation
+by enabling faster:
+
+1. **Discovery of errors.**
+   Computational methods will be fully described and auditable.
+2. **Replication.**
+   Studies can be replicated by simply replacing the raw input data and
+   rerunning the pipeline.
+3. **Extension.**
+   Innovation in science largely occurs at the level of
+   hypotheses and conceptual models,
+   not in mundane pipeline construction and execution.
+   There is also a network effect as more types of single-button projects are
+   published,
+   making it easier to find something similar to a desired workflow to start
+   from and adapt to new questions.
+
+### The status quo
+
+The figure below from the PLOS Open Science Indicators dataset
+shows how far away we are from our target.
+Code sharing rates are only ~10%,
+and of what is shared, it's reasonable to assume
+[only ~10% of that code will even run](https://doi.org/10.1093/bib/bbad375),
+never mind be included in a complete, automated pipeline.
+
+![Code sharing rates from PLOS OSI 2024.](img/plos-osi-code-2024-03.png){ style="max-width: 500px; width: auto; height: auto;" }
+/// caption
+Code sharing rates from
+[PLOS Open Science Indicators](https://theplosblog.plos.org/2024/03/six-years-of-open-science-indicators-data/).
+///
+
+## Strategy
+
+We believe one major hurdle preventing researchers from working reproducibly is
+the expectation that they become software engineering experts,
+choose and integrate multiple tools,
+and assemble a custom workflow.
+We want to provide a vertically-integrated, purpose-built,
+and user-friendly project format and toolset that reduces the required
+expertise and decision fatigue.
+That is not to say that policy, education, and support are not part of the
+solution—they certainly are—but we are focused on improving
+tooling and infrastructure.
+
+- **Path of least resistance:**
+  Make it faster to work in a clean,
+  reproducible way than it is to work in an ad-hoc, disorganized way.
+- **Intuitive tooling:**
+  Simplify the "hard parts" of modern scientific computing:
+  caching, version control, and environment management.
+- **Bridging the gap:**
+  Create a natural transition from interactive discovery (notebooks/shells)
+  to automated batch pipelines.
+- **Builder's pride:**
+  Enable researchers to take pride in what they create so
+  they will be more likely to share their projects openly.
+
+## Objective and key results (OKRs)
+
+### 2026-Q1
+
+1.  Objective: Empower researchers to create and share single-button
+    reproducible research projects.
+    1.  Key result: 5 researchers (excluding direct collaborators) create
+        single-button reproducible research projects this quarter.
+    2.  Key result: Of those who create projects, at least half share them
+        openly and cite them in submitted articles.
+    3.  Key result: At least half of those who create projects agree that they
+        would have been slower to finish (typically submit a paper) without
+        Calkit.
+
+## Funding and sustainability
+
+Calkit is committed to remaining free and open source forever.
+The project is sustained through a combination of:
+
+- **Volunteer contributions** from the community.
+- **Institutional support** through allocated work time.
+- **Calkit Cloud** optional paid plans to help cover infrastructure costs
+  for the cloud storage and compute service hosted at
+  [calkit.io](https://calkit.io).
+
+The cloud service operates on a freemium model:
+a generous free tier for most users,
+with paid options for those who need additional storage or compute resources.
+This helps ensure the service remains available and reliable
+without requiring payment for typical research projects.
+
+All Calkit software remains MIT-licensed and can be self-hosted
+and used with any compatible storage backend.
+In fact, we would prefer institutions host their own instance
+as part of a
+[decentralized, federated network](https://github.com/calkit/calkit-cloud/issues/190).

{calkit_python-0.32.8 → calkit_python-0.32.10}/mkdocs.yml

@@ -71,6 +71,7 @@ nav:
       - tutorials/github-actions.md
   - CLI reference: cli-reference.md
   - Help and support: help.md
+  - Governance: governance.md
 markdown_extensions:
   - admonition
   - attr_list

{calkit_python-0.32.8 → calkit_python-0.32.10}/pyproject.toml

@@ -16,11 +16,12 @@ dependencies = [
   "bibtexparser",
   "checksumdir",
   "docx2pdf",
-  "dvc==3.64.0",
+  "dvc==3.64.2",
   "fastapi",
   "gitpython",
   "keyring",
   "nbconvert",
+  "pathspec<1.0.0",
   "pillow",
   "pydantic[email]",
   "pydantic-settings",
@@ -35,7 +36,7 @@ dependencies = [
   "papermill>=2.6.0",
   "jupyterlab>=4.4.5",
   "sqlitedict>=2.1.0",
-  "json2latex>=0.0.2",
+  "json2latex>=0.0.3",
 ]
 description = "Reproducibility simplified."
 dynamic = ["version"]