API Reference

The intended interaction with ComfyParse is to create a ComfyParser instance, populate its schema with blocks and settings, and then parse one or more configuration documents with it to receive a Namespace object containing the parsed, validated, and converted configuration within those documents.

class comfyparse.ComfyParser(name: str | None = None, desc: str = '')

Creates a new ComfyParser object.

add_block(kind: str, named: bool = False, desc: str = '', required: bool = False, validate: Callable[[Namespace], bool] | None = None) → ConfigBlock

Define and return a new global configuration block.

Parameters:

  • kind – The identifier for the block.

  • named – If True, multiple instances of a block can be included at the global configuration level. Each instance must include an additional name identifier to distinguish them. (Default False)

  • desc – A description of the block. Included in automatic documentation.

  • required – Whether the block may be omitted. (Default False)

  • validate – Optionally, a callable which accepts the block after each field has been validated and returns whether or not is is valid.

Raises:

comfyparse.config.ConfigSpecError – Raised if the kind identifier is already in use.

The returned configuration block similarly supports the add_setting and add_block methods to allow for hierarchical configuration construction.

add_setting(name: str, desc: str = '', required: bool = False, default: Any | None = None, choices: Sequence | None = None, convert: Callable[[list | str], Any] | None = None, validate: Callable[[Any], bool] | None = None) → None

Define a new global setting.

Parameters:

  • name – The name of this setting.

  • desc – A description of the setting. Included in automatic documentation.

  • required – Whether the setting may be omitted. (Default False)

  • default – A value to use when the setting is omitted from a configuration.

  • choices – Optionally, a list of allowed values for the setting.

  • convert – Optionally, a callable which accepts the raw parsed value and returns an object of the appropriate type.

  • validate – Optionally, a callable which accepts the (potentially converted) value and returns whether or not it is a valid value for the setting.

Raises:

comfyparse.config.ConfigSpecError – Raised if the name is already in use.

generate_docs() → str

Returns a reStructuredText string consisting of documentation for the configuration’s supported blocks and settings.

parse_config_file(path: str, validate: bool = True) → Namespace

Open and parse the contents of the given file path, returning the resulting configuration Namespace.

parse_config_files(paths: list[str]) → Namespace

Given a list of file paths, open and parse each, combining the results into a single Namespace before returning the validated configuration Namespace.

parse_config_string(data: str, validate: bool = True) → Namespace

Parse the contents of the given string, returning the resulting configuration Namespace. Setting validate to False omits the validation and conversion operations. This can be useful when constructing a configuration from multiple sources, where validation should only be invoked after the complete configuration object has been assembled, such as in ComfyParser.parse_config_files().

validate(config: Namespace) → Namespace

Given an unvalidated Namespace, perform validation and return the resulting converted Namespace.

class comfyparse.Namespace(name: str | None = None, **kwargs)

A dict wrapper for allowing both indexing-based and attribute-based access to contents.

Parameters:

  • name – An optional name to help identify the namespace.

  • kwargs – All keyword arguments are treated as entries in the internally-managed dictionary.

copy() → Namespace

Return a new Namespace which is a copy of this one.

get(key: str, default: Any | None = None) → Any

Return the given key if it exists within this Namespace, otherwise return the value of default.

keys()

Return all keys within the Namespace.

merge(other: Namespace) → None

Merges the contents of other into this Namespace.

Exceptions

The following custom exception types may occur when using ComfyParse:

class comfyparse.parser.ParseError

Raised when encountering an issue during parsing.

class comfyparse.config.ConfigSpecError

Raised when an error occurs while adding a new setting or block.

class comfyparse.config.ValidationError

Raised when a block or setting’s value fail to validate.

Internals

You shouldn’t need to interact with these components directly, but they are documented here for the sake of completeness.

class comfyparse.config.ConfigSetting(name: str, desc: str = '', required: bool = False, default: Any | None = None, choices: Sequence | None = None, convert: Callable[[list | str], Any] | None = None, validate: Callable[[Any], bool] | None = None)

