Configuration

SMufoLib can be configured using an INI-style file discoverable from multiple locations. When more than one file is present, the settings from these files are layered to produce the final configuration.

Configurations are read and parsed using the config module and may be loaded as a dict object by calling the load() function.

load(path: Path | str | None = None) → dict[str, Any][source]

Load parsed config file as dict.

If path is not provided, configuration is obtained by searching the standard locations described in the user guide (see Configuring SMufoLib). Files found later in the search order override earlier ones.

If path is provided, only that file is loaded.

Parameters:: path – Path to the .cfg configuration file. Defaults to None.

Example:

>>> from smufolib import config
>>> cfg = config.load()
>>> cfg["request"]
{'encoding': 'utf-8', 'warn': True}

SMUFOLIB_CFG

If set, this environment variable overrides the default configuration file path. Use it to specify a custom configuration file location. The value should be an absolute or relative path to the .cfg configuration file.

For example:

export SMUFOLIB_CFG=/path/to/custom/smufolib.cfg

About Configuration File Naming

Configuration files located at the current working directory or the home directory must be named smufolib.cfg to be discovered automatically.

This restriction does not apply to explicitly provided paths, which may point to files with any name.

Sections and Options

The following sections and options may be overridden in a SMufoLib configuration file (smufolib.cfg):

request

This section contains configuration for the Request class.

[request]
encoding = utf-8
warn = true

request.encoding

Type:: str
Default:: utf-8

The default encoding used for Request.

request.warn

Type:: bool
Default:: true

Whether to issue warnings for Request.

metadata.paths

Primary metadata paths are configured in this section.

Relative paths declared in this section are resolved to absolute paths based on their parent directories, ensuring valid references for local metadata resources.

[metadata.paths]
directory = https://raw.githubusercontent.com/w3c/smufl/gh-pages/metadata/
classes = ${directory}classes.json
glyphnames = ${directory}glyphnames.json
ranges = ${directory}ranges.json
font = https://raw.githubusercontent.com/steinbergmedia/
        bravura/master/redist/bravura_metadata.json

metadata.paths.directory

Type:: str
Default:: https://raw.githubusercontent.com/w3c/smufl/gh-pages/metadata/

The base directory for metadata paths. This may be used to construct the full paths for metadata files using configparser.ExtendedInterpolation (${directory}).

metadata.paths.classes

Type:: str
Default:: ${directory}classes.json

The primary path to the classes metadata file.

metadata.paths.glyphnames

Type:: str
Default:: ${directory}glyphnames.json

The primary path to the glyph names metadata file.

metadata.paths.ranges

Type:: str
Default:: ${directory}ranges.json

The primary path to the ranges metadata file.

metadata.paths.font

Type:: str
Default:: ${directory}font.json

The primary path to the font metadata file.

metadata.fallbacks

Optional metadata fallback paths are configured in this section.

Fallbacks are used when the primary metadata files cannot be loaded (e.g., due to offline usage)

Like metadata.paths, relative paths in this section are resolved based on their parent directory.

[metadata.fallbacks]
directory = ./metadata/
classes = ${directory}classes.json
glyphnames = ${directory}glyphnames.json
ranges = ${directory}ranges.json
font = ${directory}bravura_metadata.json

metadata.fallbacks.directory

Type:: str
Default:: ./metadata/

The base directory for metadata fallbacks. This may be used to construct the full paths for metadata files using configparser.ExtendedInterpolation (${directory}).

metadata.fallbacks.classes

Type:: str
Default:: ${directory}classes.json

The fallback path to the classes metadata file.

metadata.fallbacks.glyphnames

Type:: str
Default:: ${directory}glyphnames.json

The fallback path to the glyph names metadata file.

metadata.fallbacks.ranges

Type:: str
Default:: ${directory}ranges.json

The fallback path to the ranges metadata file.

metadata.fallbacks.font

Type:: str
Default:: ${directory}font.json

The fallback path to the font metadata file.

cli

This section contains general configuration for the CLI Framework.

[cli]
markRequired = true

cli.markRequired

Type:: bool
Default:: true

Whether to append (required) to the help message of REQUIRED arguments. CLI Framework options.

cli.shortFlags

Short flags for CLI Framework options to be used with commonParser() are configured in this section.

[cli.shortFlags]
attributes = -a
classesData = -C
clear = -x
color = -c
colors = -c
exclude = -e
font = -f
fontData = -F
glyphnamesData = -G
include = -i
includeOptionals = -O
mark = -m
overwrite = -o
rangesData = -r
sourcePath = -S
spaces = -s
targetPath = -T
verbose = -v

cli.shortFlags.attributes

