On 7 Jul, 2013, at 19:20, Larry Hastings <la...@hastings.org> wrote:
> On 07/07/2013 01:42 PM, Ronald Oussoren wrote: >> On 7 Jul, 2013, at 13:35, Larry Hastings <la...@hastings.org> >> wrote: >> >>> On 07/07/2013 07:25 AM, Ronald Oussoren wrote: >>> >>>> Signature objects use a name in angled brackets to indicate that a >>>> parameter is positional only, for example "input(<prompt>)". That might be >>>> an alternative to adding a "/" in the argument list in pydoc's output. >>>> >>>> >>> I wasn't aware that Signature objects currently had any support whatsoever >>> for positional-only parameters. Yes, in theory they do, but in practice >>> they have never seen one, because positional-only parameters only occur in >>> builtins and Signature objects have no metadata for builtins. (The very >>> problem Argument Clinic eventually hopes to solve!) >>> >>> Can you cite an example of this, so I may examine it? >>> >> I have a branch of PyObjC that uses this: >> <https://bitbucket.org/ronaldoussoren/pyobjc-3.0-unstable/overview> >> . That branch isn't quite stable yet, but does add a __signature__ slot to >> objc.selector and objc.function (basicly methods of Cocoa classes and >> automaticly wrapped global functions), both of which only have >> positional-only arguments. With the patch for pydoc/inspect I mentioned >> earlier I can then generate somewhat useful documentation for Cocoa classes >> using pydoc. >> >> A word of warning though: the PyObjC source code isn't the most >> approachable, the code that generates the Signature object is actually in >> python (callable_signature in pyobjc-core/Lib/objc/_callable_docstr.py) >> > > Ah. In other words, you have proposed it yourself in an external project. I > thought you were saying this was something Python itself already did. I wasn't clear enough in what I wrote. The stdlib contains support for positional-only arguments in Signature objects (see Lib/inspect.py, line 1472, which says "_POSITIONAL_ONLY = _ParameterKind(0, name='POSITIONAL_ONLY')". The __str__ of Parameter amongst other says: if kind == _POSITIONAL_ONLY: if formatted is None: formatted = '' formatted = '<{}>'.format(formatted) That is, it adds angled brackets around the names of positional-only parameters. I pointed to PyObjC as an example of code that actually creates Signature objects with positional-only arguments, as far as I know the stdlib never does this because the stdlib can only create signatures for plain python functions and those cannot have such arguments. > In that case, I think I will stick with Guido's suggested syntax. Consider > window.border in the curses module: eight positional-only parameters, each in > its own optional parameter group. Adding sixteen angle-brackets to that > already unreadable morass will make it even worse. But with "/" we add only > a single extra character, in an easy-to-find place (the end). Using Guido's suggestion is fine by me, I agree that there is a clear risk of angle-bracket overload for functions with a lot of arguments. I do think that the __str__ for Signatures should be changed to match the convention. And to be clear: I'm looking forward to having Argument Clinic and __signature__ objects on built-in functions, "funcname(...)" in the output pydoc is somewhat annoying, especially for extensions where the author hasn't bothered to provide a docstring. That's one reason I wrote the __signature__ support in PyObjC in the first place (and the patch for pydoc to actually use the signature information) Ronald _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
