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 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 | false | Enable MPI detection. When set to true, bamboost checks for standard MPI launcher environment variables and initialises mpi4py if found. |
sortTableKey | str | "created_at" | Default column used to sort the collection DataFrame. |
sortTableOrder | str | "desc" | Sort order for the table: "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 used when bamboost is waiting to acquire an HDF5 file lock. |
file_lock_timeout | float|null | 60.0 | Seconds to wait for an HDF5 file lock before raising TimeoutError. Set to 0 to fail immediately; set to null (or a negative value) to wait indefinitely. |
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 without replacing it. |
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 (used when not in isolated mode). |
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 database fileYou can override individual options at runtime before creating any Collection
or Index objects:
from bamboost import config
config.options.logLevel = "DEBUG"
config.index.syncTables = FalseSetting config.options.mpi = True at runtime will also re-trigger MPI detection
immediately (if bamboost.mpi has already been imported).
Isolated 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