Python docstrings and inline code; syntax meaning ">>>"
I have some Python experience but only recently stumbled upon widespread use docstrings
. I am going through the source code of the Financial Market Simulator (FMS) and when I open it in PyCharm I see the following syntax highlighting (screenshot of a code snippet of one of the modules in FMS):
Why are statements after "→>" highlighted as if they are executable? From what I've read docstrings
, both in the official documentation and on SO (for example here ), I think these assertions shouldn't be met, but the syntax highlighting confuses me by making me think that "→>" is a code marker inside docstring
. to be executed. Or is it just PiKarma's mistake? None of the documentation mentions anything related to this and I am worried if something is missing.
PS: for the record, viewing the code in SublimeText does not reproduce the same behavior.
source to share
Operators written with >>>
in docstrings, doctests .
It allows you to test your code by running the examples built into the documentation and checking that they give the expected results. It parses the help text to find examples, runs them, and then compares the output text to the expected value.
In your case, PyCharm did the additional task of highlighting python code in docstrings. It won't affect your normal function, so you don't need to worry about it.
Example:
Let's say I have a script with a name doctest_simple_addition
in which I wrote some doctrines for a function add()
where some test cases give correct output and some give an exception. Then I can verify that my function is giving the expected results by running these doctrines.
doctest_simple_addition.py
def add(a,b):
"""
>>> add(1, 2)
3
>>> add(5, 3)
8
>>> add('a', 1)
Traceback (most recent call last):
...
TypeError: cannot concatenate 'str' and 'int' objects
"""
return a + b
To run Doctrines, use doctest
as the main program with a parameter -m
to the interpreter. Typically, no output is produced during testing. You can add an option -v
and doctest
then it will print a detailed log of what its attempted with a summary at the end.
doctest
searches for lines beginning with an interpreter prompt >>>
to find the beginning of a test case. The test instance ends with an empty line or the next interpreter prompt.
$ python -m doctest -v doctest_simple_addition.py
Trying:
add(1, 2)
Expecting:
3
ok
Trying:
add(5, 3)
Expecting:
8
ok
Trying:
add('a', 1)
Expecting:
Traceback (most recent call last):
...
TypeError: cannot concatenate 'str' and 'int' objects
ok
1 items had no tests:
doctest_simple_addition
1 items passed all tests:
3 tests in doctest_simple_addition.add
3 tests in 2 items.
3 passed and 0 failed.
Test passed.
Note. ... When doctest sees a header line traceback
(either Traceback (most recent call last):
or Traceback (innermost last):
, depending on the version of Python you are running), it skips ahead to find the exception type and message, completely ignoring the intermediate lines.
This is because the paths in the trace depend on where the module is installed on the file system on a given system, and it would be impossible to write portable tests because the path would change from system to system.
source to share
The behavior you see is part of the Python testing support available in Pycharm.
The settings option is called Parsing Python Code in docstrings and is available under Integrated Python Tools :
If checked, PyCharm highlights the sample code and performs syntax checks and code checks. If this check box is not selected, code snippets inside docstrings are not parsed.
You can turn it off if you like.
The online documentation details how to run tests and view your results .
source to share