Python docstring repeated param text

Question

In a Python module (which is designed to be used in IPython Notebooks by less-technical users), I have several functions in the way of:

load_this(dt, this_filter)
load_that(dt, that_filter)
load_the_other(dt, the_other_filter)

The docstring for the dt param is the same for each function:

:param dt: date, date tuple, or datetime tuple. 
    date type args expand to start and end of day.
    eg.  date(2015, 9, 9) or
    (date(2015, 9, 9), date(2015, 9, 10)) or
    (datetime(2015, 9, 9, 12, 30), datetime(2015, 9, 9, 1))

However the docsring for x_filter params are different in each case.

I try to be as DRY as I can in my code, so the repeated docstring is grating a little. Is there any way to cross reference a docstring param in the code, but still have IPython display the full docstring.

Thanks

Speaking Code · Accepted Answer · 2015-09-11 10:07:15Z

2

You can add docs to functions via decorator

def mydoc(func):
    func.__doc__ = 'Here I am.'
    return func

@mydoc
def load_this(dt):
    pass

Variant with custom docs

def setdoc(docstring):
    def decor(func):
        func.__doc__ = docstring
        return func
    return decor

@setdoc('Here I am.')
def load_this(dt):
    pass

or just add docs after defining a function

docmessage = 'Here I am.'
def load_this(dt):
    pass
load_this.__doc__ = docmessage

edited Sep 11, 2015 at 10:07

answered Sep 11, 2015 at 9:49

Speaking Code

1415 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

MarkNS Over a year ago

Thanks, that's useful.. I should have specified that I have other heterogeneous arguments in the different functions.. it's only the dt argument that is common. But, I guess I can do some string replacement with the doc reference? I'm going to play with it. (Although am wary of making things too magic :))

Speaking Code Over a year ago

Yes you can modify existing doc instead of replacing. By default doc is None. I'll add one more example now for passing docstring to decorator as parameter.

Cong Ma · Accepted Answer · 2015-09-11 10:17:25Z

1

Instead of programmatically generating the docstring (rather unpythonic in my opinion), what stops you from just define a function load like

def load(dt, filter_):
    ... ...

and write a single documentation for it? I really fail to see the need for 3 separate functions.

Even if you some how do, you can always create them, after defining the above function load, by partialing them.

Edit: After the comment by OP, I think you can simply write the doc for dt once in one of the functions (presumably the most basic, "prototype" one) and in other function simply say

"See the documentation of ___ for details about dt".

Yes, you can splice docstrings smartly like

some_function.__doc__ = some_function.__doc__ + "doc for dt"

or more smartly than that by writing your own documentation-generating metaclass generator factor factory framework, but why? ;)

edited Sep 11, 2015 at 10:17

answered Sep 11, 2015 at 10:01

Cong Ma

11.4k3 gold badges36 silver badges49 bronze badges

1 Comment

MarkNS Over a year ago

I was expecting an answer like this ;) a) the code is designed for non-technical users. b) the filter_ args are very heterogeneous, and indeed aren't the only variation between the functions. Some functions have 2 args, some have 7.

Collectives™ on Stack Overflow

Python docstring repeated param text

2 Answers 2

2 Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related