Type:: str
Default:: -a

Short flag equivalent to the --attributes option in the CLI Framework.

cli.shortFlags.classesData

Type:: str
Default:: -C

Short flag equivalent to the --classes-data option in the CLI Framework.

cli.shortFlags.clear

Type:: str
Default:: -x

Short flag equivalent to the --clear option in the CLI Framework.

cli.shortFlags.color

Type:: str
Default:: -c

Short flag equivalent to the --color option in the CLI Framework.

cli.shortFlags.colors

Type:: str
Default:: -c

Short flag equivalent to the --colors option in the CLI Framework.

cli.shortFlags.exclude

Type:: str
Default:: -e

Short flag equivalent to the --exclude option in the CLI Framework.

cli.shortFlags.font

Type:: str
Default:: -f

Short flag equivalent to the --font option in the CLI Framework.

cli.shortFlags.fontData

Type:: str
Default:: -F

Short flag equivalent to the --font-data option in the CLI Framework.

cli.shortFlags.glyphnamesData

Type:: str
Default:: -G

Short flag equivalent to the --glyphnames-data option in the CLI Framework.

cli.shortFlags.include

Type:: str
Default:: -i

Short flag equivalent to the --include option in the CLI Framework.

cli.shortFlags.includeOptionals

Type:: str
Default:: -O

Short flag equivalent to the --include-optionals option in the CLI Framework.

cli.shortFlags.mark

Type:: str
Default:: -m

Short flag equivalent to the --mark option in the CLI Framework.

cli.shortFlags.overwrite

Type:: str
Default:: -o

Short flag equivalent to the --overwrite option in the CLI Framework.

cli.shortFlags.rangesData

Type:: str
Default:: -r

Short flag equivalent to the --ranges-data option in the CLI Framework.

cli.shortFlags.sourcePath

Type:: str
Default:: -S

Short flag equivalent to the --source-path option in the CLI Framework.

cli.shortFlags.spaces

Type:: str
Default:: -s

Short flag equivalent to the --spaces option in the CLI Framework.

cli.shortFlags.targetPath

Type:: str
Default:: -T

Short flag equivalent to the --target-path option in the CLI Framework.

cli.shortFlags.verbose

Type:: str
Default:: -v

Short flag equivalent to the --verbose option in the CLI Framework.

color.marks

Color values for glyph marks are configured in this section.

[color.marks]
# Red
mark1 = (1.0, 0.0, 0.0, 1.0)
# Green
mark2 = (0.0, 1.0, 0.0, 1.0)
# Blue
mark3 = (0.0, 0.0, 1.0, 1.0)

color.marks.mark1

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (1.0, 0.0, 0.0, 1.0)

The primary mark color.

color.marks.mark2

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 1.0, 0.0, 1.0)

The secondary mark color.

color.marks.mark3

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 0.0, 1.0, 1.0)

The tertiary mark color.

color.anchors

Color values for glyph anchors are configured in this section.

[color.anchors]
# Yellow
cutOutNE = (1.0, 1.0, 0.0, 1.0)
# Magenta
cutOutNW = (1.0, 0.0, 1.0, 1.0)
# Cyan
cutOutSE = (0.0, 1.0, 1.0, 1.0)
# Dark Red
cutOutSW = (0.5, 0.0, 0.0, 1.0)
# Dark Green
graceNoteSlashNE = (0.0, 0.5, 0.0, 1.0)
# Dark Blue
graceNoteSlashNW = (0.0, 0.0, 0.5, 1.0)
# Olive
graceNoteSlashSE = (0.5, 0.5, 0.0, 1.0)
# Purple
graceNoteSlashSW = (0.5, 0.0, 0.5, 1.0)
# Teal
nominalWidth = (0.0, 0.5, 0.5, 1.0)
# Orange
noteheadOrigin = (1.0, 0.5, 0.0, 1.0)
# Lime
numeralBottom = (0.5, 1.0, 0.0, 1.0)
# Sky Blue
numeralTop = (0.0, 0.5, 1.0, 1.0)
# Violet
opticalCenter = (0.5, 0.0, 1.0, 1.0)
# Rose
repeatOffset = (1.0, 0.0, 0.5, 1.0)
# Spring Green
splitStemDownNE = (0.0, 1.0, 0.5, 1.0)
# Gray
splitStemDownNW = (0.5, 0.5, 0.5, 1.0)
# Light Gray
splitStemUpSE = (0.75, 0.75, 0.75, 1.0)
# Dark Gray
splitStemUpSW = (0.25, 0.25, 0.25, 1.0)
# Brown
stemDownNW = (0.8, 0.6, 0.4, 1.0)
# Dark Brown
stemDownSW = (0.6, 0.4, 0.2, 1.0)
# Steel Blue
stemUpNW = (0.2, 0.4, 0.6, 1.0)
# Light Steel Blue
stemUpSE = (0.4, 0.6, 0.8, 1.0)