Defines the specification for a single configuration setting.

Parameters:

  • name – The name of this setting.

  • desc – A description of the setting. Included in automatic documentation.

  • required – Whether the setting may be omitted. (Default False)

  • default – A value to use when the setting is omitted from a configuration.

  • choices – Optionally, a list of allowed values for the setting.

  • convert – Optionally, a callable which accepts the raw parsed value and returns an object of the appropriate type.

  • validate – Optionally, a callable which accepts the (potentially converted) value and returns whether or not it is a valid value for the setting.

render_as_table_row(name_width: int, default_width: int) → str

Renders the setting’s parameters as a string for inclusion in the table generated by ConfigBlock.generate_docs() which contains this setting.

validate_value(raw_value: str | None = None) → Any

Returns a validated and optionally converted value from a raw value (or None)

class comfyparse.config.ConfigBlock(kind: str, named: bool = False, desc: str = '', required: bool = False, validate: Callable[[Namespace], bool] | None = None)

Defines a configuration block.

Parameters:

  • kind – The identifier for the block.

  • named – If True, multiple instances of a block can be included at the global configuration level. Each instance must include an additional name identifier to distinguish them. (Default False)

  • desc – A description of the block. Included in automatic documentation.

  • required – Whether the block may be omitted. (Default False)

  • validate – Optionally, a callable which accepts the block after each field has been validated and returns whether or not is is valid.

add_block(kind: str, named: bool = False, desc: str = '', required: bool = False, validate: Callable[[Namespace], bool] | None = None) → ConfigBlock

Define and return a new configuration block nested within this block.

Parameters:

  • kind – The identifier for the block.

  • named – If True, multiple instances of a block can be included at the global configuration level. Each instance must include an additional name identifier to distinguish them. (Default False)

  • desc – A description of the block. Included in automatic documentation.

  • required – Whether the block may be omitted. (Default False)

  • validate – Optionally, a callable which accepts the block after each field has been validated and returns whether or not is is valid.

Raises:

comfyparse.config.ConfigSpecError – Raised if the kind identifier is already in use within this block.

Returns:

The newly defined block.

Return type:

ConfigBlock

The returned configuration block similarly supports the add_setting and add_block methods to allow for hierarchical configuration construction.

add_setting(name: str, desc: str = '', required: bool = False, default: Any | None = None, choices: Sequence | None = None, convert: Callable[[list | str], Any] | None = None, validate: Callable[[Any], bool] | None = None) → None

Define a new configuration setting within this block.

Parameters:

  • name – The name of this setting.

  • desc – A description of the setting. Included in automatic documentation.

  • required – Whether the setting may be omitted. (Default False)

  • default – A value to use when the setting is omitted from a configuration.

  • choices – Optionally, a list of allowed values for the setting.

  • convert – Optionally, a callable which accepts the raw parsed value and returns an object of the appropriate type.

  • validate – Optionally, a callable which accepts the (potentially converted) value and returns whether or not it is a valid value for the setting.

Raises:

comfyparse.config.ConfigSpecError – Raised if the name is already in use within this block.

generate_docs(level: int = 0) → str

Returns a reStructuredText string containing documentation for this block and its settings, as well as the documentation of its child blocks.

validate_block(block: Namespace) → Namespace

Returns a validated copy of the given block with all child blocks and settings validated. Settings values in the returned Namespace will also have been converted if a convert callable was defined for them.

class comfyparse.lexer.ComfyLexer(source: str)

Defines a ComfyLexer instance. Use peek() and consume() to access token objects. Delays tokenization until explicitly requested, or a method is used which requires tokens to have been generated.

Parameters:

source – The source string to render into tokens.

consume() → Token

Return the current token and increment the token position.

is_exhausted() → bool

Return whether or not all tokens have been consumed.

peek(offset: int = 0) → Token

Return the token at the current token pointer plus an optional offset. Does not affect the current token pointer.

tokenize() → None

Explicitly invoke tokenization of the input source.