Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorflow/python/summary/plugin_asset.py: 28%

1# Copyright 2017 The TensorFlow Authors. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14# ============================================================================== 

15"""TensorBoard Plugin asset abstract class. 

16 

17TensorBoard plugins may need to provide arbitrary assets, such as 

18configuration information for specific outputs, or vocabulary files, or sprite 

19images, etc. 

20 

21This module contains methods that allow plugin assets to be specified at graph 

22construction time. Plugin authors define a PluginAsset which is treated as a 

23singleton on a per-graph basis. The PluginAsset has an assets method which 

24returns a dictionary of asset contents. The tf.compat.v1.summary.FileWriter 

25(or any other Summary writer) will serialize these assets in such a way that 

26TensorBoard can retrieve them. 

27""" 

28 

29import abc 

30 

31from tensorflow.python.framework import ops 

32 

33_PLUGIN_ASSET_PREFIX = "__tensorboard_plugin_asset__" 

34 

35 

36def get_plugin_asset(plugin_asset_cls, graph=None): 

37 """Acquire singleton PluginAsset instance from a graph. 

38 

39 PluginAssets are always singletons, and are stored in tf Graph collections. 

40 This way, they can be defined anywhere the graph is being constructed, and 

41 if the same plugin is configured at many different points, the user can always 

42 modify the same instance. 

43 

44 Args: 

45 plugin_asset_cls: The PluginAsset class 

46 graph: (optional) The graph to retrieve the instance from. If not specified, 

47 the default graph is used. 

48 

49 Returns: 

50 An instance of the plugin_asset_class 

51 

52 Raises: 

53 ValueError: If we have a plugin name collision, or if we unexpectedly find 

54 the wrong number of items in a collection. 

55 """ 

56 if graph is None: 

57 graph = ops.get_default_graph() 

58 if not plugin_asset_cls.plugin_name: 

59 raise ValueError("Class %s has no plugin_name" % plugin_asset_cls.__name__) 

60 

61 name = _PLUGIN_ASSET_PREFIX + plugin_asset_cls.plugin_name 

62 container = graph.get_collection(name) 

63 if container: 

64 if len(container) != 1: 

65 raise ValueError("Collection for %s had %d items, expected 1" % 

66 (name, len(container))) 

67 instance = container[0] 

68 if not isinstance(instance, plugin_asset_cls): 

69 raise ValueError("Plugin name collision between classes %s and %s" % 

70 (plugin_asset_cls.__name__, instance.__class__.__name__)) 

71 else: 

72 instance = plugin_asset_cls() 

73 graph.add_to_collection(name, instance) 

74 graph.add_to_collection(_PLUGIN_ASSET_PREFIX, plugin_asset_cls.plugin_name) 

75 return instance 

76 

77 

78def get_all_plugin_assets(graph=None): 

79 """Retrieve all PluginAssets stored in the graph collection. 

80 

81 Args: 

82 graph: Optionally, the graph to get assets from. If unspecified, the default 

83 graph is used. 

84 

85 Returns: 

86 A list with all PluginAsset instances in the graph. 

87 

88 Raises: 

89 ValueError: if we unexpectedly find a collection with the wrong number of 

90 PluginAssets. 

91 

92 """ 

93 if graph is None: 

94 graph = ops.get_default_graph() 

95 

96 out = [] 

97 for name in graph.get_collection(_PLUGIN_ASSET_PREFIX): 

98 collection = graph.get_collection(_PLUGIN_ASSET_PREFIX + name) 

99 if len(collection) != 1: 

100 raise ValueError("Collection for %s had %d items, expected 1" % 

101 (name, len(collection))) 

102 out.append(collection[0]) 

103 return out 

104 

105 

106class PluginAsset(metaclass=abc.ABCMeta): 

107 """This abstract base class allows TensorBoard to serialize assets to disk. 

108 

109 Plugin authors are expected to extend the PluginAsset class, so that it: 

110 - has a unique plugin_name 

111 - provides an assets method that returns an {asset_name: asset_contents} 

112 dictionary. For now, asset_contents are strings, although we may add 

113 StringIO support later. 

114 

115 LifeCycle of a PluginAsset instance: 

116 - It is constructed when get_plugin_asset is called on the class for 

117 the first time. 

118 - It is configured by code that follows the calls to get_plugin_asset 

119 - When the containing graph is serialized by the 

120 tf.compat.v1.summary.FileWriter, the writer calls assets and the 

121 PluginAsset instance provides its contents to be written to disk. 

122 """ 

123 

124 plugin_name = None 

125 

126 @abc.abstractmethod 

127 def assets(self): 

128 """Provide all of the assets contained by the PluginAsset instance. 

129 

130 The assets method should return a dictionary structured as 

131 {asset_name: asset_contents}. asset_contents is a string. 

132 

133 This method will be called by the tf.compat.v1.summary.FileWriter when it 

134 is time to write the assets out to disk. 

135 """ 

136 raise NotImplementedError()