Skip to content

Backends

qcstore.Backend

The operations a store needs of the medium holding its files.

Paths are relative POSIX paths. Names starting with . are the backend's own (temporary files) and never listed.

append

append(path: str, data: bytes) -> None

Append bytes to a file, creating it; each call's bytes stay contiguous.

Source code in src/qcstore/backend.py
51
52
53
def append(self, path: str, data: bytes) -> None:
    """Append bytes to a file, creating it; each call's bytes stay contiguous."""
    ...

delete

delete(path: str) -> None

Remove a file if it exists.

Source code in src/qcstore/backend.py
63
64
65
def delete(self, path: str) -> None:
    """Remove a file if it exists."""
    ...

exists

exists(path: str) -> bool

Whether a file or directory exists.

Source code in src/qcstore/backend.py
55
56
57
def exists(self, path: str) -> bool:
    """Whether a file or directory exists."""
    ...

get

get(path: str, start: int = 0) -> bytes

Return a file's bytes from offset start to its end.

Raises:

Type Description
FileNotFoundError

No such file.

Source code in src/qcstore/backend.py
28
29
30
31
32
33
34
def get(self, path: str, start: int = 0) -> bytes:
    """Return a file's bytes from offset ``start`` to its end.

    Raises:
        FileNotFoundError: No such file.
    """
    ...

list

list(path: str) -> list[str]

The names directly inside a directory, sorted; empty if it does not exist.

Source code in src/qcstore/backend.py
59
60
61
def list(self, path: str) -> list[str]:
    """The names directly inside a directory, sorted; empty if it does not exist."""
    ...

put

put(
    path: str, data: bytes, *, replace: bool = False
) -> None

Write a file atomically, creating its directories.

Parameters:

Name Type Description Default
path str

The file.

required
data bytes

Its contents.

required
replace bool

Replace the file if it exists. Otherwise an existing file is left as it is and FileExistsError raised: of two writers creating the same file, exactly one succeeds.

False

Raises:

Type Description
FileExistsError

The file exists and replace is False.

Source code in src/qcstore/backend.py
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def put(self, path: str, data: bytes, *, replace: bool = False) -> None:
    """Write a file atomically, creating its directories.

    Args:
        path: The file.
        data: Its contents.
        replace: Replace the file if it exists. Otherwise an existing file is left
            as it is and `FileExistsError` raised: of two writers creating the
            same file, exactly one succeeds.

    Raises:
        FileExistsError: The file exists and ``replace`` is False.
    """
    ...

qcstore.LocalBackend

LocalBackend(root: str | PathLike[str])

Files in a directory on a local disk or a network filesystem (NFS).

Writes go to a hidden temporary file beside the target, are flushed to disk, and are then renamed into place (to replace) or hard-linked into place (to create exclusively). Both are atomic on POSIX filesystems and on NFS, so concurrent writers on several machines need no locks.

Attributes:

Name Type Description
root Path

The store's directory.

Source code in src/qcstore/backend.py
80
81
82
def __init__(self, root: str | os.PathLike[str]) -> None:
    """Use the directory ``root``, created on the first write if needed."""
    self.root: Path = Path(root).expanduser().absolute()

append

append(path: str, data: bytes) -> None

Append bytes with one write to a file opened for appending.

Source code in src/qcstore/backend.py
117
118
119
120
121
122
123
124
125
126
127
def append(self, path: str, data: bytes) -> None:
    """Append bytes with one write to a file opened for appending."""
    target = self._path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    fd = os.open(target, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)
    try:
        written = os.write(fd, data)
        if written != len(data):  # pragma: no cover - a full disk
            raise OSError(f"Short write appending to {target}.")
    finally:
        os.close(fd)

delete

delete(path: str) -> None

Remove a file if it exists.

Source code in src/qcstore/backend.py
141
142
143
def delete(self, path: str) -> None:
    """Remove a file if it exists."""
    self._path(path).unlink(missing_ok=True)

exists

exists(path: str) -> bool

Whether a file or directory exists.

Source code in src/qcstore/backend.py
129
130
131
def exists(self, path: str) -> bool:
    """Whether a file or directory exists."""
    return self._path(path).exists()

get

get(path: str, start: int = 0) -> bytes

Return a file's bytes from offset start to its end.

Source code in src/qcstore/backend.py
94
95
96
97
98
def get(self, path: str, start: int = 0) -> bytes:
    """Return a file's bytes from offset ``start`` to its end."""
    with self._path(path).open("rb") as f:
        f.seek(start)
        return f.read()

list

list(path: str) -> list[str]

The visible names directly inside a directory, sorted.

Source code in src/qcstore/backend.py
133
134
135
136
137
138
139
def list(self, path: str) -> list[str]:
    """The visible names directly inside a directory, sorted."""
    try:
        names = os.listdir(self._path(path))
    except (FileNotFoundError, NotADirectoryError):
        return []
    return sorted(n for n in names if not n.startswith("."))

put

put(
    path: str, data: bytes, *, replace: bool = False
) -> None

Write a file atomically: a flushed temporary file, renamed or linked in.

Source code in src/qcstore/backend.py
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def put(self, path: str, data: bytes, *, replace: bool = False) -> None:
    """Write a file atomically: a flushed temporary file, renamed or linked in."""
    target = self._path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    temporary = target.with_name(f".{target.name}.{secrets.token_hex(4)}.tmp")
    with temporary.open("xb") as f:
        f.write(data)
        f.flush()
        os.fsync(f.fileno())
    try:
        if replace:
            os.replace(temporary, target)
        else:
            os.link(temporary, target)
    finally:
        temporary.unlink(missing_ok=True)