scitex-path 0.1.6

Scientific project path utilities (find, split, symlink, versioning)

scitex-path

Scientific project path utilities — find files / git root, symlink mgmt, version increment.

Full Documentation · uv pip install scitex-path[all]

---

Problem and Solution

#	Problem	Solution
1	Scripts hard-code /home/user/proj/... paths — break the moment someone else runs them	find_git_root() + get_spath(filename) — paths auto-resolve to the repo root and the current script's _out/ dir
2	{script}_out/ convention implemented 33 different ways — inconsistent, error-prone	Canonical helpers — mk_spath, get_this_path, create_relative_symlink, find_latest standardize the pattern

Installation

pip install scitex-path

Quick Start

import scitex_path as sp

git_root = sp.find_git_root()
matches = sp.find_file("*.csv", root="/data/project")

1 Interfaces

Python API

import scitex_path as sp

# Find
sp.find_file("*.csv", root="/data/project")
sp.find_dir("results_*", root="/runs")
sp.find_git_root()
sp.find_latest("/results/experiment_v*")

# Path manipulation
sp.split("/home/user/project/data/results.csv")
sp.clean("path/with/../spaces ")
sp.getsize("/path/to/dir")

# Symlinks
sp.symlink("/data/raw", "/project/data/raw")
sp.create_relative_symlink(src, dst)
sp.list_symlinks("/project/data")
sp.fix_broken_symlinks("/project/data")
sp.resolve_symlinks(path)

# Versioning
sp.increment_version("v1.2.3", part="patch")  # "v1.2.4"

# Session paths (relative to calling script)
sp.this_path() / sp.get_this_path()
sp.get_spath(filename) / sp.mk_spath(filename)

Architecture

scitex_path/
├── _find.py              ← find_file, find_dir, find_git_root, find_latest
├── _split_clean.py       ← split, clean, getsize
├── _symlink.py           ← symlink, create_relative_symlink,
│                            list_symlinks, fix_broken_symlinks, resolve_symlinks
├── _version.py           ← increment_version (semver bumps)
└── _session.py           ← this_path / get_spath / mk_spath
                            (caller-script-relative `_out/` dirs)

Demo

flowchart LR
    A[script.py] -->|find_git_root| B[repo root]
    A -->|mk_spath| C[script_out/]
    C --> D[results.csv]
    D -->|create_relative_symlink| E[repo/latest.csv]
    F[/runs/experiment_v*/] -->|find_latest| G[experiment_v17]

import scitex_path as sp

root = sp.find_git_root()                          # → /home/me/proj/myrepo
out  = sp.mk_spath("results.csv")                  # → <script>_out/results.csv
sp.create_relative_symlink(out, root / "latest.csv")
print(sp.find_latest("/runs/experiment_v*"))       # → /runs/experiment_v17

/home/me/proj/myrepo
/home/me/proj/myrepo/scripts/train_out/results.csv
/runs/experiment_v17

Part of SciTeX

scitex-path is part of SciTeX. Install via the umbrella with pip install scitex[path] to use as scitex.path (Python) or scitex path ... (CLI).

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

License

AGPL-3.0 — see LICENSE for details.

---