color.anchors

Type:: dict[str, tuple[int | float, int | float, int | float, int | float]]
Default:: {<anchorName>: (r, g, b, a)}

A dictionary mapping anchor names to their corresponding RGBA color values. Each key is the name of an anchor (e.g., cutOutNE, graceNoteSlashNW), and each value is a 4-tuple representing red, green, blue, and alpha channel values.

Individual anchor colors may also be referenced as distinct configuration values (e.g., color.anchors.cutOutNE) for documentation or override purposes.

color.anchors.cutOutNE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (1.0, 1.0, 0.0, 1.0)

The default color for anchor cutOutNE, used in color.anchors.

color.anchors.cutOutNW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (1.0, 0.0, 1.0, 1.0)

The default color for anchor cutOutNW, used in color.anchors.

color.anchors.cutOutSE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 1.0, 1.0, 1.0)

The default color for anchor cutOutSE, used in color.anchors.

color.anchors.cutOutSW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.5, 0.0, 0.0, 1.0)

The default color for anchor cutOutSW, used in color.anchors.

color.anchors.graceNoteSlashNE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 0.5, 0.0, 1.0)

The default color for anchor graceNoteSlashNE, used in color.anchors.

color.anchors.graceNoteSlashNW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 0.0, 0.5, 1.0)

The default color for anchor graceNoteSlashNW, used in color.anchors.

color.anchors.graceNoteSlashSE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.5, 0.5, 0.0, 1.0)

The default color for anchor graceNoteSlashSE, used in color.anchors.

color.anchors.graceNoteSlashSW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.5, 0.0, 0.5, 1.0)

The default color for anchor graceNoteSlashSW, used in color.anchors.

color.anchors.nominalWidth

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 0.5, 0.5, 1.0)

The default color for anchor nominalWidth, used in color.anchors.

color.anchors.noteheadOrigin

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (1.0, 0.5, 0.0, 1.0)

The default color for anchor noteheadOrigin, used in color.anchors.

color.anchors.numeralBottom

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.5, 1.0, 0.0, 1.0)

The default color for anchor numeralBottom, used in color.anchors.

color.anchors.numeralTop

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 0.5, 1.0, 1.0)

The default color for anchor numeralTop, used in color.anchors.

color.anchors.opticalCenter

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.5, 0.0, 1.0, 1.0)

The default color for anchor opticalCenter, used in color.anchors.

color.anchors.repeatOffset

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (1.0, 0.0, 0.5, 1.0)

The default color for anchor repeatOffset, used in color.anchors.

color.anchors.splitStemDownNE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.0, 1.0, 0.5, 1.0)

The default color for anchor splitStemDownNE, used in color.anchors.

color.anchors.splitStemDownNW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.5, 0.5, 0.5, 1.0)

The default color for anchor splitStemDownNW, used in color.anchors.

color.anchors.splitStemUpSE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.75, 0.75, 0.75, 1.0)

The default color for anchor splitStemUpSE, used in color.anchors.

color.anchors.splitStemUpSW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.25, 0.25, 0.25, 1.0)

The default color for anchor splitStemUpSW, used in color.anchors.

color.anchors.stemDownNW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.8, 0.6, 0.4, 1.0)

The default color for anchor stemDownNW, used in color.anchors.

color.anchors.stemDownSW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.6, 0.4, 0.2, 1.0)

The default color for anchor stemDownSW, used in color.anchors.

color.anchors.stemUpNW

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.2, 0.4, 0.6, 1.0)

The default color for anchor stemUpNW, used in color.anchors.

color.anchors.stemUpSE

Type:: tuple[int | float, int | float, int | float, int | float]
Default:: (0.4, 0.6, 0.8, 1.0)

The default color for anchor stemUpSE, used in color.anchors.

engravingDefaults

This section contains configuration for the EngravingDefaults class.

[engravingDefaults]
auto = true

engravingDefaults.auto

Type:: bool
Default:: true

Whether to calculate engraving defaults automatically.

ranges

This section contains configuration related to the functionality, generation and modification of Range objects.

[ranges]
editable = false

ranges.editable

Type:: bool
Default:: false

Whether to allow creation or editing of glyph ranges.

classes

This section contains configuration related to Smufl.classes.

[classes]
strict = true

classes.strict

Type:: bool
Default:: true

Whether to enforce SMuFL-specific CLASS_NAMES or allow custom names.