artifactum 0.2.0__tar.gz

artifactum-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+.pixi/*
+!.pixi/config.toml
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/

artifactum-0.2.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [0.2.0](https://github.com/atfm-io/artifactum/compare/v0.1.0...v0.2.0) (2026-11-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* **storage:** google-cloud-storage is no longer installed by default. Install `artifactum[gcs]` to keep storing files in a bucket.
+* **cli:** the `artifactum` console script no longer exists. Run `atfm` instead.
+
+### Features
+
+* **cli:** add --json output to get, publish, describe, log and run status ([16f97aa](https://github.com/atfm-io/artifactum/commit/16f97aafbcdca2c34815cc49d9502ff3e3abe431))
+* **cli:** atfm --version ([5f16856](https://github.com/atfm-io/artifactum/commit/5f1685657061c83e92da738cc2e650a3f191d932))
+* **cli:** atfm init --token --storage, and atfm storage move ([6aecb95](https://github.com/atfm-io/artifactum/commit/6aecb95afca1c751ee88f04a0ed960358af57f98))
+* **cli:** label the terminal browser as a preview ([b6a9940](https://github.com/atfm-io/artifactum/commit/b6a99403ec090edb2dbf34d98653b6a0a4e32e13))
+* **cli:** the command is atfm only ([0777167](https://github.com/atfm-io/artifactum/commit/0777167210378998a1f46601a87ba8f7fd31f982))
+* **storage:** store files in a shared directory, or a GCS bucket ([3db014f](https://github.com/atfm-io/artifactum/commit/3db014fc0d89c4ba53ca7fa1480b9c6517eeff32))
+* support Python 3.10 ([070f6c4](https://github.com/atfm-io/artifactum/commit/070f6c4e69ec3756777a5debcb1d1f1223684e12))
+
+
+### Bug Fixes
+
+* accept artifact IDs in lowercase ([be79ec2](https://github.com/atfm-io/artifactum/commit/be79ec2a4a103d5b43c7ba0416abb0073dfb2595))
+* **cli:** clear errors instead of tracebacks, and other fixes found by new tests ([fd3fe10](https://github.com/atfm-io/artifactum/commit/fd3fe1085535fb724740d6ba312c91d92a4ff1b6))
+* **cli:** no hint about parents on the first publish ([451b737](https://github.com/atfm-io/artifactum/commit/451b737cd02f12b36aea031e25345de404d09e3d))
+
+
+### Documentation
+
+* MIT license ([7ad2ce5](https://github.com/atfm-io/artifactum/commit/7ad2ce50729fba95843b57b8546e01542d3316c4))
+* README no longer mentions an atfm search command ([2d9b86e](https://github.com/atfm-io/artifactum/commit/2d9b86e2aa1a97ee47ef54a4c9872265d51fd946))

artifactum-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+## Development
+
+The development environment is defined in `pyproject.toml` (the `[tool.pixi.*]` tables):
+
+```bash
+pixi run test   # runs the tests and prints a coverage report
+pixi run fmt    # formats the code and fixes what ruff can fix
+pixi run lint   # what CI checks: formatting and lint, without changing anything
+pixi run install-hooks   # once per clone: ruff then runs on every commit
+```
+
+Without pixi: `pip install -e ".[dev]"`, then `pytest`, `ruff format` and `ruff check`.
+Style settings are in `[tool.ruff]` in `pyproject.toml`.
+
+## Commit messages
+
+Every commit on `main` follows [Conventional Commits](https://www.conventionalcommits.org/).
+Releases are cut from these messages by [release-please](https://github.com/googleapis/release-please),
+so a commit that doesn't follow the format is left out of the changelog.
+
+```
+<type>(<optional scope>): <summary in the imperative>
+
+<optional body>
+
+<optional footers, e.g. BREAKING CHANGE: ...>
+```
+
+| Type | Use for | In the changelog | Version bump |
+| --- | --- | --- | --- |
+| `feat` | a new feature | Features | minor |
+| `fix` | a bug fix | Bug Fixes | patch |
+| `perf` | a performance improvement | Performance | patch |
+| `docs` | documentation only | Documentation | patch |
+| `deps` | dependency updates | Dependencies | patch |
+| `refactor`, `test`, `build`, `ci`, `chore`, `style` | everything else | hidden | none |
+
+A `!` after the type (`feat!: ...`) or a `BREAKING CHANGE:` footer marks a breaking change.
+While the version is below 1.0, breaking changes bump the minor version.
+
+Pull requests are squash-merged, so the PR title becomes the commit message and must
+follow the same format.
+
+## Releases
+
+release-please keeps a release PR open that collects unreleased changes, bumps the
+version in `pyproject.toml` and updates `CHANGELOG.md`. Merging that PR tags the release
+(`vX.Y.Z`), publishes a GitHub release with the built files attached, and uploads the
+package to PyPI.

artifactum-0.2.0/LICENSE

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

artifactum-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: artifactum
+Version: 0.2.0
+Summary: A registry and lineage tracker for the files data teams produce
+Project-URL: Homepage, https://atfm.io
+Project-URL: Repository, https://github.com/atfm-io/artifactum
+Project-URL: Issues, https://github.com/atfm-io/artifactum/issues
+Author-email: Chris Cole <chris.c.1221@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: artifacts,data lineage,data versioning,provenance,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonargparse>=4.35
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.70
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=1.1; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.0; extra == 'gcs'
+Description-Content-Type: text/markdown
+
+# Artifactum · `atfm`
+
+[atfm.io](https://atfm.io) · `pip install artifactum` · `import artifactum as atfm` · the `atfm` command
+
+A registry and lineage tracker for the files data teams produce: datasets, models, results and figures.
+
+Every file you publish gets a permanent ID, and Artifactum records where it came from: the artifacts your
+code read, the git commit and code that ran, and who published it. Files stay in storage your team
+controls, a shared directory or a Google Cloud Storage bucket; Artifactum stores only metadata.
+
+## Install
+
+```bash
+pip install artifactum
+atfm init
+```
+
+`init` asks for your API token (from Settings at [atfm.io](https://atfm.io)), your server URL (`https://atfm.io`
+unless your team runs its own) and where to store files. Or give them and skip the questions:
+
+```bash
+atfm init --token atfm_... --storage ~/atfm-files
+```
+
+## Storage
+
+Artifactum never holds your files. Each one is copied to your team's storage when it's published and
+fetched from there when someone reads it, then cached locally.
+
+| Storage | Location to give `init` | Install |
+| --- | --- | --- |
+| A shared directory (lab server, cluster, network drive) | `/groups/lab/atfm` | `pip install artifactum` |
+| Google Cloud Storage | `gs://my-team-bucket/atfm` | `pip install 'artifactum[gcs]'` |
+
+A shared directory needs no cloud account: everyone on the team just needs to reach it **at the same
+path**, since the registry records where each file is. Files are stored by content, under
+`<location>/<hash[:2]>/<hash>/<filename>`, and never overwritten.
+
+For Google Cloud Storage, each person signs in once with `gcloud auth application-default login` and needs
+read and write access to the bucket.
+
+To try Artifactum on your own, a folder like `~/atfm-files` is enough. When you bring in your team, move
+what you've published to shared storage; the files are copied, checked against their hashes and their
+records updated, and the old copies are left in place:
+
+```bash
+atfm storage move /groups/lab/atfm      # or gs://my-team-bucket/atfm
+```
+
+## Use
+
+```python
+import artifactum as atfm
+import pandas as pd
+
+events = pd.read_parquet(atfm.artifact("C4LN9E2A"))  # fetched and cached locally
+features = build_features(events)
+features.to_parquet("features.parquet")
+
+atfm.publish(
+    "features.parquet",
+    description="Feature matrix, nulls dropped",
+    tags=["features"],
+)
+# C4LN9E2A is recorded as the parent automatically, along with the git commit and code.
+```
+
+From the shell (bash, R, Nextflow, Snakemake, ...):
+
+```bash
+eval "$(atfm run start 'align reads')"      # lineage is recorded across the commands below
+bwa mem "$(atfm get GRCH38RF)" "$(atfm get FQ7R1A2B)" > aligned.sam
+atfm publish aligned.bam -d "Reads aligned with BWA-MEM" --code align.sh
+eval "$(atfm run end)"
+```
+
+`atfm get` prints a local path and `atfm publish` prints the new ID, so both compose with other
+commands. Use `--parent ID` to set parents explicitly.
+
+Add `--json` to `get`, `publish`, `describe`, `log` or `run status` to get one JSON object on stdout
+instead, for tools that parse rather than split strings. Messages and errors stay on stderr, and a
+failure exits non-zero.
+
+```bash
+$ atfm get C4LN9E2A --json
+{"id": "C4LN9E2A", "path": "/home/me/.artifactum/cache/3f9a..."}
+$ atfm publish model.rds -p C4LN9E2A --json
+{"id": "M0DL3V3X", "file": "/home/me/project/model.rds", "parents": ["C4LN9E2A"], "run_id": null}
+```
+
+From R, call the command and read its JSON with `jsonlite`:
+
+```r
+atfm <- function(...) {
+  out <- system2("atfm", c(..., "--json"), stdout = TRUE)
+  if (!is.null(attr(out, "status"))) stop("atfm failed")
+  jsonlite::fromJSON(paste(out, collapse = ""))
+}
+
+counts <- read.csv(atfm("get", "C4LN9E2A")$path)
+saveRDS(fit, "model.rds")
+atfm("publish", "model.rds", "-p", "C4LN9E2A", "-d", shQuote("GLM on cleaned counts"))$id
+```
+
+There's no R package yet. If you'd like one, email hello@atfm.io.
+
+Browsing from the terminal:
+
+```bash
+atfm log K9PWQM7T      # upstream lineage
+atfm browse            # interactive browser (preview: recent artifacts, no search yet)
+```
+
+## License
+
+MIT. See [LICENSE](https://github.com/atfm-io/artifactum/blob/main/LICENSE).

artifactum-0.2.0/README.md

@@ -0,0 +1,116 @@
+# Artifactum · `atfm`
+
+[atfm.io](https://atfm.io) · `pip install artifactum` · `import artifactum as atfm` · the `atfm` command
+
+A registry and lineage tracker for the files data teams produce: datasets, models, results and figures.
+
+Every file you publish gets a permanent ID, and Artifactum records where it came from: the artifacts your
+code read, the git commit and code that ran, and who published it. Files stay in storage your team
+controls, a shared directory or a Google Cloud Storage bucket; Artifactum stores only metadata.
+
+## Install
+
+```bash
+pip install artifactum
+atfm init
+```
+
+`init` asks for your API token (from Settings at [atfm.io](https://atfm.io)), your server URL (`https://atfm.io`
+unless your team runs its own) and where to store files. Or give them and skip the questions:
+
+```bash
+atfm init --token atfm_... --storage ~/atfm-files
+```
+
+## Storage
+
+Artifactum never holds your files. Each one is copied to your team's storage when it's published and
+fetched from there when someone reads it, then cached locally.
+
+| Storage | Location to give `init` | Install |
+| --- | --- | --- |
+| A shared directory (lab server, cluster, network drive) | `/groups/lab/atfm` | `pip install artifactum` |
+| Google Cloud Storage | `gs://my-team-bucket/atfm` | `pip install 'artifactum[gcs]'` |
+
+A shared directory needs no cloud account: everyone on the team just needs to reach it **at the same
+path**, since the registry records where each file is. Files are stored by content, under
+`<location>/<hash[:2]>/<hash>/<filename>`, and never overwritten.
+
+For Google Cloud Storage, each person signs in once with `gcloud auth application-default login` and needs
+read and write access to the bucket.
+
+To try Artifactum on your own, a folder like `~/atfm-files` is enough. When you bring in your team, move
+what you've published to shared storage; the files are copied, checked against their hashes and their
+records updated, and the old copies are left in place:
+
+```bash
+atfm storage move /groups/lab/atfm      # or gs://my-team-bucket/atfm
+```
+
+## Use
+
+```python
+import artifactum as atfm
+import pandas as pd
+
+events = pd.read_parquet(atfm.artifact("C4LN9E2A"))  # fetched and cached locally
+features = build_features(events)
+features.to_parquet("features.parquet")
+
+atfm.publish(
+    "features.parquet",
+    description="Feature matrix, nulls dropped",
+    tags=["features"],
+)
+# C4LN9E2A is recorded as the parent automatically, along with the git commit and code.
+```
+
+From the shell (bash, R, Nextflow, Snakemake, ...):
+
+```bash
+eval "$(atfm run start 'align reads')"      # lineage is recorded across the commands below
+bwa mem "$(atfm get GRCH38RF)" "$(atfm get FQ7R1A2B)" > aligned.sam
+atfm publish aligned.bam -d "Reads aligned with BWA-MEM" --code align.sh
+eval "$(atfm run end)"
+```
+
+`atfm get` prints a local path and `atfm publish` prints the new ID, so both compose with other
+commands. Use `--parent ID` to set parents explicitly.
+
+Add `--json` to `get`, `publish`, `describe`, `log` or `run status` to get one JSON object on stdout
+instead, for tools that parse rather than split strings. Messages and errors stay on stderr, and a
+failure exits non-zero.
+
+```bash
+$ atfm get C4LN9E2A --json
+{"id": "C4LN9E2A", "path": "/home/me/.artifactum/cache/3f9a..."}
+$ atfm publish model.rds -p C4LN9E2A --json
+{"id": "M0DL3V3X", "file": "/home/me/project/model.rds", "parents": ["C4LN9E2A"], "run_id": null}
+```
+
+From R, call the command and read its JSON with `jsonlite`:
+
+```r
+atfm <- function(...) {
+  out <- system2("atfm", c(..., "--json"), stdout = TRUE)
+  if (!is.null(attr(out, "status"))) stop("atfm failed")
+  jsonlite::fromJSON(paste(out, collapse = ""))
+}
+
+counts <- read.csv(atfm("get", "C4LN9E2A")$path)
+saveRDS(fit, "model.rds")
+atfm("publish", "model.rds", "-p", "C4LN9E2A", "-d", shQuote("GLM on cleaned counts"))$id
+```
+
+There's no R package yet. If you'd like one, email hello@atfm.io.
+
+Browsing from the terminal:
+
+```bash
+atfm log K9PWQM7T      # upstream lineage
+atfm browse            # interactive browser (preview: recent artifacts, no search yet)
+```
+
+## License
+
+MIT. See [LICENSE](https://github.com/atfm-io/artifactum/blob/main/LICENSE).

artifactum-0.2.0/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "artifactum"
+version = "0.2.0"
+description = "A registry and lineage tracker for the files data teams produce"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Chris Cole", email = "chris.c.1221@gmail.com"}]
+requires-python = ">= 3.10"
+keywords = ["data lineage", "provenance", "artifacts", "reproducibility", "data versioning"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.27",
+    "jsonargparse>=4.35",
+    "rich>=13.0",
+    "textual>=0.70",
+    "tomli-w>=1.0",
+    "pyperclip>=1.8",
+    "tomli>=1.1; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+# Storing files in a Google Cloud Storage bucket (a shared directory needs nothing extra)
+gcs = ["google-cloud-storage>=2.0"]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "ruff>=0.8", "pre-commit>=3.5"]
+
+[project.urls]
+Homepage = "https://atfm.io"
+Repository = "https://github.com/atfm-io/artifactum"
+Issues = "https://github.com/atfm-io/artifactum/issues"
+
+[project.scripts]
+atfm = "artifactum.cli.main:main"
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/artifactum"]
+
+# The source archive is the package, its tests and docs; not the dev tooling
+[tool.hatch.build.targets.sdist]
+include = ["src/artifactum", "tests", "LICENSE", "README.md", "CHANGELOG.md", "CONTRIBUTING.md"]
+
+# ── Development environment (pixi) ───────────────────────────────────────────────
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64", "osx-64"]
+
+[tool.pixi.dependencies]
+python = "3.12.*"
+
+[tool.pixi.pypi-dependencies]
+artifactum = { path = ".", editable = true, extras = ["dev"] }
+
+[tool.pixi.tasks]
+test = "pytest"
+# Format and fix what can be fixed automatically, then report the rest
+fmt = "ruff format && ruff check --fix"
+# What CI runs: fails on unformatted code or lint errors, changes nothing
+lint = "ruff format --check && ruff check"
+# Run ruff automatically on every commit (once per clone)
+install-hooks = "pre-commit install"
+
+# ── Code style ───────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E", "W",  # pycodestyle
+    "F",       # pyflakes: unused imports and variables, undefined names
+    "I",       # import order
+    "UP",      # modern syntax for the supported Python versions
+    "B",       # likely bugs (bugbear)
+    "SIM",     # simpler equivalents
+]
+
+# ── Tests and coverage ───────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["artifactum"]
+branch = true
+
+[tool.coverage.report]
+# CI fails if coverage drops below this (91% when it was set)
+fail_under = 85
+skip_covered = true
+show_missing = true
+exclude_also = ["if __name__ == .__main__.:", "if TYPE_CHECKING:"]