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

[Stephen J. Turnbull]

Peter O'Connor writes:
 > On Fri, Apr 26, 2019 at 2:18 AM Stephen J. Turnbull <
 > turnbull.stephen.fw at u.tsukuba.ac.jp> wrote:

 > > What I would rather see is
 > >
 > > (1) Comment syntax "inside" (fvo "inside" including any comment after
 > >     the colon but before docstring or other code) .....
 > >
 > > (2) asserts involving parameters lexically are available to help().....
 > >
 > 
 > (1) I'm fine with "#" being used instead of "?" as the "documentation
 > operator", but I figured it would be rejected for breaking the president
 > that everything after "#" is ignored by the compiler.

This is not quite true, depending on your definition of "compiler",
because of PEP 263, which allows you to specify the program's encoding
in a comment at the beginning (first or second line), and because of
type hints themselves, which are recognized in comments by parsing
tools like mypy.  The reason for not having semantically significant
comments, AIUI, is not so much that the *compiler* ignore it as that
the *human reader* be able to ignore it.  The way I think about it,
this is what justifies the PEP 263 coding cookies, since humans *will*
ignore the cookies in favor of detecting mojibake "by eye", while
compilers need them to construct string literals correctly.  I'm not
sure how the authorities on Pythonicity will come down on this, though.

 > (2) This would be a nice addition ... if this proposal were actually
 > implemented, you'd have a built in "Argument" object, and in that case you
 > could do e.g.:
 >     RGB_IMAGE = Argument(type=np.ndarray, doc = 'An RGB image', check =
 > lambda img: (img.ndim==3 and img.shape[2]==3))
 >     def brighten_image(image :=? RGB_IMAGE, ...):
 >         ...

If the "(2)" refers to my proposal that asserts be available to
help(), I don't understand the example.  Are you proposing that
instead of an explicit expression, asserts of this kind be written

    assert image.check()

In any case, as far as I know you can already use the syntax suggested
in the quotation with standard type hints as long as "Argument" is a
class *factory*.  (Caveat: I'm not sure what semantics you attach to
":=?".)  I'm not arguing against the desire for the *builtin* feature,
simply recognizing the practicality that already implemented features,
or approximations to what you really want, get more support more
quickly.

Thinking aloud, you're probably way ahead of me, but just in case:
I'm not so clear on whether the reuse of RGB_IMAGE suggested by the
assignment in the example is so useful.  I would expect something more
like

RGB_IMAGE = Argument(type=np.ndarray, doc = 'An RGB image',
                     check = lambda img: (img.ndim==3 and img.shape[2]==3))
def brighten_image(image : RGB_IMAGE(doc = 'Image to brighten in-place', ...):

because "image" already tells you what the argument *is*, and
"RGB_IMAGE" tells you its specific *type*, while the docstring tells
you its *role* in the function, and that it's being mutated.  For
various reasons, these distinctions aren't so salient for RGB images,
I guess, but they're crucial for types like int and float.  It seems
to me, therefore, that the Argument object (whether an instance or a
class) is likely to have 'doc' and 'check' attributes that vary with
role, ie, as the arguments they described get passed from function to
function.  I don't think there's a lot to say about the variability of
'doc' except "live with it", but the variability of 'check' sounds
like something that a contracting functionality would deal with (if
you don't know him already, Anders Hovmöller is expert on contracts in
Python, and there were long threads on that a few months ago, which he
could probably summarize for you).

Steve