On 08/04/2016 03:45 PM, Alexander Belopolsky wrote:

On Thu, Aug 4, 2016 at 2:19 PM, Larry Hastings <larry@hastings.org> wrote:
AFAIK the Clinic DSL can handle all of Python's C extensions.  I have no plans to "revise the whole approach"; if someone else does I haven't heard about it.

I was just wondering that with so much effort to bring typing to the mainstream, a more "pythonic" DSL may emerge for describing the signatures of functions in C modules. 

BTW, is there any document describing the syntax of "text signatures" such as:

>>> os.rename.__text_signature__
'($module, /, src, dst, *, src_dir_fd=None, dst_dir_fd=None)'

What does the "$module, /," part mean?

/ is the delimiter between positional-only parameters and positional-or-keyword arguments.  It's not actual Python syntax, but Guido said (somewhere) that *if* Python ever sprouted a syntax for positional-only parameters, that was as good a delimiter as any.  I think he picked it because / is the inverse of *.

The "$" in "$module" means it's what we called a "bound parameter", a parameter which gets bound to a value before Python ever sees it.  C extension functions get the module passed in automatically, but this is done internally and from the Python level you can't see it.  So it's accurate to present it there, but we suppress it before we compute the inspect.signature.  For example, os_chdir_impl in Modules/posixmodule.c takes two arguments, the first being the module, the second being the path; inspect.signature(os.chdir) only shows one parameter, the path.

__text_signature__, although user-visible, is not considered information for users.  It's an internal implementation detail like co_code.  However, with the exception of things like "$module" and "/" it's just a Python function declaration.  Literally we remove the funny bits like "$module" and "/", prepend that string with "def foo", append that string with ": pass", and parse the result with ast.parse.

If you have more questions about __text_signature__, I recommend reading the implementation of inspect.signature, since that's the one and only consumer of it.