Documentation for psychopy.gui.Dlg outdated as of 2024.1.0, unannounced breaking change

[jfkominsky]

See https://discourse.psychopy.org/t/in-new-versions-dialog-box-functionality-has-been-broken/41036/2

In short, gui.Dlg has completely changed in a way that breaks most code that used it prior to 2024.1.0 by operating in dictionaries instead of lists. For all intents and purposes this deprecates and replaces gui.Dlg for coder experiments.

The ongoing issue is that the example in documentation is now just plain wrong and will not work, and needs to be updated: https://psychopy.org/api/gui.html#psychopy.gui.Dlg

I see the logic behind the change and I see why it's better in the long run, but it's a big breaking change for any existing code, in that any pre-2024 code that uses gui.Dlg is now inoperable and any post-2024 code will probably not be able to run in any pre-2024 version of PsychoPy. It's already done and it's straightforward (though a little bothersome) to update all my code, but it would have been nice to have some warning and maybe a little more consideration of the potential consequences of this change.

[peircej]

Hi there!

Sorry that the docs weren't updated.

We do try to warn people of major compatibility changes but I'm afraid this one was overlooked, mostly because not many people are hand-writing code and even fewer make use of the basic gui.Dlg (most would use DlgFromDict if hand-writing code). We do also, for sure, try to avoid changes to the API but there are times when these changes are necessary for new features. In this case we needed more flexible inputs to the dialog fields so that we could separate the displayed text from the input key (we have a new situation where there are tags on the field names that need tracking but shouldn't be displayed to the participant) and that necessitated this change.

[peircej]

To be fair, these twice-yearly major updates include a very large number of changes. 891 files were updated, with contributions from 28 authors in the 2024.1.0 release. So some things are likely to introduce breaking changes beyond our control

[jfkominsky]

I totally get it! The main reason not to use DlgFromDict is that it doesn't support static text fields (i.e., addText) and is more awkward for conditional field creation in a dialog box. I just happen to be in a weird position where I'm building on PsychoPy as a library for my own tool (PyHab) and happen to need to use a lot of these darn things. I think in the long run the change to a fully dict-based structure is definitely better, the only problem is what it does to existing experiment code.

6792 adding some backwards compatibility is appreciated. If it becomes fully backwards-compatible then most of the issue is moot, but the doc should still be updated.

[alexholcombe]

Thanks everyone! Just noting this is the same issue as https://github.com/psychopy/psychopy/issues/6781

[jfkominsky]

Had an idea that I think restores full backward compatibility to Dlg behavior with minimal muss and fuss: https://github.com/psychopy/psychopy/pull/6806