[Tutor] How to use introspection to discover parameters?
Please help me understand the following (I have python 2.6.2) ... Because I want to write nice docstrings, I read PEP257 where it says: The one-line docstring should NOT be a signature reiterating the function/method parameters (which can be obtained by introspection). I am understanding this sentence to mean: don't put function parameters in my own docstrings, because they are readily obtained some other way. This other way is apparently called introspection, but how to actually do it is a mystery that I cannot find documented. If the following guess is wrong, I will be grateful if someone would just show a simple example of how this is done. If I was to attempt a guess: does it just mean using the help() builtin in the interpreter? I know about help() from books and tutorials. In the packaged html python docs though, use of help() is hardly described and never associated with the word introspection. My reasoning for this guess is explained in the rest of this email, which sets out what I have tried before asking here: I searched the installed html docs for introspection. I disregard most hits as too specific, except these: On Page 2. Defining new types it says: An application can use the introspection API ... and under Glossary it says, in the docstring entry: Since [the docstring] is available via introspection, it is the canonical place for documentation of the object. So I find no clue there how to do introspection to obtain function/method parameters, except that there is an API for it, somewhere. I googled and found various, eg: http://www.ibm.com/developerworks/library/l-pyint/index.html It also does not explain how to do introspection to obtain function/method parameters. Next, I tried looking somewhere arbitrary in the python libraries hoping to see PEP257-compliant practice.I think that I need to find some code that is written in python, not C, because PEP257 also says: docstring [with parameters] is only appropriate for C functions (such as built-ins), where introspection is not possible. I arbitrarily choose the logging module: import logging logging.__file__ '/usr/lib/python2.6/logging/__init__.pyc' ls -1 /usr/lib/python2.6/logging/*.py /usr/lib/python2.6/logging/config.py /usr/lib/python2.6/logging/handlers.py /usr/lib/python2.6/logging/__init__.py so I assume the logging module is not written in C, and therefore will contain suitable examples. And I try this: help(logging.log) Help on function log in module logging: log(level, msg, *args, **kwargs) Log 'msg % args' with the integer severity 'level' on the root logger. logging.log.__doc__ \nLog 'msg % args' with the integer severity 'level' on the root logger.\n So I look at that and guess: is PEP257 actually attempting to say dont reiterate the function/method parameters in the docstring, because help() displays them in line 3 of its output. If it does mean this, it would be a lot clearer if it just said so! A related question: help() seems to do the introspection for me. Does python allow me to do it in my own code? Specifically, how might I write my own function to mimic line 3 of help(), appearing like so: my_function(logging.log) log(level, msg, *args, **kwargs) If I knew how to do that, it might help me understand how to do introspection better. One last thing. When looking for answers, I found this page which seems related: http://stackoverflow.com/questions/2536879/python-introspection-how-to-get-varnames-of-class-methods There is a comment by S Lott who possibly is the author of Building Skills In Python: Please ... explain why you need introspection and why you can't simply read the source. Ummm ... I'm not sure what to make of that!! Because I've read that this instrospection thing is supposed to be an important feature of Python. Clarifications welcome :) ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] How to use introspection to discover parameters?
On Thu, Jul 26, 2012 at 9:48 AM, David bouncingc...@gmail.com wrote: A related question: help() seems to do the introspection for me. Does python allow me to do it in my own code? Specifically, how might I write my own function to mimic line 3 of help(), appearing like so: my_function(logging.log) log(level, msg, *args, **kwargs) If I knew how to do that, it might help me understand how to do introspection better. The inspect module probably has all the tools you need: http://docs.python.org/library/inspect.html . In particular, inspect.getargspec() will get you the argument specification of a function, like this: inspect.getargspec(logging.log) ArgSpec(args=['level', 'msg'], varargs='args', keywords='kwargs', defaults=None) Then you just have to format those results the way you like. Also, the help object itself is written in python. You can look at the source in pydoc.py (http://hg.python.org/cpython/file/2.7/Lib/pydoc.py) to see exactly what it does. -- Jerry ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] How to use introspection to discover parameters?
David wrote: Please help me understand the following (I have python 2.6.2) ... Because I want to write nice docstrings, I read PEP257 where it says: The one-line docstring should NOT be a signature reiterating the function/method parameters (which can be obtained by introspection). As a general rule, yes, that is right -- your doc strings should not merely repeat the function signature in the first line. The help() function automatically determines the signature for you. For example, if I define this function with a docstring, and then call help() on it: py def spam(n): ... Return Spam Spam Spam Glorious SPAM!!! ... return spam*n ... py help(spam) I get this help text displayed: Help on function spam in module __main__: spam(n) Return Spam Spam Spam Glorious SPAM!!! Notice that the function signature, spam(n), is displayed by help() even though I didn't include it in the docstring. That is because help() uses introspection to discover the signature. See more detail below. I am understanding this sentence to mean: don't put function parameters in my own docstrings, because they are readily obtained some other way. This other way is apparently called introspection, but how to actually do it is a mystery that I cannot find documented. If the following guess is wrong, I will be grateful if someone would just show a simple example of how this is done. You don't have to do a thing unless you are writing your own help system. The standard help() function already does it. In case it isn't obvious, introspection in programming refers to the ability of your program to inspect its own components (in this case, functions) to find out what they are and what they can do. Python has a couple of built-in functions for introspection, plus an entire module of extra functions. Built-ins include: dir, vars, globals, locals, hasattr, type, help [Note: technically, help is not a built-in. It is added to the built-ins at runtime. Some systems may disable that, e.g. on embedded systems with limited memory.] Plus the inspect module, which contains many other advanced introspection tools. You can read about the inspect module here: http://docs.python.org/library/inspect.html http://hg.python.org/cpython/file/2.7/Lib/inspect.py [...] So I find no clue there how to do introspection to obtain function/method parameters, except that there is an API for it, somewhere. Using the same function spam() I defined above: py import inspect py inspect.getargspec(spam) ArgSpec(args=['n'], varargs=None, keywords=None, defaults=None) And here is one way to use it to print the function signature. First we grab the argument spec, then we concatenate it after the function name. py spec = inspect.getargspec(spam) py spam.__name__ + inspect.formatargspec(*spec) 'spam(n)' So I look at that and guess: is PEP257 actually attempting to say dont reiterate the function/method parameters in the docstring, because help() displays them in line 3 of its output. Right! If it does mean this, it would be a lot clearer if it just said so! Perhaps so. You might consider putting in a request for a documentation change on the bug tracker. A related question: help() seems to do the introspection for me. Does python allow me to do it in my own code? Specifically, how might I write my own function to mimic line 3 of help(), appearing like so: my_function(logging.log) log(level, msg, *args, **kwargs) If I knew how to do that, it might help me understand how to do introspection better. The help() function is written in pure Python. It's a big, powerful function, but if you want to read it, you can do so: This is where it is added to the built-ins: http://hg.python.org/cpython/file/2.7/Lib/site.py And this is where the actual help functionality is made: http://hg.python.org/cpython/file/2.7/Lib/pydoc.py One last thing. When looking for answers, I found this page which seems related: http://stackoverflow.com/questions/2536879/python-introspection-how-to-get-varnames-of-class-methods There is a comment by S Lott who possibly is the author of Building Skills In Python: Please ... explain why you need introspection and why you can't simply read the source. What an asinine comment. Where shall we start? 1) Source code is not always available. Even when available, it can sometimes be covered by a license which makes it professional suicide to read the code, because then anything you write afterwards may be legally deemed to be copied from the source code you read. 2) Even when you have the source code to read, reading the source can be much, much harder than using introspection. The pydoc module is over 2000 lines of code, the decimal module is over 4000 lines of code. I shudder to think how many thousands of lines of code, spread over who knows how many files, the numpy library would be. Ten? Twenty? And it is written in a mix of Python, C and Fortran. I
Re: [Tutor] Private attributes [was Re: What on earth is happening here ???]
Trying to make things private is a throwback to Java. In Python the tendency is to just leave everything public. And private is with one underbar/underscore. [snip] In general, I recommend that beginners avoid double leading underscore methods until they are no longer beginners, because (1) they can be confusing to people still trying to learn the language; (2) you aren't going to need them; and (3) if you do need them, you can add them in later. Yeah, that is what I was trying to get across. Ramit This email is confidential and subject to important disclaimers and conditions including on offers for the purchase or sale of securities, accuracy and completeness of information, viruses, confidentiality, legal privilege, and legal entity disclaimers, available at http://www.jpmorgan.com/pages/disclosures/email. ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] How to use introspection to discover parameters?
On 27/07/2012, Jerry Hill malaclyp...@gmail.com wrote: ... inspect.getargspec(logging.log) ArgSpec(args=['level', 'msg'], varargs='args', keywords='kwargs', defaults=None) ... Also, the help object itself is written in python. You can look at the source in pydoc.py On 27/07/2012, Steven D'Aprano st...@pearwood.info wrote: find out what they are and what they can do. Python has a couple of built-in functions for introspection, plus an entire module of extra functions. Built-ins include: dir, vars, globals, locals, hasattr, type, help ... Plus the inspect module, which contains many other advanced introspection ... This is where it is added to the built-ins: ... And this is where the actual help functionality is made: ... 1) Source code is not always available. Even when available, it can ... 2) Even when you have the source code to read, reading the source can be ... 3) Even if the source code is short and sweet and easy to understand, this ... Thanks for the great and comprehensive answers! I understand much better it now. When I saw that help() was a builtin, I assumed it was written in C. So it helped that you pointed me to pydoc and inspect. In pydoc I found this: if inspect.isfunction(object): args, varargs, varkw, defaults = inspect.getargspec(object) I didn't realise that so much of a builtin help() would be visible to me in *.py files. I naively assumed builtin meant compiled-from-C. You might consider putting in a request for a documentation change on the bug tracker. Will do. Assistance much appreciated! ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
[Tutor] going rate for python tutoring?
Hello, I'm trying to learn posting and am having a very hard time at it. I'm going to hire someone to give me a private lesson, so I put up a notice on Northwestern's CS bulletin board--probably a student there'll be able to help. How much money should I offer? I haven't the foggiest notion what the going rate is for private computer tutoring. Thanks, Ben ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] going rate for python tutoring?
On 26/07/12 19:06, Benjamin Fishbein wrote: I'm trying to learn posting Can you explain what 'posting' is? I've no idea what you mean. Are you talking about web transactions? Or using message boards? Or something else? I haven't the foggiest notion what the going rate is for private computer tutoring. Me neither but are there any other adverts you could compare to? Meantime you could just ask your questions here for free! -- Alan G Author of the Learn to Program web site http://www.alan-g.me.uk/ ___ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: http://mail.python.org/mailman/listinfo/tutor
