Miscellaneous: Config and Exceptions

This section covers two minor parts of the API that can be useful when writing programs with FluidPatcher:

  • Managing the global configuration file
  • Exceptions raised when a bank file fails to load

Global Configuration

FluidPatcher configuration is stored at ~/.config/fluidpatcher/fluidpatcherconf.yaml, or the location referenced by the environment variable FLUIDPATCHER_CONFIG if set.

Loading Config

Loading happens once at import, and the data is stored in the global variable CONFIG. When loading, any key ending in _path is automatically converted into a pathlib.Path object internally, so paths behave consistently across platforms.

Bank File Errors

All bank-related errors derive from a single base class BankError. This makes it easy to catch any bank failure at a high level, while still getting detailed diagnostics.

fluidpatcher.bankfiles.BankSyntaxError

Error raised when the YAML text is malformed and cannot be parsed.

Attributes:
  • msg (str) –

    Reason for failure

  • mark (tuple) –

    YAML mark object describing the error

This error means the YAML itself is improperly formatted.

Typical issues include:

  • Bad indentation
  • Missing colons
  • Unterminated flow mappings
  • Invalid YAML literals

When possible, the error includes line and column information pointing directly at the problem.

Example output:

mapping values are not allowed here at line 27, column 14

This error happens before fluidpatcher looks at musical meaning— nothing in the file is interpreted yet.

fluidpatcher.bankfiles.BankValidationError

Raised when a bank file is valid YAML but contains incorrect or unsupported values.

Attributes:
  • msg (str) –

    Reason for failure

  • path (tuple) –

    Hierarchical path to the failing node

This error means the YAML is valid, but the contents don’t make sense to fluidpatcher.

Common causes include:

  • Missing required keys
  • Unknown rule or message types
  • Invalid parameter ranges
  • Null values (not allowed)

Validation errors include a path that points to the failing node in the bank structure.

Example output:

MidiRule type 'ntoe' not recognized in patches.Rhodes.rules.2

This tells you exactly where fluidpatcher gave up, without requiring guesswork.

Summary

  • Global config can be modified and store state variables
  • Bank files are validated strictly, with clear diagnostics
  • Syntax errors mean “bad YAML”
  • Validation errors mean “valid YAML, wrong meaning”