src-snapshot 0.1.0__tar.gz

src_snapshot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    name: Smoke test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Oldest and newest Python on Linux, newest only on Windows and macOS.
+        include:
+          - { os: ubuntu-latest, python-version: "3.10" }
+          - { os: ubuntu-latest, python-version: "3.13" }
+          - { os: windows-latest, python-version: "3.13" }
+          - { os: macos-latest, python-version: "3.13" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Install wheel
+        shell: bash
+        run: python -m pip install dist/*.whl
+
+      - name: Snapshot from a script
+        shell: bash
+        run: |
+          python examples/create_zip.py
+          python -c "import zipfile; names = zipfile.ZipFile('code.zip').namelist(); print(names); assert '__main__.py' in names and 'metadata.json' in names"
+
+      - name: Snapshot without a main script (python -c)
+        shell: bash
+        run: |
+          python -c "from src_snapshot import create_snapshot; create_snapshot('interactive.zip', source_folders='src')"
+          python -c "import zipfile; names = zipfile.ZipFile('interactive.zip').namelist(); print(names); assert '__main__.py' not in names"
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/src-snapshot
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Check tag matches package version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

src_snapshot-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

src_snapshot-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

src_snapshot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominik Woiwode
+
+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.

src_snapshot-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: src-snapshot
+Version: 0.1.0
+Summary: Lightweight utility to snapshot your source code into a zip archive for reproducible experiments.
+Project-URL: Homepage, https://github.com/dwoiwode/src-snapshot
+Project-URL: Repository, https://github.com/dwoiwode/src-snapshot
+Project-URL: Issues, https://github.com/dwoiwode/src-snapshot/issues
+Author: Dominik Woiwode
+License-Expression: MIT
+License-File: LICENSE
+Keywords: experiments,provenance,reproducibility,research,slurm,snapshot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.10
+Requires-Dist: psutil
+Description-Content-Type: text/markdown
+
+# src-snapshot
+
+[![CI](https://github.com/dwoiwode/src-snapshot/actions/workflows/ci.yml/badge.svg)](https://github.com/dwoiwode/src-snapshot/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/src-snapshot)](https://pypi.org/project/src-snapshot/)
+[![Python](https://img.shields.io/pypi/pyversions/src-snapshot)](https://pypi.org/project/src-snapshot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Lightweight utility to snapshot your source code into a zip archive for reproducible experiments.
+
+Designed for researchers who want a simple, reliable way to store the exact code used for a run (and some metadata).
+
+## Installation
+
+```bash
+pip install src-snapshot
+```
+
+The package is installed as `src-snapshot` and imported as `src_snapshot`.
+
+## Usage
+```python
+from src_snapshot import create_snapshot
+
+create_snapshot("code.zip", source_folders="src")
+```
+
+That’s it. A zip archive will be created containing your source files and optional metadata.
+
+## Features
+- Copy selected source folders into a zip archive
+- Filter files by suffix (default: .py, .yaml)
+- Include the main entrypoint script (automatically or manual path)
+- Store current git commit and diff
+- Generate a metadata file with environment, hardware, SLURM and run information
+
+## API
+```python
+def create_snapshot(
+    filepath: Path | str,
+    *,
+    source_folders: Optional[Path | str | Iterable[Path | str]] = None,
+    suffixes: Optional[str | tuple[str]] = (".py", ".yaml"),
+    add_main_file: bool | Path | str = True,
+    add_git_diff: bool = True,
+    add_metadata: bool = True,
+)
+```
+
+### Arguments
+- ``filepath``: Output zip file (must not exist yet)
+- ``source_folders``: Folder(s) to include (default: current directory)
+- ``suffixes``: File extensions to include
+- ``add_main_file``: Include the main script as ``__main__.py``. ``True`` detects it automatically; pass a path to choose it explicitly.
+  In interactive sessions (Jupyter, REPL, ``python -c``) there is no main script, so it is skipped with a warning.
+- ``add_git_diff``: Store uncommitted changes as ``git_diff.patch``
+- ``add_metadata``: Write ``metadata.json`` (timestamp, environment, git info, installed packages)
+
+## Archive contents
+```
+code.zip
+├── <source_folder>/...   # your source files
+├── __main__.py           # the entrypoint script
+├── git_diff.patch        # uncommitted changes
+└── metadata.json         # run metadata
+```
+
+## Privacy
+``metadata.json`` contains the username, hostname, working directory, command line and the list of installed packages.
+Keep this in mind before sharing snapshots publicly, or set ``add_metadata=False``.
+
+## Releasing
+Releases are published to PyPI by GitHub Actions using [trusted publishing](https://docs.pypi.org/trusted-publishers/):
+
+1. Bump ``version`` in ``pyproject.toml``.
+2. Commit, then tag and push: ``git tag v0.1.0 && git push origin v0.1.0``.
+
+The workflow runs the tests, checks that the tag matches the version, builds and uploads the package.
+
+## License
+[MIT](LICENSE)

src_snapshot-0.1.0/README.md

@@ -0,0 +1,80 @@
+# src-snapshot
+
+[![CI](https://github.com/dwoiwode/src-snapshot/actions/workflows/ci.yml/badge.svg)](https://github.com/dwoiwode/src-snapshot/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/src-snapshot)](https://pypi.org/project/src-snapshot/)
+[![Python](https://img.shields.io/pypi/pyversions/src-snapshot)](https://pypi.org/project/src-snapshot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Lightweight utility to snapshot your source code into a zip archive for reproducible experiments.
+
+Designed for researchers who want a simple, reliable way to store the exact code used for a run (and some metadata).
+
+## Installation
+
+```bash
+pip install src-snapshot
+```
+
+The package is installed as `src-snapshot` and imported as `src_snapshot`.
+
+## Usage
+```python
+from src_snapshot import create_snapshot
+
+create_snapshot("code.zip", source_folders="src")
+```
+
+That’s it. A zip archive will be created containing your source files and optional metadata.
+
+## Features
+- Copy selected source folders into a zip archive
+- Filter files by suffix (default: .py, .yaml)
+- Include the main entrypoint script (automatically or manual path)
+- Store current git commit and diff
+- Generate a metadata file with environment, hardware, SLURM and run information
+
+## API
+```python
+def create_snapshot(
+    filepath: Path | str,
+    *,
+    source_folders: Optional[Path | str | Iterable[Path | str]] = None,
+    suffixes: Optional[str | tuple[str]] = (".py", ".yaml"),
+    add_main_file: bool | Path | str = True,
+    add_git_diff: bool = True,
+    add_metadata: bool = True,
+)
+```
+
+### Arguments
+- ``filepath``: Output zip file (must not exist yet)
+- ``source_folders``: Folder(s) to include (default: current directory)
+- ``suffixes``: File extensions to include
+- ``add_main_file``: Include the main script as ``__main__.py``. ``True`` detects it automatically; pass a path to choose it explicitly.
+  In interactive sessions (Jupyter, REPL, ``python -c``) there is no main script, so it is skipped with a warning.
+- ``add_git_diff``: Store uncommitted changes as ``git_diff.patch``
+- ``add_metadata``: Write ``metadata.json`` (timestamp, environment, git info, installed packages)
+
+## Archive contents
+```
+code.zip
+├── <source_folder>/...   # your source files
+├── __main__.py           # the entrypoint script
+├── git_diff.patch        # uncommitted changes
+└── metadata.json         # run metadata
+```
+
+## Privacy
+``metadata.json`` contains the username, hostname, working directory, command line and the list of installed packages.
+Keep this in mind before sharing snapshots publicly, or set ``add_metadata=False``.
+
+## Releasing
+Releases are published to PyPI by GitHub Actions using [trusted publishing](https://docs.pypi.org/trusted-publishers/):
+
+1. Bump ``version`` in ``pyproject.toml``.
+2. Commit, then tag and push: ``git tag v0.1.0 && git push origin v0.1.0``.
+
+The workflow runs the tests, checks that the tag matches the version, builds and uploads the package.
+
+## License
+[MIT](LICENSE)

src_snapshot-0.1.0/examples/create_zip.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+from src_snapshot import create_snapshot
+
+# Snapshot the package source next to this repository's examples folder
+create_snapshot("code.zip", source_folders=Path(__file__).parent.parent / "src")

src_snapshot-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "src-snapshot"
+version = "0.1.0"
+description = "Lightweight utility to snapshot your source code into a zip archive for reproducible experiments."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Dominik Woiwode" }]
+requires-python = ">=3.10"
+dependencies = [
+    "psutil",
+]
+keywords = ["reproducibility", "snapshot", "experiments", "research", "provenance", "slurm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Archiving",
+]
+
+[project.urls]
+Homepage = "https://github.com/dwoiwode/src-snapshot"
+Repository = "https://github.com/dwoiwode/src-snapshot"
+Issues = "https://github.com/dwoiwode/src-snapshot/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/src_snapshot"]

src_snapshot-0.1.0/src/src_snapshot/__init__.py

@@ -0,0 +1 @@
+from .snapshot import create_snapshot

src_snapshot-0.1.0/src/src_snapshot/snapshot.py

@@ -0,0 +1,90 @@
+import datetime
+import json
+import os
+import tempfile
+import warnings
+from pathlib import Path
+from typing import Optional, Iterable
+from zipfile import ZipFile, ZIP_DEFLATED
+
+from src_snapshot.utils import git_diff, create_metadata, zip_file_folders, get_main_script_path
+
+
+def create_snapshot(
+        filepath: Path | str,
+        *,
+        source_folders: Optional[Path | str | Iterable[Path | str]] = None,
+        suffixes: Optional[str | tuple[str]] = (".py", ".yaml"),
+        add_main_file: bool | Path | str = True,
+        add_git_diff: bool = True,
+        add_metadata: bool = True
+):
+    # Prepare source folders (default: current directory)
+    if source_folders is None:
+        source_folders = (Path.cwd(),)
+    elif isinstance(source_folders, (str, Path)):
+        source_folders = (source_folders,)
+    else:
+        source_folders = tuple(source_folders)
+
+    # Prepare output folder
+    filepath = Path(filepath)
+    if filepath.exists():
+        raise FileExistsError(f"Code already exists at {filepath.absolute()}!")
+
+    filepath.parent.mkdir(exist_ok=True, parents=True)
+
+    # Write to a temp file next to the target and rename at the end,
+    # so a failed run never leaves a half-written zip behind.
+    fd, tmp_name = tempfile.mkstemp(dir=filepath.parent, prefix=f".{filepath.name}.", suffix=".tmp")
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    try:
+        _write_zip(tmp_path, source_folders, suffixes, add_main_file, add_git_diff, add_metadata)
+        os.replace(tmp_path, filepath)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def _write_zip(zip_path, source_folders, suffixes, add_main_file, add_git_diff, add_metadata):
+    with ZipFile(zip_path, 'w', compression=ZIP_DEFLATED) as zip_file:
+        n = 0
+        for source_folder in source_folders:
+            source_folder = Path(source_folder).resolve()
+            n += zip_file_folders(zip_file, source_folder, source_folder.name, suffixes=suffixes)
+
+        # Add main file
+        if add_main_file:
+            if isinstance(add_main_file, (Path, str)):
+                main_file = Path(add_main_file)
+                if not main_file.is_file():
+                    raise FileNotFoundError(f"Main file not found: {main_file.absolute()}")
+            else:
+                main_file = get_main_script_path()
+
+            if main_file is None:
+                # e.g. Jupyter, REPL or `python -c`: nothing to copy
+                warnings.warn(
+                    "Could not determine the main script (interactive session?); "
+                    "skipping __main__.py. Pass add_main_file=<path> to set it explicitly.",
+                    stacklevel=3,
+                )
+            else:
+                main_file_content = (
+                    f"# Originally copied on {datetime.datetime.now():%Y-%m-%d %H:%M:%S} from {main_file.absolute()}\n\n"
+                    f"{main_file.read_text(encoding='utf-8')}"
+                )
+                zip_file.writestr('__main__.py', main_file_content)
+                n += 1
+
+        # Add git diff
+        if add_git_diff:
+            n += 1
+            zip_file.writestr('git_diff.patch', git_diff())
+
+        # Add metadata
+        if add_metadata:
+            n += 1
+            meta = create_metadata()
+            meta["files_copied"] = n
+            zip_file.writestr('metadata.json', json.dumps(meta, indent=2))

src_snapshot-0.1.0/src/src_snapshot/utils.py

@@ -0,0 +1,195 @@
+import datetime
+import getpass
+import importlib.metadata
+import inspect
+import os
+import platform
+import socket
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+import psutil
+
+
+def dependencies():
+    """Installed distributions as sorted ``name==version`` strings (like ``pip freeze``)."""
+    packages = {}
+    for dist in importlib.metadata.distributions():
+        name = dist.metadata["Name"]
+        if name:  # skip broken installs without metadata
+            packages.setdefault(name, dist.version)
+    return [f"{name}=={version}" for name, version in sorted(packages.items(), key=lambda kv: kv[0].lower())]
+
+
+def environment_info():
+    info = {
+        "python": sys.version.replace("\n", " "),
+        "executable": sys.executable,
+        "platform": platform.platform(),
+        "machine": platform.machine(),
+        "processor": platform.processor(),
+        "hardware": {
+            "GPU": gpu_info(),
+            "RAM": ram_info()
+        }
+    }
+    return info
+
+
+def git_info():
+    def _run(cmd):
+        try:
+            return subprocess.check_output(cmd, stderr=subprocess.DEVNULL).decode().strip()
+        except Exception:
+            return "unknown"
+
+    return {
+        "repo_url": _run(["git", "config", "--get", "remote.origin.url"]),
+        "commit": _run(["git", "rev-parse", "HEAD"]),
+        "short_commit": _run(["git", "rev-parse", "--short", "HEAD"]),
+        "branch": _run(["git", "rev-parse", "--abbrev-ref", "HEAD"]),
+        "dirty": bool(_run(["git", "status", "--porcelain"])),
+        "tag": _run(["git", "describe", "--tags", "--abbrev=0"]),
+    }
+
+def git_diff():
+    try:
+        return subprocess.check_output(["git", "diff"], stderr=subprocess.DEVNULL).decode().strip()
+    except (OSError, subprocess.CalledProcessError):
+        # git missing or not inside a repository
+        return ""
+
+def create_metadata():
+    now = datetime.datetime.now(datetime.timezone.utc).isoformat()
+    main_file = get_main_script_path()
+    meta = {
+        "timestamp_utc": now,
+        "provenance": git_info(),
+        "user": user_info(),
+        "execution": {
+            "entrypoint": f"{main_file.absolute() if main_file else 'unknown'}",
+            "sys.argv": " ".join(sys.orig_argv),
+            "cwd": str(Path.cwd()),
+            "hostname": socket.gethostname(),
+            "pid": os.getpid(),
+        },
+        "environment": environment_info(),
+        "slurm": slurm_info(),
+        "dependencies": dependencies(),
+    }
+    return meta
+
+def zip_file_folders(
+        zip_file,
+        in_dir: Path,
+        archive_path: str,
+        *,
+        suffixes: Optional[str | tuple[str]] = None
+) -> int:
+    if in_dir.is_dir():
+        n = 0
+        for file_folder in in_dir.iterdir():
+            n += zip_file_folders(zip_file, file_folder, f"{archive_path}/{file_folder.name}", suffixes=suffixes)
+        return n
+    elif in_dir.is_file():
+        if isinstance(suffixes, str) and not in_dir.suffix == suffixes:
+            return 0
+
+        if isinstance(suffixes, tuple | list) and in_dir.suffix not in suffixes:
+            return 0
+
+        # Add file to zip
+        zip_file.write(in_dir, archive_path)
+        return 1
+
+    else:
+        raise TypeError(f"What is {in_dir} if not file or folder?")
+
+
+def get_main_script_path() -> Optional[Path]:
+    """
+    This function gets the current frame and then recursively goes back to the calling function until
+        - no more calling function exists (-> reached most top level file)
+        - the __name__ of the current file is "__main__"
+    :return:
+    """
+
+    current_frame = inspect.currentframe()
+    while current_frame is not None:
+        # Check if the module is the main module
+        if current_frame.f_globals.get("__name__") == "__main__":
+            main_file = current_frame.f_globals.get("__file__")
+            # No __file__ in REPLs, Jupyter or `python -c`
+            if main_file is None:
+                return None
+            main_file = Path(main_file)
+            return main_file if main_file.is_file() else None
+        current_frame = current_frame.f_back
+    return None
+
+def slurm_info():
+    def env(key):
+        return os.environ.get(key)
+
+    info = {
+        "job_id": env("SLURM_JOB_ID"),
+        "job_name": env("SLURM_JOB_NAME"),
+        "array_job_id": env("SLURM_ARRAY_JOB_ID"),
+        "array_task_id": env("SLURM_ARRAY_TASK_ID"),
+        "partition": env("SLURM_JOB_PARTITION"),
+        "node_list": env("SLURM_NODELIST"),
+        "num_nodes": env("SLURM_JOB_NUM_NODES"),
+        "num_tasks": env("SLURM_NTASKS"),
+        "cpus_per_task": env("SLURM_CPUS_PER_TASK"),
+        "cpus_on_node": env("SLURM_CPUS_ON_NODE"),
+        "gpus": env("SLURM_GPUS"),
+        "gpus_per_node": env("SLURM_GPUS_ON_NODE"),
+        "ntasks_per_node": env("SLURM_NTASKS_PER_NODE"),
+        "local_id": env("SLURM_LOCALID"),
+        "global_id": env("SLURM_PROCID"),
+    }
+
+    # remove keys that are not set
+    info = {k: v for k, v in info.items() if v is not None}
+
+    return info if info else None
+
+def gpu_info():
+    try:
+        out = subprocess.check_output([
+            "nvidia-smi",
+            "--query-gpu=index,name,memory.total",
+            "--format=csv,noheader,nounits"
+        ]).decode().strip().splitlines()
+    except (OSError, subprocess.CalledProcessError):
+        # nvidia-smi missing or failing (e.g. no driver) -> no GPU info
+        return []
+
+    gpus = []
+    for line in out:
+        try:
+            idx, name, mem = [x.strip() for x in line.split(",")]
+        except ValueError:
+            continue
+        gpus.append({
+            "index": int(idx) if idx.isdigit() else idx,
+            "name": name,
+            "memory_mb": int(mem) if mem.isdigit() else None,
+        })
+    return gpus
+
+def ram_info():
+    vm = psutil.virtual_memory()
+    return {
+        "total_bytes": vm.total,
+        "available_bytes": vm.available,
+        "used_bytes": vm.used,
+    }
+
+def user_info():
+    return {
+        "username": getpass.getuser(),
+        "uid": os.getuid() if hasattr(os, "getuid") else None,
+    }