I recently started programming using Python. I have to write many functions and was wondering how I can incorporate a help or description text such that it appears in the object inspector of spyder when I call the function.
In MatLab, this worked by putting commented text at the beginning of the function file. Is there a similar method in Python (using Spyder)?
By default, the first string in the body of a method is used as its docstring (or documentation string). Python will use this when help() is called for that method.
def foo(bar):
"""
Takes bar and does some things to it.
"""
return bar
help(foo)
foo(bar)
Takes bar and does
some things to it
You can read more about how this works by reading PEP-258, and this question goes into some more details.
(Spyder maintainer here) There are other couple of things you need to know (besides what #burhan-khalid mentioned) regarding Spyder itself:
If you want to see your docstrings nicely formatted in the Help pane, you need to write them following the numpydoc standard, which is explained here. This is a set of conventions used by almost all python scientific packages to write their docstrings. It's not mandatory but we follow it too while converting docstrings (which come in plain text) to html.
You have to use Ctrl+I in front of an object's name to show their help in our Help pane.
In a short answer. This can be done by putting text between triple quotes.
'''
#param self
'''
You can find a brief example on this link: https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html#
The other answers are more extensive.
Related
I would like to provide code snippets to show-case how one could use a particular method or class in python. How can I do that?
In Java one could use <pre> ... </pre> to do so.
Doctest is the only way?
As I look at the existing docstrings for typical packages (e.g., pandas, numpy, etc), I never see anything other than doctest which is intended to test the method and not just to format text as python code. So, if doctest is the only way, what would be the proper way of formatting a snippet of code to look like interactive python sessions? I don't want to write my code in an interactive session each time and then c+p it in my docstring. It doesn't seem to be right.
DocStrings are not the only way. If you are using Sphinx to generate documentation then you should read this.
Example
Here is something I want to talk about:: <-- Special syntax to mark code beginning
def my_fn(foo, bar=True): # Code itself
"""A really useful function.
Returns None
"""
For example, when i use matplotlib as plt, a possible statement is like below:
plt.plot(x,y,color='blue')
so how can i get what arguments like 'color' i can pass to the 'plot' function, and what is the proper values for that argument?
Especially when i use some modules.
thanks for any answers.
I'm a little disappointed that this post is being downvoted because I think it's a very legitimate question. In particular, I appreciate that you asked not what the answer was but instead how you could find it for yourself in the future.
Exploring Local Python Documentation
Python has a very robust built-in documentation system as well as a very active and supportive community. At any point in time, you can use the help function to examine a particular object that you want more information on - this will pull up the documentation for that object. In your example, you could do something like:
help(plt.plot)
to pull up the documentation for the matplotlib.pyplot.plot function. Outside of a running Python process, you can use the pydoc command line tool to read and explore that same documentation. Something like:
$ pydoc matplotlib.pyplot.plot
Running that in the shell will display the same documentation as the help command example.
Writing Documentation
As a good citizen of the Python ecosystem, you'll naturally want to document your own code. This is done pretty simply by adding a docstring to the top of a function, class, or module. Docstrings are denoted with a triple quotation mark """, seen in the examples below:
"""This module contains some example classes and functions"""
class MyClass(object):
"""MyClass does some things"""
pass
def my_function(a):
"""Calculates the sum"""
return(a)
There are many different documentation styles that people prefer, so what you choose is up to you. Though I would recommend the official docstring standards outlined in PEP 257.
Finding Online Resources
It's also often useful to take advantage of online documentation and resources. The official Python documentation includes all of the builtin documentation for the standard libraries as well as a tutorial for developers who are new to Python!
As it seems that you're relatively new to the ecosystem yourself, here's some more resources that you might find useful:
Learn Python the Hard Way
CodeAcademy has a Python track
StackOverflow, obviously
What is the optimal way to get documentation about a specific function in Python? I am trying to download stock price data such that I can view it in my Spyder IDE.
The function I am interested in is:
ystockquote.get_historical_prices
How do I know how many inputs the function takes, the types of inputs it accepts, and the date format for example?
Just finding documentation
I suspect this question was super-downvoted because the obvious answer is to look at the documentation. It depends where your function came from, but googling is typically a good way to find it (I found the class here in a few seconds of googling).
It is also very trivialy to just check the source code
In order to import a function, you need to know where the source file it comes from is; open that file: in python, docstrings are what generate the documentation and can be found in triple-quotes beneath the function declaration. The arguments can be inferred from the function signature, but because python is dynamically typed, any type "requirements" are just suggestions. Some good documenters will provide the optimal types, too.
While "how do I google for documentation" is not a suitable question, the question of how to dynamically infer documentation is more reasonable. The answer is
The help function, built in here
The file __doc__ accessible on any python object, as a string
Using inspection
The question is even more reasonable if you are working with python extensions, like from external packages. I don't if the package you specifically asked about has any of those, but they can be tricky to work with if the authors haven't defined docstrings in the module. The problem is that in these cases, the typing can be rigidly inforced. There is no great way to get the tpye requirements in this case, as inspection will fail. If you can get at the source code, though, (perhaps by googling), this is where the documentation would be provided
Is there a python regex which will generically match a method definition (not just the declaration but also the method body) inside a python code file?
I did my share of googling but only found something similar for Java. Python is different w.r.t. to the way scopes are entered through indentation rather than accolades. What makes this problem hard is the fact that indentation may drop inside the method body (i.e. blank lines, multiline strings, comments).
I also looked for DOM parsers but basically they're all aimed at XML or HTML.
Finally I am looking into introspection (How can I get the source code of a Python function?) but I still wonder if there is a nicer way for code analysis without execution.
EDIT: the question receives a bunch of downvotes but I think it's actually a valid and specific programming question. I elaborated the question a bit.
Err, you don't want to use regexes to parse Python. The 'nicer way for code analysis without execution' is to use the Python standard library parser and/or ast modules. Look under the heading Python Language Services, e.g. https://docs.python.org/2/library/language.html
I'm looking at various IDEs for python. Looking at the official list the IDEs are categorized based on 'introspection based code completion'.
What does introspection based code completion mean?
Thanks.
It means the IDE uses introspection to figure out what methods and variables are accessible from a given object, then allows quick code completion, usually by providing a list of options after you type a period following a symbol.
Here's an example if WingIDE Pro inaction. Forgive the hastily thrown together image.
You can see that arg1 is being shown as 1 in the first example, as well as the helper showing that it is probably an int.
In the second part, you can see that the IDE is looking through the docstrings for what the method get does, in the requests module.
The second image below shows that the IDE can 'auto-complete' code for you, including showing what it does.