[Python-ideas] Proposal: "?" Documentation Operator and easy reference to argument types/defaults/docstrings

Anders Hovmöller boxed at killingar.net
Fri Apr 26 00:04:30 EDT 2019



> On 26 Apr 2019, at 00:41, Peter O'Connor <peter.ed.oconnor at gmail.com> wrote:
> 
> - Defaults are defined in multiple places, which very easily leads to bugs (I'm aware of **kwargs but it obfuscates function interfaces and usually does more harm than good)
> - Types are defined in multiple places
> - Documentation is copy-pasted when referencing a single thing from different places.  (I can't count the number of types I've written ":param img: A (size_y, size_x, 3) RGB image" - I could now just reference a single RGB_IMAGE_DOC variable)
> - Argument names need to be written twice - in the header and documentation - and it's up to the user / IDE to make sure they stay in sync.


We have this exact problem in many places in tri.form, tri.query, tri.table and the code bases that use them. I would really like a solution to these! But you don’t seem to address these problems at all in the rest of your email, which makes me confused. In general I think what we want is an agreed upon way to specify argument names, counts and defaults for use by static analysis tools, documentation generation tools and IDEs, in a programmatic way. This could solve the problems you reference above, and also the issue of how to supply auto complete for something like Djangos query language (where you can do SomeTable.objects.filter(foreignkey__anotherforeignkey__value=3) which is great!).

Maybe something like...

def foo(**kwargs):
    “””
    @signature_by: full.module.path.to.a.signature_function(pass_kwargs_to=bar, hardcoded=[‘quux’])
    “””
    return bar(**kwargs, quux=3)


def signature_function(f, pass_kwargs_to=None, hardcoded=None, **_):
	signature = inspect.signature(f)
	if pass_kwargs_to is not None:
		signature_nested = inspect.signature(pass_kwargs_to)
		signature.remove_kwargs()
		signature = signature.merge(signature_nested)
	if hardcoded is not None:
		for h in hardcoded:
			signature.parameters.remove(h)
	return signature
	

Some of the above is pseudo code obviously.

What do you think?

/ Anders
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20190426/69be16dd/attachment-0001.html>


More information about the Python-ideas mailing list