Package: docstringer
docstringerA simple decorator to create documentation of your function calls from their docstringsScopeWhat package does?This utility allows you to add a simple@docstringerdecorator to any function calls you wish to document when you are running your code. This will then track the calls to these functions and output documentation of the call-stack flow.This utility is focused on documentation of the call stack of functions and uses the function doc strings to document the call order.What package does not do?This function is purely focused on documenting the call order, the call parameters and the return values and using the docstrings to make this auto documentation.This package doesnotintermediate values tracked at each stage within functions. There are many great packages already available to do this such assnoop.This package also doesnotprofile the time taken to run each function in the call stack. There are many great packages already available to do this such asprofiling.QuickstartInstall the package using:pip install docstringerOn any function in your code that you wish to document the calling order, add the@docstringerdecorator. By default thedocstringerpackage will print the output.An exampleWe have a simple program that rolls a number of dice and returns the result.We decorate the functions we want to document function calls to using the@docstringerdecorator.@docstringerdefroll_the_dice(rolls:int,sides:int=6)->tuple:"""Rolls a number of dice and returns the result."""results=[]for_inrange(rolls):results.append(roll(sides))return(sum(results),results)@docstringerdefroll(sides:int=6)->int:"""An individual die (of side count=sides) roll."""returnrandom.randint(1,sides)An example output from running this code:CALL to roll_the_dice (id=4441740768)
with {'args': (), 'kwargs': {'rolls': 2, 'sides': 6}}

    Rolls a number of dice and returns the result.

CALL to roll (id=4442233152)
with {'args': (6,), 'kwargs': {}}

    An individual die (of side count=sides) roll.

RETURN from roll (id=4442233152
result = 5

CALL to roll (id=4442233152)
with {'args': (6,), 'kwargs': {}}

    An individual die (of side count=sides) roll.

RETURN from roll (id=4442233152
result = 3

RETURN from roll_the_dice (id=4441740768
result = (8, [5, 3])Deactivating docstringer in productionBy defaultdocstringeris active and will log the call stack on the decorated functions. When using in production you will want to switch this off. This will also speed up running.To switch off the@docstringerdecorator without removing it, pass theactive=Falseparameter to the decorator. This can be done globally using a configuration. For example:DEBUG=False# Set to True in debug mode when decorator should be active\@docstringer(active=DEBUG)defmy_function():""" My function to be documented when it is called """...Different output formatsDifferentFormatterscan be used to push the output in different formats by passing an instance of theFormatteryou want to theDOCSTRINGER_FORMATTERvariable.By defaultdocstringeroutputs the function call information as print statements to the console. This default formatter is thePrintFormatterYou can set a different formatter by passing this to theformatterparameter in the docstring. The built in formatters are outlined below. Or you can customise your ownfromdocstringer.formattersimportLoggerFormatterformatter=LoggerFormatter(logger=logger,log_level='info')@docstringer(formatter=formatter)defmy_function():""" My function to be documented when it is called """...LoggerFormatterThis formatter outputs the function call information to the logger of your choice instead of printing to the screen. When instantiating theLoggerFormatter, pass it the logger and log=level you want to use:fromdocstringer.formattersimportLoggerFormatterimportlogginglogging.basicConfig(level=logging.INFO,format="%(levelname)s-%(message)s")@docstringer(formatter=LoggerFormatter(logger=logging,log_level='info')defmy_function():...This will now output function calls as log items.EventListFormatterTheEventListFormatterwill return the function call information a a list ofFunctionEventobjects. These objects contain the name, docstring, call values and return values of each function call in the order that they were called.This formatter is passed a list (usually an empty list) when it is instantiated and it will populate this list with the FunctionEvent objects that occur on decorated functions.fromdocstringer.formattersimportEventListFormatterevent_list=[]@docstringer(formatter=EventListFormatter(event_list))defmy_function():...Combining with other tracing or introspection packagesThis package focuses on documenting the call stack and showing the docstring for the decorated functions.This can be combined with a more detailed tracing or profiling package to give a combined output. We recommend that the tracing decorator is placed inside the docstringer decorator.Example combining with snoopIn this example we use thePrintSimpleFormatterwhich does not show the parameters and return values as these are already provided by snoop. We also configure snoop to print in a similar formatimportsnoopfromdocstringerimportdocstringersnoop_formatted=snoop.Config(color=False,prefix="",columns=[]).snoop@docstringer(formatter=PrintSimpleFormatter())@snoop_formatteddefroll(sides:int=6)->int:"""An individual die (of side count=sides) roll."""returnrandom.randint(1,sides)The output contains both the snoop and docstringer outputs:...

CALL to roll (id=4343471264)

    An individual die roll.

    Parameters:
    - sides (int) - the number of sides on the dice (default = 6)

    Returns:
    - the value of the die roll


>>> Call to roll in File "/Users/matt/Projects/docstringer/demo.py", line 50
...... sides = 6
50 | def roll(sides: int = 6) -> int:
60 |     return random.randint(1, sides)
<<< Return value from roll: 1

...