Skip to content

decorators

Add additional parameters to docstring of function.

Source code in navis/utils/decorators.py
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
def map_neuronlist_update_docstring(func, allow_parallel):
    """Add additional parameters to docstring of function."""
    # Parse docstring
    lines = func.__doc__.split('\n')

    # Find a line with a parameter
    pline = [l for l in lines if ' : ' in l][0]
    # Get the leading whitespaces
    wspaces = ' ' * re.search('( *)', pline).end(1)
    # Get the offset for type and description
    offset = re.search('( *: *)', pline).end(1) - len(wspaces)

    # Find index of the last parameters (assuming there is a single empty
    # line between Returns and the last parameter)
    lastp = [i for i, l in enumerate(lines) if ' Returns' in l][0] - 1

    msg = ''
    if allow_parallel:
        msg += dedent(f"""\
        parallel :{" " * (offset - 10)}bool
                  {" " * (offset - 10)}If True and input is NeuronList, use parallel
                  {" " * (offset - 10)}processing. Requires `pathos`.
        n_cores : {" " * (offset - 10)}int, optional
                  {" " * (offset - 10)}Numbers of cores to use if `parallel=True`.
                  {" " * (offset - 10)}Defaults to half the available cores.
        """)

    msg += dedent(f"""\
    progress :{" " * (offset - 10)}bool
              {" " * (offset - 10)}Whether to show a progress bar. Overruled by
              {" " * (offset - 10)}`navis.set_pbars`.
    omit_failures :{" " * (offset - 15)}bool
                   {" " * (offset - 15)}If True will omit failures instead of raising
                   {" " * (offset - 15)}an exception. Ignored if input is single neuron.
    """)

    # Insert new docstring
    lines.insert(lastp, indent(msg, wspaces))

    # Update docstring
    func.__doc__ = '\n'.join(lines)

    return func