create tools/runfiles

a (subjectively) improved API for bazel runfiles in Python

tools/runfiles/BUILD.bazel

@@ -0,0 +1,19 @@
+load("@rules_python//python:defs.bzl", "py_library", "py_test")
+
+py_library(
+    name = "runfiles",
+    srcs = ["__init__.py"],
+    visibility = ["//visibility:public"],
+    deps = ["@rules_python//python/runfiles"],
+)
+
+py_test(
+    name = "runfiles_test",
+    size = "small",
+    srcs = ["runfiles_test.py"],
+    data = ["runfiles_test_data.txt"],
+    deps = [
+        ":runfiles",
+        "@pip//pytest",
+    ],
+)

tools/runfiles/__init__.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from python.runfiles import Runfiles
+
+# FIXME: https://github.com/bazelbuild/rules_python/issues/1679
+# from rules_python.python.runfiles import runfiles
+
+_RUNFILES = Runfiles.Create()
+
+
+def locate(path: str | Path, workspace: str = "__main__") -> Path:
+    if not isinstance(path, Path):
+        path = Path(path)
+
+    if path.is_absolute():
+        msg = f"{path=} must be a relative path"
+        raise ValueError(msg)
+
+    located = _RUNFILES.Rlocation(f"{workspace}/{path}")
+    if located is None:
+        msg = f"Failed to locate data-dependency. {path=} {workspace=}"
+        raise ValueError(msg)
+
+    pth = Path(located)
+    if not pth.exists():
+        msg = f"Located data-dependency does not exist. {located=} {path=} {workspace=}"
+        raise ValueError(msg)
+
+    return pth

tools/runfiles/runfiles_test.py

@@ -0,0 +1,23 @@
+import sys
+
+import pytest
+
+from tools import runfiles
+
+
+def test_runfiles_happy():
+    data = runfiles.locate("tools/runfiles/runfiles_test_data.txt")
+    assert data.read_text() == "Hello, world!\n"
+
+
+def test_runfiles_error():
+    to_locate = "tools/runfiles/does_not_exist.txt"
+    with pytest.raises(
+        ValueError,
+        match=r"^Located data-dependency does not exist.",
+    ):
+        runfiles.locate(to_locate)
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main(sys.argv))

tools/runfiles/runfiles_test_data.txt

@@ -0,0 +1 @@
+Hello, world!