Python docstrings that immediately follows the declaration of a class or function are placed in the __doc__
attribute.
The Question: How does one extract additional "internal" docstrings that occur later on in a function?
Update: Such literal statements are elided by the compiler. Could I perhaps get to them (and their line number) via the AST?
Why do I ask?
I've had a (not fully baked) idea to use such "internal" docstrings to delineate Given/When/Then sections of an Agile Scenario:
def test_adding():
"""Scenario: Adding two numbers"""
adder = Adder()
"""When I add 2 and 3"""
result = adder.add(2, 3)
"""Then the result is 5"""
assert result == 5
By extracting the docstrings, the test-running framework could generate output like this:
Scenario: Adding two numbers
When I add 2 and 3 (PASS)
Then the result is 5 (FAIL)
AssertionError Traceback
...
I think this would be more concise than the approach taken in Behave, Freshen, Lettuce, PyCukes, which require defining a separate function for each step. I don't like having to repeat the text of the step as a function name (@When("I add numbers") def add_numbers()
). But unlike a plain unit test, the docstrings will add the ability to print out a business-readable scenario for reference.