wch
commented
2 years ago FWIW, I very recently added better typing information so that VS Code will underline in red if the shape of the input isn't correct.
Since this is code that's almost never used by normal users, I don't think that saving a bit of typing is that much of a benefit.
I really don't want to end up in a place similar to HTML dependencies in R, where so many forms of input are accepted, and we've spent countless hours trying to understand the shape of the data, and it's very painful and risky to make any changes. (I'm thinking of this one we dealt with very recently, where it took hours just to fix a small recursive function, because the shape of the data was unclear.)
We currently allow a dict or a list of those dicts. So the inputs could look like these:
script = {"src": "foo.js"}
script = [{"src": "foo.js"}]
script = [{"src": "foo.js"}, {"src": "bar.js", "type": "module"}]If we also allow bare strings, then the inputs could look like this:
script = "foo.js"
script = {"src": "foo.js"}
script = [{"src": "foo.js"}]
script = ["foo.js", {"src": "bar.js", "type": "module"}]
script = ["foo.js"]
script = [{"src": "foo.js"}, {"src": "bar.js", "type": "module"}]If there's one thing I know, it's that when people are allowed to use inputs in a particular way, they will use them that way, so all of these forms will end up in the wild. The nature of this kind of library code is that it is read much more often than it is written, and so if the inputs are loose, in the long run it will result in people spending much more time trying to decipher other people's code than it will save them in typing and remembering which field names are needed (especially now that the type hints help with the field names).
I know it may seem like I'm reacting strongly to this... it's in part because we recently spent hours trying to understand and fix up a simple PR in R htmltools that should have been trivial. Every time we work with HTML dependencies in R, it is way, way more painful than it should be, largely because we've been very lax with the inputs, and even worse, we've used those varied inputs directly in our data structures. (Thankfully, we're not doing the latter in Python!)
Same goes for
HTMLDependency(stylesheet=)Not only is it less typing, but it's also annoying to have to remember when to use
srcvshref(and >95% of the time you don't need any extra attributes)