Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/IPython/core/displaypub.py: 36%

1"""An interface for publishing rich data to frontends. 

2 

3There are two components of the display system: 

4 

5* Display formatters, which take a Python object and compute the 

6 representation of the object in various formats (text, HTML, SVG, etc.). 

7* The display publisher that is used to send the representation data to the 

8 various frontends. 

9 

10This module defines the logic display publishing. The display publisher uses 

11the ``display_data`` message type that is defined in the IPython messaging 

12spec. 

13""" 

14 

15# Copyright (c) IPython Development Team. 

16# Distributed under the terms of the Modified BSD License. 

17 

18 

19import sys 

20 

21from traitlets.config.configurable import Configurable 

22from traitlets import List 

23 

24# This used to be defined here - it is imported for backwards compatibility 

25from .display_functions import publish_display_data 

26 

27#----------------------------------------------------------------------------- 

28# Main payload class 

29#----------------------------------------------------------------------------- 

30 

31 

32class DisplayPublisher(Configurable): 

33 """A traited class that publishes display data to frontends. 

34 

35 Instances of this class are created by the main IPython object and should 

36 be accessed there. 

37 """ 

38 

39 def __init__(self, shell=None, *args, **kwargs): 

40 self.shell = shell 

41 super().__init__(*args, **kwargs) 

42 

43 def _validate_data(self, data, metadata=None): 

44 """Validate the display data. 

45 

46 Parameters 

47 ---------- 

48 data : dict 

49 The formata data dictionary. 

50 metadata : dict 

51 Any metadata for the data. 

52 """ 

53 

54 if not isinstance(data, dict): 

55 raise TypeError('data must be a dict, got: %r' % data) 

56 if metadata is not None: 

57 if not isinstance(metadata, dict): 

58 raise TypeError('metadata must be a dict, got: %r' % data) 

59 

60 # use * to indicate transient, update are keyword-only 

61 def publish(self, data, metadata=None, source=None, *, transient=None, update=False, **kwargs) -> None: 

62 """Publish data and metadata to all frontends. 

63 

64 See the ``display_data`` message in the messaging documentation for 

65 more details about this message type. 

66 

67 The following MIME types are currently implemented: 

68 

69 * text/plain 

70 * text/html 

71 * text/markdown 

72 * text/latex 

73 * application/json 

74 * application/javascript 

75 * image/png 

76 * image/jpeg 

77 * image/svg+xml 

78 

79 Parameters 

80 ---------- 

81 data : dict 

82 A dictionary having keys that are valid MIME types (like 

83 'text/plain' or 'image/svg+xml') and values that are the data for 

84 that MIME type. The data itself must be a JSON'able data 

85 structure. Minimally all data should have the 'text/plain' data, 

86 which can be displayed by all frontends. If more than the plain 

87 text is given, it is up to the frontend to decide which 

88 representation to use. 

89 metadata : dict 

90 A dictionary for metadata related to the data. This can contain 

91 arbitrary key, value pairs that frontends can use to interpret 

92 the data. Metadata specific to each mime-type can be specified 

93 in the metadata dict with the same mime-type keys as 

94 the data itself. 

95 source : str, deprecated 

96 Unused. 

97 transient : dict, keyword-only 

98 A dictionary for transient data. 

99 Data in this dictionary should not be persisted as part of saving this output. 

100 Examples include 'display_id'. 

101 update : bool, keyword-only, default: False 

102 If True, only update existing outputs with the same display_id, 

103 rather than creating a new output. 

104 """ 

105 

106 handlers = {} 

107 if self.shell is not None: 

108 handlers = getattr(self.shell, 'mime_renderers', {}) 

109 

110 for mime, handler in handlers.items(): 

111 if mime in data: 

112 handler(data[mime], metadata.get(mime, None)) 

113 return 

114 

115 if 'text/plain' in data: 

116 print(data['text/plain']) 

117 

118 def clear_output(self, wait=False): 

119 """Clear the output of the cell receiving output.""" 

120 print('\033[2K\r', end='') 

121 sys.stdout.flush() 

122 print('\033[2K\r', end='') 

123 sys.stderr.flush() 

124 

125 

126class CapturingDisplayPublisher(DisplayPublisher): 

127 """A DisplayPublisher that stores""" 

128 outputs = List() 

129 

130 def publish(self, data, metadata=None, source=None, *, transient=None, update=False): 

131 self.outputs.append({'data':data, 'metadata':metadata, 

132 'transient':transient, 'update':update}) 

133 

134 def clear_output(self, wait=False): 

135 super(CapturingDisplayPublisher, self).clear_output(wait) 

136 

137 # empty the list, *do not* reassign a new list 

138 self.outputs.clear()