Skip to content

Error message fixes - #886

Merged
lognaturel merged 10 commits into
XLSForm:masterfrom
lindsay-stevens:error-message-fixes
Nov 10, 2026
Merged

lognaturel merged 10 commits into
XLSForm:masterfrom
lindsay-stevens:error-message-fixes

Conversation

@lindsay-stevens

@lindsay-stevens lindsay-stevens commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Why is this the best possible solution? Were any other approaches considered?

  • fixes some error messages with incorrect formatting tokens (curly braces) (recently added/unreleased).
  • fixes missing token values using the last-resort fallback "unknown" instead of something more useful, or at least an intentional "(unknown)" if a value isn't available in that context.
  • fixes usages of pre-formatted errors when raising a PyXFormError, which prevents adding/modifying context values if the error is caught elsewhere, prevents handling errors by code rather than an exact message or message fragment, makes it harder to spot missing or extra keys, etc.
    • currently not avoidable for warning messages though
  • fixes cases of missing format tokens, or extra format tokens

Not sure yet on the neatest way to fix this sort of thing more permanently (e.g. lint / mock / some other approach), but caught many of these issues by modifying the pyxform.errors._ErrorFormatter to a) raise an error instead of returning a default value, b) raise an error for unused keys.

L17 in get_value()

            if value is None:
                raise KeyError("Missing key")

L23 add implementation of no-op base method:

    def check_unused_args(self, used_args, args, kwargs):
        if len(used_args) < (len(args) + len(kwargs)):
            raise KeyError("Unused error args.")

Also considered adding PyxformTestCase options error__equals, warnings__equals, etc for when one specific error/warning is expected, to add to (and eventually replace) the looser "contains" methods. But that would be a larger refactor and not really in scope of this fixes PR.

What are the regression risks?

Some of the sheet misspelling messages were changed but hopefully they're clearer now, and the associated refactoring cleans up xls2json a bit.

Does this change require updates to documentation? If so, please file an issue here and include the link below.

No

Before submitting this PR, please make sure you have:

  • included test cases for core behavior and edge cases in tests
  • run python -m unittest and verified all tests pass
  • run ruff format pyxform tests and ruff check pyxform tests to lint code
  • verified that any code or assets from external sources are properly credited in comments

- impact is that users would see 'unknown' when the string was formatted
  for display e.g. "variable reference ('$unknown') must start".
- PYREF errors are meant to show the syntax so these braces are doubled.
- RANGE error seems to have been a typo (compared to adjacent errors).
- when called from section.py, validate_question_group_repeat_name isn't
  part of a call chain that has easy access to the 'warnings' list, so
  the local warnings list passed in goes nowhere. It is still useful
  to call this validator in case one of the errors is raised, but
  there is no need to create warning strings in that context.
- The string formats to "For internal API usage, may be due to a
  missing mapping for '(missing header)', in which case..." rather than
  using the fallback "unknown" e.g. "mapping for 'unknown', in ...".
- While no more useful than the default placeholder "unknown", it's at
  least explicit which makes it easier to find missing message tokens.
- pre-formatting makes it harder to find (or handle consistently)
  missing/unknown message context, vs. using PyXFormError formatting.
- a few other pre-formatting usages remain but they require less trivial
  refactoring to resolve, so are left for a later commit.
- pre-formatting is currently not avoidable when an ErrorCode is used
  for a warning message, since those strings are not processed further
  by pyxform.
- although it seems pycharm may not pick it up properly for working out
  what methods are available on the `Detail` class, annotating `_value_`
  seems to be the documented way, per:
  https://typing.python.org/en/latest/spec/enums.html
  "If an enum class provides an explicit type annotation for _value_,
  type checkers should enforce this declared type when values are
  assigned to _value_".
- conversely, pycharm flags the old annotations as an error, saying:
  "Type annotations are not allowed for enum members." and still doesn't
  work out the methods available on the `Detail` class.
- split duplicate choices error into two forms so that the formatting
  context can be provided for the errors module to use/inspect.
- maybe not ideal to have two almost identical error messages, but it
  seems better than:
  - having a new format token for "extra_message" then having a large
    inline message fragment i.e. the third line of the new message.
  - the current code which could be a wall of repeated text, whereas
    the new message just has a list of row numbers.
- for sheet misspelling errors and warnings
  - convert existing string concatenation to the distinct message forms
  - move the validation checks into new sheet_misspellings.py funcs
  - the messages SURVEY_013 and SURVEY_014 nominate a row since it
    seemed useful to point to the source of the error, which in the code
    is coming from a specific row while iterating the survey sheet.
  - the (external) choices messages don't mention columns anymore since
    that is checked in dealias_and_group_headers() and the criteria
    have changed as well (e.g. choices label not necessarily required).
- in errors.py, the addition of "field_names" allows checking what
  format tokens are in the message, but for now just using that to
  allow for the `SURVEY_011` message having no format tokens.
- update tests accordingly, in particular simplifying test_xls2json.py
  assertions since the full message is more specific than the fragments
  checked for previously.
- not necessarily a problem but at least from the calling side seems a
  bit confusing/misleading about what the message will convey, or which
  message was intended to be used.

@lognaturel lognaturel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oof, glad you caught this!

@lognaturel
lognaturel merged commit d46e9c3 into XLSForm:master Nov 10, 2026
14 checks passed
@lindsay-stevens
lindsay-stevens deleted the error-message-fixes branch November 10, 2026 10:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants