# configTools

Code of the config system; not related to fontTools or fonts in particular.

The options that are specific to fontTools are in `fontTools.config`.

To create your own config system, you need to create an instance of `Options`, and a subclass of `AbstractConfig` with its `options` class variable set to your instance of Options.

class fontTools.misc.configTools.AbstractConfig(values: Union[AbstractConfig, Dict[Union[Option, str], Any]] = {}, parse_values: bool = False, skip_unknown: bool = False)

  Create a set of config values, optionally pre-filled with values from the given dictionary or pre-existing config object.

  The class implements the MutableMapping protocol keyed by option name (str). For convenience its methods accept either Option or str as the key parameter.

  See also

  `set()`

  This config class is abstract because it needs its `options` class var to be set to an instance of `Options` before it can be instanciated and used.

      class MyConfig(AbstractConfig):
          options = Options()

      MyConfig.register_option( "test:option_name", "This is an option", 0, int, lambda v: isinstance(v, int))

      cfg = MyConfig({"test:option_name": 10})

  clear() → None. Remove all items from D.
  copy()
  get(option_or_name: ~typing.Union[~fontTools.misc.configTools.Option, str], default: ~typing.Any = <object object>) → Any

    Get the value of an option. The value which is returned is the first provided among:

    1. a user-provided value in the options’s `self._values` dict

    2. a caller-provided default value to this method call

    3. the global default for the option provided in `fontTools.config`

    This is to provide the ability to migrate progressively from config options passed as arguments to fontTools APIs to config options read from the current TTFont, e.g.

        def fontToolsAPI(font, some_option):
            value = font.cfg.get("someLib.module:SOME_OPTION", some_option)
            # use value

    That way, the function will work the same for users of the API that still pass the option to the function call, but will favour the new config mechanism if the given font specifies a value for that option.

  items() → a set-like object providing a view on D's items
  keys() → a set-like object providing a view on D's keys
  options: ClassVar[Options]
  pop(k[, d]) → v, remove specified key and return the corresponding value.

    If key is not found, d is returned if given, otherwise KeyError is raised.

  popitem() → (k, v), remove and return some (key, value) pair

    as a 2-tuple; but raise KeyError if D is empty.

  classmethod register_option(name: str, help: str, default: Any, parse: Callable[[str], Any], validate: Optional[Callable[[Any], bool]] = None) → Option

    Register an available option in this config system.

  set(option_or_name: Union[Option, str], value: Any, parse_values: bool = False, skip_unknown: bool = False)

    Set the value of an option.

    Parameters

      - option_or_name (*) – an Option object or its name (str).

      - value (*) – the value to be assigned to given option.

      - parse_values (*) – parse the configuration value from a string into its proper type, as per its Option object. The default behavior is to raise ConfigValueValidationError when the value is not of the right type. Useful when reading options from a file type that doesn’t support as many types as Python.

      - skip_unknown (*) – skip unknown configuration options. The default behaviour is to raise ConfigUnknownOptionError. Useful when reading options from a configuration file that has extra entries (e.g. for a later version of fontTools)

  setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  update([E, ]**F) → None. Update D from mapping/iterable E and F.

    If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

  values() → an object providing a view on D's values

exception fontTools.misc.configTools.ConfigAlreadyRegisteredError(name)

  Raised when a module tries to register a configuration option that already exists.

  Should not be raised too much really, only when developing new fontTools modules.

  add_note()

    Exception.add_note(note) – add a note to the exception

  args
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fontTools.misc.configTools.ConfigError

  Base exception for the config module.

  add_note()

    Exception.add_note(note) – add a note to the exception

  args
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fontTools.misc.configTools.ConfigUnknownOptionError(option_or_name)

  Raised when a configuration option is unknown.

  add_note()

    Exception.add_note(note) – add a note to the exception

  args
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fontTools.misc.configTools.ConfigValueParsingError(name, value)

  Raised when a configuration value cannot be parsed.

  add_note()

    Exception.add_note(note) – add a note to the exception

  args
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fontTools.misc.configTools.ConfigValueValidationError(name, value)

  Raised when a configuration value cannot be validated.

  add_note()

    Exception.add_note(note) – add a note to the exception

  args
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class fontTools.misc.configTools.Option(name: 'str', help: 'str', default: 'Any', parse: 'Callable[[str], Any]', validate: 'Optional[Callable[[Any], bool]]' = None)
  default: Any

    Default value for this option.

  help: str

    Help text for this option.

  name: str

    MY_OPTION).

    Type

      Unique name identifying the option (e.g. package.module

  parse: Callable[[str], Any]

    Turn input (e.g. string) into proper type. Only when reading from file.

  static parse_optional_bool(v: str) → Optional[bool]
  validate: Optional[Callable[[Any], bool]] = None

    Return true if the given value is an acceptable value.

  static validate_optional_bool(v: Any) → bool

class fontTools.misc.configTools.Options(other: Options = None)

  Registry of available options for a given config system.

  Define new options using the `register()` method.

  Access existing options using the Mapping interface.

  get(k[, d]) → D[k] if k in D, else d. d defaults to None.
  is_registered(option: Option) → bool

    Return True if the same option object is already registered.

  items() → a set-like object providing a view on D's items
  keys() → a set-like object providing a view on D's keys
  register(name: str, help: str, default: Any, parse: Callable[[str], Any], validate: Optional[Callable[[Any], bool]] = None) → Option

    Create and register a new option.

  register_option(option: Option) → Option

    Register a new option.

  values() → an object providing a view on D's values