A portion of this thread seems to be focusing on what key word args parameters actually mean, in the Python sense. There is documentation for that, and a modicum of experience with Python makes this a relatively simple question and answer. However, when docs for a specific function or method specify keyword arguments without any indication of what the *expected* arguments might be, or what *useful* arguments might be, then it's not really helpful. If I have to look at the source code to figure out how the args are used, I don't need the docs at all. Which is why I suggest a line or two with sample invocations to provide at least a starting point to understand the parameters.
A doc signature that says something like "do_something(p1, d)" tells me very little. Even knowing that p1 is a "Point" is not all that valuable, except to give me another item to look up (the expected Point implementation). However, an example like 'do_something((141,380),"January, 2017")' tells me a lot more - that the Point is actually a tuple with (probably) x-y coordinates, and 'd' is a description associated with that position. That's a lot of useful information at a cost of a couple of dozen characters. So why not add a few examples? -- https://mail.python.org/mailman/listinfo/python-list
