gbd_core.config

module documentation
(source)

GBD configuration system.

The central configuration is a TOML file registered via the GBD environment variable (or passed to -d/--db as a path). It may declare databases, contexts, extractors, and transformers. The bundled default_config.toml provides the built-in defaults, onto which any user configuration is merged.

Configuration layers are merged low-to-high precedence: bundled defaults < GBD env config < -d/--db config. The GBD config acts as a user-level default that a -d/--db config overrides. A -d/--db value is auto-detected as either a legacy colon-separated database list or a path to a central config file (see is_config_file); a legacy database list (or the GBD_DB environment variable) provides the databases when no config layer does.

Configuration file format

A GBD configuration is a TOML document with up to four top-level tables. A file is recognised as a config (rather than a database list) as soon as it contains at least one of them. All tables are optional; anything omitted keeps its bundled default.

[databases]

Extra databases loaded in addition to any given via -d/--db or GBD_DB.

  • paths (list of str): filesystem paths to SQLite database files.
[contexts]

Problem domains, keyed by context name. Each context maps a file suffix to the identifier (hash) function used for that domain.

  • default (str): the context assumed when none is given on the CLI.
  • <name> (table): a context definition with the keys
    • suffix (str): file-name suffix that identifies instances of this context (e.g. ".cnf").
    • idfunc (str): name of the hash function used to compute instance identifiers (e.g. "cnf_hash", "opb_hash", "wcnf_hash").
    • description (str): human-readable description.
[extractors]

Feature extractors: external command-line tools that compute features for an instance. Keyed by extractor name; each entry supports

  • tool (str): the command gbd runs. It may include a subcommand (e.g. "gbdc base") and is split with shell-like quoting.
  • contexts (list of str): contexts this extractor applies to.
  • description (str): human-readable description.
[transformers]

Instance transformers: external command-line tools that derive a new instance from an existing one. Keyed by transformer name; each entry supports

  • tool (str): the command gbd runs (see tool above).
  • source (list of str): contexts the transformer reads from.
  • target (list of str): contexts the transformer writes to.
  • output_suffix (str, optional): overrides the target context's suffix for the produced file.
  • compress (str, optional): compression for the produced file, one of none, xz, gz, bz2.
  • description (str): human-readable description.

Registry blocks ([extractors], [transformers]) may be defined inline, offloaded to a separate file via file = "...", or both (inline entries win on a name clash). When file is relative, it is resolved against the directory of the config that references it.

Example

[databases]
paths = ["/data/meta.db", "/data/features.db"]

[contexts]
default = "cnf"
cnf = { suffix = ".cnf", idfunc = "cnf_hash", description = "DIMACS CNF" }

[extractors]
# Inline entry ...
base = { tool = "gbdc base", contexts = ["cnf"], description = "Base features." }
# ... or offload the rest to a separate file (inline entries win on a clash):
file = "my_extractors.toml"

[transformers]
sanitise = { tool = "gbdc sanitize", source = ["cnf"], target = ["sancnf"], output_suffix = ".sanitized.cnf", compress = "xz", description = "Sanitise CNF files." }
Class GbdConfig Merged view of the GBD configuration (bundled defaults + user config layers).
Function default_config The configuration from the environment: bundled defaults plus the GBD config layer when it points to a valid config file.
Function is_config_file True if path is a single existing file that parses as a GBD TOML config (i.e. contains a known top-level table). A colon-separated list is legacy.
Function resolve_sources Resolve the ordered configuration layers and legacy database paths.
Function _deep_merge Recursively merge override onto base (override wins on conflicts).
Function _load_defaults Undocumented
Function _load_toml Undocumented
Function _named_tables Keep only the name -> table entries of a mapping.
Function _normalize Return a copy of a parsed config with registry file references resolved.
Function _read_toml Undocumented
Function _resolve_block Return a registry block's name -> table entries, resolving an optional file reference (inline entries win over referenced ones on a name clash).
Function _split_paths Undocumented
Constant _CONFIG_TABLES Undocumented
Constant _REGISTRY_BLOCKS Undocumented
def default_config() -> GbdConfig: (source)

The configuration from the environment: bundled defaults plus the GBD config layer when it points to a valid config file.

def is_config_file(path: str) -> bool: (source)

True if path is a single existing file that parses as a GBD TOML config (i.e. contains a known top-level table). A colon-separated list is legacy.

def resolve_sources(cli_db=None): (source)

Resolve the ordered configuration layers and legacy database paths.

Layers are returned low-to-high precedence and merged onto the bundled defaults: the GBD env config, then a -d/--db config. A legacy -d/--db list (or, as a last resort, GBD_DB) provides the databases when no config layer does.

Returns
tuple[list[str], list[str]](config_layers, db_paths).
def _deep_merge(base: dict, override: dict) -> dict: (source)

Recursively merge override onto base (override wins on conflicts).

def _load_defaults() -> dict: (source)

Undocumented

def _load_toml(path: str) -> dict: (source)

Undocumented

def _named_tables(mapping: dict) -> dict: (source)

Keep only the name -> table entries of a mapping.

def _normalize(raw: dict, base_dir: str) -> dict: (source)

Return a copy of a parsed config with registry file references resolved.

def _read_toml(fp): (source)

Undocumented

def _resolve_block(raw: dict, block: str, base_dir: str) -> dict: (source)

Return a registry block's name -> table entries, resolving an optional file reference (inline entries win over referenced ones on a name clash).

def _split_paths(value: str) -> list: (source)

Undocumented

_CONFIG_TABLES: tuple[str, ...] = (source)

Undocumented

Value
('databases', 'contexts', 'extractors', 'transformers')
_REGISTRY_BLOCKS: tuple[str, ...] = (source)

Undocumented

Value
('extractors', 'transformers')