Skip to content

feat: friendly error messages for builder validation failures #11

@genro

Description

@genro

Summary

Builder validation errors (sub_tags, parent_tags) currently raise raw Python ValueErrors with cryptic messages and full tracebacks. They should raise a specific exception with a clear, actionable message.

Current behavior

When a builder call violates the schema (e.g. adding a child to an element that does not allow children), the error is:

ValueError: 'None' not allowed as child of 'tree'

With a multi-frame traceback through builder internals that is hard to interpret.

Proposed behavior

A dedicated exception class with a clear message:

BuilderValidationError: element 'tree' cannot contain children (sub_tags="")
  at: tabpane > tree
  hint: 'tree' is a leaf element — pass data via attributes, not as child nodes

Design

New exception class

class BuilderValidationError(Exception):
    """Raised when a builder call violates the schema."""

Error messages should include

  • What failed: which element, which rule was violated
  • Where: the parent > child path in the recipe
  • Hint: actionable suggestion when possible

Cases to cover

  1. Child tag not allowed: "element 'foo' is not allowed as child of 'bar' (allowed: baz, qux)"
  2. Too many children of a type: "too many 'column' in 'datatable' (max: N)"
  3. No children allowed: "element 'tree' cannot contain children (sub_tags='')"
  4. Wrong parent: "element 'tabpane' must be inside 'tabbedcontent', found 'vertical'"

Files to modify

  • src/genro_builders/builder.py_validate_sub_tags, _validate_children_tags
  • src/genro_builders/__init__.py — export BuilderValidationError

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions