Metadata-Version: 2.4
Name: labpaths
Version: 0.4.2
Summary: Cross-project / cross-machine path resolution: sync the code, keep outputs local, zero path edits.
Author-email: Yonas <xintao443@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Yonas-Xin/LabPaths
Project-URL: Repository, https://github.com/Yonas-Xin/LabPaths
Project-URL: Issues, https://github.com/Yonas-Xin/LabPaths/issues
Keywords: paths,configuration,reproducibility,research,cross-platform
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# labpaths

跨项目 / 跨机器的统一路径解析。**代码靠同步统一，产出靠不同步的机器配置区分**，
两者正交，换机器不用改任何地址参数。

## 为什么

同一个项目在多台机器（如 Mac 写代码、Windows 跑）之间，绝对路径各不相同。
把地址写死在每个脚本顶部，换机就要改 N 个文件、迟早出错。labpaths 把
“逻辑”和“每台机器/每个项目的具体值”彻底分开：

- **结构路径**（原始数据、产出根）：从 `__file__` 自动派生，跨机零改动。
- **机器专属值**（产出盘、项目外数据）：只写在一个**不随项目同步**的机器配置里。
- **可变构件**（多个候选权重/先验）：`resolve()` 让用户灵活自定义，绝对/相对都通。

## 安装（每台机器一次）

```bash
git clone <this-repo> ~/lab-tools/labpaths
pip install -e ~/lab-tools/labpaths
```

装好后任意项目、任意脚本里 `from labpaths import load` 直接可用，无需再往
`sys.path` 塞路径。

## 两层配置

**机器层** `~/labpaths.json`（每台机器一份，所有项目共用，**不随项目同步**）：

```json
{
  "output_base": "C:/2026H",
  "extras": { "spectra_lib": "C:/Users/you/usgs_v7" }
}
```

首次运行自动生成模板；也可 `python -m labpaths --init`。

**项目层** `projectroot.json`（放项目根，随项目同步，**只含名字、无绝对路径**）：

```json
{ "name": "myproj", "raw_dir": "60_data", "out": "SHIYAN_DATA" }
```

## 脚本里怎么用

```python
from labpaths import load
P = load(__file__)

raw   = P.data / "rasters" / "x.tif"       # 原始数据（随项目）
out   = P.out  / "runs" / "expA"           # 产出（本地，不同步）
usgs  = P.extra("spectra_lib") / "lib"     # 项目外数据（机器 extras）
ckpt  = P.resolve(user_value, base=P.out)  # 灵活权重：绝对原样/相对挂产出根/空->None
P.ensure(out)                              # 写入前建目录
```

## 铁律（配合同步）

**同步区里只写“名字”（`P.out`/`P.data`/`SHIYAN_DATA` 这种），真实盘符只写进不同步的
`~/labpaths.json`。** 于是同一份代码在 Mac / Windows 各自解析成各自的绝对路径。

## 新项目上手

1. 项目根跑 `python -m labpaths --init-project`：生成 `projectroot.json` +
   `AGENTS.md`（给其他 agent 的路径说明）。
2. `pip install -e` 本包（若该机器还没装）。
3. 脚本里 `from labpaths import load; P = load(__file__)`，路径全走 `P.*`。
4. 跑 `tests/test_no_abs_paths.py` 守住“禁绝对路径”。

配套的 `setup-paths` skill 可把 2~4 步在新项目里自动做掉。
