Skip to content

_storage

Runtime directory operations. Disk only, no R, no config.

Functions

get_os()

Returns 'linux', 'macos', or 'windows'.

Source code in brmspy/_runtime/_platform.py 
20
21
22
23
24
25
26
27
28
def get_os() -> str:
    """Returns 'linux', 'macos', or 'windows'."""
    raw_os = platform.system().lower()
    if raw_os == "darwin":
        return "macos"
    elif raw_os in ("windows", "linux"):
        return raw_os
    else:
        return raw_os

get_runtime_base_dir()

Returns ~/.brmspy/runtime/, creating if needed.

Source code in brmspy/_runtime/_storage.py 
12
13
14
15
16
def get_runtime_base_dir() -> Path:
    """Returns ~/.brmspy/runtime/, creating if needed."""
    base_dir = Path.home() / ".brmspy" / "runtime"
    base_dir.mkdir(parents=True, exist_ok=True)
    return base_dir

get_runtime_path(fingerprint, version, n=None, allow_existing=True)

Returns ~/.brmspy/runtime/{fingerprint}-{version}/.

Source code in brmspy/_runtime/_storage.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
def get_runtime_path(fingerprint: str, version: str, n=None, allow_existing=True) -> Path:
    """Returns ~/.brmspy/runtime/{fingerprint}-{version}/."""
    if n is None:
        runtime_path = get_runtime_base_dir() / f"{fingerprint}-{version}"
    else:
        runtime_path = get_runtime_base_dir() / f"{fingerprint}-{version}-{n}"
    if not allow_existing:
        if runtime_path.exists():
            if n is None:
                n = 0
            return get_runtime_path(fingerprint, version, n + 1)

    return runtime_path

is_runtime_dir(path)

Check if path has valid structure (manifest.json, Rlib/, cmdstan/).

Source code in brmspy/_runtime/_storage.py 
34
35
36
37
38
39
def is_runtime_dir(path: Path) -> bool:
    """Check if path has valid structure (manifest.json, Rlib/, cmdstan/)."""
    if not path.is_dir():
        return False
    manifest = path / "manifest.json"
    return manifest.is_file()

list_installed_runtimes()

List all installed runtime directories.

Source code in brmspy/_runtime/_storage.py 
42
43
44
45
46
47
48
49
50
51
52
def list_installed_runtimes() -> list[Path]:
    """List all installed runtime directories."""
    base_dir = get_runtime_base_dir()
    if not base_dir.exists():
        return []

    runtimes = []
    for item in base_dir.iterdir():
        if item.is_dir() and is_runtime_dir(item):
            runtimes.append(item)
    return runtimes

find_runtime_by_fingerprint(fingerprint)

Find newest installed runtime matching fingerprint.

Source code in brmspy/_runtime/_storage.py 
55
56
57
58
59
60
61
62
def find_runtime_by_fingerprint(fingerprint: str) -> Path | None:
    """Find newest installed runtime matching fingerprint."""
    runtimes = list_installed_runtimes()
    matching = [r for r in runtimes if fingerprint in r.name]
    if not matching:
        return None
    # Sort by name (which includes version) and return newest
    return sorted(matching, reverse=True)[0]

read_stored_hash(path)

Read hash file from runtime directory.

Source code in brmspy/_runtime/_storage.py 
65
66
67
68
69
70
def read_stored_hash(path: Path) -> str | None:
    """Read hash file from runtime directory."""
    hash_path = path / "hash"
    if not hash_path.is_file():
        return None
    return hash_path.read_text(encoding="utf-8").strip()

write_stored_hash(path, hash_value)

Write hash file to runtime directory.

Source code in brmspy/_runtime/_storage.py 
73
74
75
76
def write_stored_hash(path: Path, hash_value: str) -> None:
    """Write hash file to runtime directory."""
    hash_path = path / "hash"
    hash_path.write_text(hash_value.strip() + "\n", encoding="utf-8")

install_from_archive(archive, fingerprint, version)

Extract archive to runtime directory. Returns path to installed runtime.

Source code in brmspy/_runtime/_storage.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def install_from_archive(
    archive: Path,
    fingerprint: str,
    version: str,
) -> Path:
    """
    Extract archive to runtime directory.
    Returns path to installed runtime.
    """
    import time

    base_dir = get_runtime_base_dir()
    is_windows = get_os() == "windows"
    runtime_root = get_runtime_path(fingerprint, version, allow_existing=not is_windows)

    # Extract to temp directory first
    temp_extract_root = base_dir / "_tmp_extract"
    if temp_extract_root.exists():
        shutil.rmtree(temp_extract_root)
    temp_extract_root.mkdir(parents=True, exist_ok=True)

    try:
        with tarfile.open(archive, mode="r:*") as tf:
            # 'data' filter breaks on windows and python 3.14 demands a filter.
            # fully_trusted is least error prone for now
            tf.extractall(path=temp_extract_root, filter="fully_trusted")

        # Find the runtime directory in extracted content
        runtime_tmp = temp_extract_root / "runtime"
        if not runtime_tmp.is_dir():
            raise RuntimeError(
                f"Extracted archive does not contain 'runtime/' under {temp_extract_root}"
            )

        # Validate manifest
        manifest_path = runtime_tmp / "manifest.json"
        if not manifest_path.is_file():
            raise RuntimeError(f"Missing manifest.json in {runtime_tmp}")

        # Remove existing runtime if present - critical for Windows!
        # On Windows, if runtime_root exists and rmtree fails silently,
        # shutil.move() will place runtime_tmp INSIDE runtime_root instead of replacing it.
        if runtime_root.exists():
            shutil.rmtree(runtime_root, ignore_errors=False)
            # Wait for deletion to complete on Windows (file locking issues)
            for _ in range(10):
                if not runtime_root.exists():
                    break
                time.sleep(0.1)

        # Move to final location
        shutil.move(str(runtime_tmp), str(runtime_root))

    finally:
        shutil.rmtree(temp_extract_root, ignore_errors=True)

    return runtime_root

install_from_directory(source, fingerprint, version)

Copy/move directory to runtime location. Returns path to installed runtime.

Source code in brmspy/_runtime/_storage.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def install_from_directory(
    source: Path,
    fingerprint: str,
    version: str,
) -> Path:
    """
    Copy/move directory to runtime location.
    Returns path to installed runtime.
    """
    runtime_root = get_runtime_path(fingerprint, version)

    # Validate manifest
    manifest_path = source / "manifest.json"
    if not manifest_path.is_file():
        raise RuntimeError(f"Missing manifest.json in {source}")

    source = source.resolve()
    runtime_root = runtime_root.resolve()

    # If already in place, just return
    if source == runtime_root:
        return runtime_root

    # Remove existing runtime if present
    if runtime_root.exists():
        shutil.rmtree(runtime_root, ignore_errors=True)

    # Move to final location
    shutil.move(str(source), str(runtime_root))

    return runtime_root

remove_runtime(path)

Remove installed runtime directory.

Source code in brmspy/_runtime/_storage.py 
171
172
173
174
def remove_runtime(path: Path) -> None:
    """Remove installed runtime directory."""
    if path.exists() and path.is_dir():
        shutil.rmtree(path)