how to docstring argument that is a function

Question

I have two questions

how can I docstring a argument that is a function
is it a good idea to use lambda when I have couple line of code like print('xxxx') but i need the same function (time.sleep(5)) to be executed between them

#method 1
time.sleep(5)
print('i am first')
time.sleep(5)
print('i am 2nd')
time.sleep(5)
print('i am 3rd')
time.sleep(5)
print('i am 4th')
time.sleep(5)
print('i am 5th')


#method 2
import time
def add_delay_between_action(func):
    time.sleep(5)
    func()
    time.sleep(5)
add_delay_between_action(lambda: print('i am first'))
add_delay_between_action(lambda: print('i am 2nd'))
add_delay_between_action(lambda: print('i am 3rd'))
add_delay_between_action(lambda: print('i am 4th'))
add_delay_between_action(lambda: print('i am 5th'))

Note that you should only have one time.sleep in add_delay_between_action, otherwise you're sleeping both after one function and before the next, which will add up to 10 seconds between functions instead of 5. add_delay_between_action should probably be renamed to add_delay_after_action — BallpointBen
– BallpointBen, Commented Aug 27, 2018 at 21:22
1. It is not clear what you mean. 2. The answer is probably opinion-based. — DYZ
– DYZ, Commented Aug 27, 2018 at 21:28

301_Moved_Permanently · Accepted Answer · 2018-08-28 08:08:58Z

2

An alternative to docstrings to convey the expected types of arguments is to use the typing module. And in your case, for a function typing.Callable.

import time
import typing

def add_delay_between_action(func: typing.Callable[[], None]):
    time.sleep(5)
    func()
    time.sleep(5)

answered Aug 28, 2018 at 8:08

301_Moved_Permanently

4,2261 gold badge17 silver badges30 bronze badges

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

Comments

Colonder · Accepted Answer · 2018-08-27 21:38:21Z

1

You could go with e.g.

def add_delay_between_action(func):
"""method summary

   Note:
       Do not include the `self` parameter in the ``Args`` section.

   Args:
       func: a function.

   ---------- OR ------------

   func : callable
       A function.

   Returns:
       Values to be returned.

"""

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

answered Aug 27, 2018 at 21:38

Colonder

1,5763 gold badges21 silver badges44 bronze badges

Comments

grahamlyons · Accepted Answer · 2018-08-27 21:48:34Z

0

I don't understand your first question but to your second I would direct you to The Zen of Python (https://www.python.org/dev/peps/pep-0020/) and

Simple is better than complex

It's entirely a matter of opinion and context but if you've got a couple of functions and want to sleep between them then just repeating the sleep call is simper and easier to follow.

answered Aug 27, 2018 at 21:48

grahamlyons

6875 silver badges16 bronze badges

Comments

micka190 · Accepted Answer · 2018-08-27 21:50:40Z

0

For your first question: You can not add docstrings within a function call's parentheses. This means you have to explain it somewhere else (where you do that is a matter of opinion).

One alternative would be to leave a comment next to the line explaining the function (since you are using lambdas).

Another alternative is to define a function and give that function a docstring. You probably should avoid this in your case, as you're only using lambdas to print, and having a bunch of functions with prints would be redundant when a lambda works.

Your second question is kind of vague.

I have couple line of code like print('xxxx') but i need the same function (time.sleep(5)) to be executed between them.

Lambdas are used when you need a pretty specific function or when you need to give another function a function parameter. In either case, your lambda should be small and simple (i.e. don't use a lambda that does 100 things.) If you're only going to use the lambda as a ways of passing the print() method, then yeah, lambdas will do just fine.

If you see yourself having complex lambdas, it might be time for a function. You can pass them the same way you would a lambda (if they don't take parameters):

def foo():
    [...]
    [do stuff]
    [...]

add_delay_between_action(foo)

answered Aug 27, 2018 at 21:50

micka190

1,0132 gold badges12 silver badges32 bronze badges

2 Comments

micka190 Over a year ago

You misunderstood me. I'm not saying that you can't pass a docstring as a parameter. I'm saying you can't write your argument, then type in a docstring next to it to do a "comment block" if you will. In some languages, you could do foo(arg1, arg2 /*This does bar*/, arg3). Attempting to do foo(arg1, arg2"""this does bar""", arg3) causes a SyntaxError. You totally can pass a docstring, it'll just be treated as a regular string. But that isn't was the OP was asking.

Hans Musgrave Over a year ago

I did completely misunderstand. Thanks for the clarification.

Collectives™ on Stack Overflow

how to docstring argument that is a function

4 Answers 4

Comments

Comments

Comments

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

Comments

Comments

Comments

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related