Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/IPython/utils/decorators.py: 48%

1# encoding: utf-8 

2"""Decorators that don't go anywhere else. 

3 

4This module contains misc. decorators that don't really go with another module 

5in :mod:`IPython.utils`. Before putting something here please see if it should 

6go into another topical module in :mod:`IPython.utils`. 

7""" 

8 

9#----------------------------------------------------------------------------- 

10# Copyright (C) 2008-2011 The IPython Development Team 

11# 

12# Distributed under the terms of the BSD License. The full license is in 

13# the file COPYING, distributed as part of this software. 

14#----------------------------------------------------------------------------- 

15 

16#----------------------------------------------------------------------------- 

17# Imports 

18#----------------------------------------------------------------------------- 

19from typing import Sequence 

20 

21from IPython.utils.docs import GENERATING_DOCUMENTATION 

22 

23 

24#----------------------------------------------------------------------------- 

25# Code 

26#----------------------------------------------------------------------------- 

27 

28def flag_calls(func): 

29 """Wrap a function to detect and flag when it gets called. 

30 

31 This is a decorator which takes a function and wraps it in a function with 

32 a 'called' attribute. wrapper.called is initialized to False. 

33 

34 The wrapper.called attribute is set to False right before each call to the 

35 wrapped function, so if the call fails it remains False. After the call 

36 completes, wrapper.called is set to True and the output is returned. 

37 

38 Testing for truth in wrapper.called allows you to determine if a call to 

39 func() was attempted and succeeded.""" 

40 

41 # don't wrap twice 

42 if hasattr(func, 'called'): 

43 return func 

44 

45 def wrapper(*args,**kw): 

46 wrapper.called = False 

47 out = func(*args,**kw) 

48 wrapper.called = True 

49 return out 

50 

51 wrapper.called = False 

52 wrapper.__doc__ = func.__doc__ 

53 return wrapper 

54 

55 

56def undoc(func): 

57 """Mark a function or class as undocumented. 

58 

59 This is found by inspecting the AST, so for now it must be used directly 

60 as @undoc, not as e.g. @decorators.undoc 

61 """ 

62 return func 

63 

64 

65def sphinx_options( 

66 show_inheritance: bool = True, 

67 show_inherited_members: bool = False, 

68 exclude_inherited_from: Sequence[str] = tuple(), 

69): 

70 """Set sphinx options""" 

71 

72 def wrapper(func): 

73 if not GENERATING_DOCUMENTATION: 

74 return func 

75 

76 func._sphinx_options = dict( 

77 show_inheritance=show_inheritance, 

78 show_inherited_members=show_inherited_members, 

79 exclude_inherited_from=exclude_inherited_from, 

80 ) 

81 return func 

82 

83 return wrapper