Skip to content

decorators

Add additional parameters to docstring of function.

Source code in navis/utils/decorators.py
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
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)
    try:
        lastp = [
            i
            for i, line in enumerate(lines[:-1])
            if "Returns" in line and "----" in lines[i + 1]
        ][0] - 1
    except IndexError:
        warnings.warn(f'Could not find "Returns" in docstring for function {func}')
        return func

    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