BamboostConfiguration
bamboost reads configuration from two sources that are merged
together:
- A global config file at
~/.config/bamboost/config.toml - A project config file — either
bamboost.tomlor the[tool.bamboost]table inpyproject.toml, located at the project root (the nearest parent directory that contains.gitorpyproject.toml)
Project settings take precedence over global ones.
Config file format
Both files use TOML with two top-level tables:
[options] and [index].
[options]
logLevel = "WARNING"
sortTableKey = "created_at"
[index]
searchPaths = ["~/simulations", "/data/scratch/myuser"]
excludeDirs = [".git", ".venv", "__pycache__"][tool.bamboost.options]
logLevel = "DEBUG"
[tool.bamboost.index]
isolated = true[options]
logLevel = "DEBUG"
[index]
isolated = true[options] — Core options
| Key | Type | Default | Description |
|---|---|---|---|
mpi | bool | auto | Enable MPI support. Defaults to True if mpi4py is installed. |
sortTableKey | str | "created_at" | Default column used to sort the collection DataFrame. |
sortTableOrder | str | "desc" | Sort order: "asc" or "desc". |
logLevel | str | "WARNING" | Log verbosity: DEBUG, INFO, WARNING, ERROR, or CRITICAL. |
log_root_only | bool | false | If true, suppress log messages from non-root MPI ranks. |
log_file_lock_severity | str | "WARNING" | Log level for HDF5 file-lock retry messages. |
clipboardCommand | str|null | null | Shell command used to copy text to the clipboard (e.g. "wl-copy", "xclip -sel clip", "pbcopy"). Required for bamboost yank. |
[index] — Index options
| Key | Type | Default | Description |
|---|---|---|---|
searchPaths (alias: paths) | list[str] | ["~"] | Directories to scan when looking for bamboost collections. |
excludeDirs | list[str] | many | Directory names to skip during scanning (.git, venv, node_modules, …). |
extendDefaultExcludeDirs | list[str]|null | null | Extra directory names to add to the default exclude list. |
syncTables | bool | true | Keep the SQLite cache up to date after reads and writes. |
convertArrays | bool | true | Deserialise SQLite lists as numpy arrays. |
databaseFileName | str | "bamboost.0.11.sqlite" | Basename of the index database file. |
isolated | bool | false | Restrict the index to the current project directory and store the database under .bamboost/. |
strictLinks | bool | true | Raise an error when assigning a link whose target simulation is not found in the index. |
strictLinksWhenSyncing | bool | false | Apply strictLinks validation also during collection syncing. |
Reading config at runtime
The config object is a global singleton accessible from Python:
from bamboost import config
print(config.options.logLevel)
print(config.index.searchPaths)
print(config.index.databaseFile) # resolved path to the active databaseYou can override individual options at runtime before creating any
Collection or Index objects:
from bamboost import config
config.options.logLevel = "DEBUG"
config.index.syncTables = FalseIsolated mode
Setting isolated = true in your project config makes bamboost manage
a project-local index database. The database is stored at
.bamboost/bamboost.0.11.sqlite inside the project root, and the search
paths are automatically narrowed to the project root only.
This is useful when you want to keep project data completely
self-contained, for example when using bamboost as part of a
reproducible research repository.
[index]
isolated = true