See issue on GitHub here. Relevant docs are here.
The argument used to be named fmt. Now, as of dev build 4133, only format is accepted. Oddly minor and annoying breaking change … am I missing something?
Did the API for `view.find_all` change with `fmt` now being `format`?
maegul
#1
0 Likes
Another undocumented API change?
jfcherng
#2
It looks like the staff is going to refactor sublime.py and sublime_plugin.py for docs and types annotation. So there can be some typos during refactoring.
0 Likes
maegul
#3
Right … I figured as much.
I’m not on the discord (I really don’t like it) … would it help to bring it up there?
0 Likes
bschaaf
#5
Note the parameter has always been documented as format, but the code was incorrectly fmt. As such it was assumed no one was relying on the argument name and it was changed to match the documentation. The same goes for all of the other argument names.
0 Likes
jfcherng
#6
show_quick_panelhas had it’son_selectargument removed or changed toon_done(this is in dev build4133for me).
I guess this naming change can break a lot. As there are many on_xxx callbacks, people will prefer using named arguments show_quick_panel(on_select=my_on_select_callback) over something like show_quick_panel(None, None, my_on_select_callback).
After all, obviously, ST staff uses it in core and it breaks ST now.
0 Likes
maegul
#7
Well, if the code was incorrectly fmt, “relying”, as you say, includes using keyword/named arguments. I relied on LSP and pyright, and then the code itself, to infer the argument to use and presumed it was the documentation that was wonky (which, honestly, I don’t think was an unfair presumption … the sublime API and plugin development always seemed to be happy to have little “secrets” like this).
Honestly, I don’t think this is a fair presumption for python. And, unless there’s a list of such instances (I haven’t looked), I’d consider this a pretty ugly breaking change to leave undocumented … unless I’m the only one using named arguments with the API.
Is there a version number from which these changes are being made?
0 Likes
maegul
#9
Agreed. I do wonder if I’m the only one trying hard to use named arguments!
Surely if the documented name of the parameter was wrong, and so could never have been used in anyone’s code, then changing the documentation to match the code would be the more sensible change than a breaking change in the code to match the inaccurate documentation.
An exception might be if the argument name (in the code) was so atrociously unhelpful that a breaking change was worth it in the long run.
But otherwise, you could keep the slightly more helpful descriptive word in the documentation while also just accurately documenting the actual name of the argument while not making any breaking changes to the API.
1 Like