-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
base_plugin.py
348 lines (283 loc) · 11.9 KB
/
base_plugin.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
# Copyright 2016 The TensorFlow Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ==============================================================================
"""TensorBoard Plugin abstract base class.
Every plugin in TensorBoard must extend and implement the abstract methods of
this base class.
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import collections
import six
from abc import ABCMeta
from abc import abstractmethod
@six.add_metaclass(ABCMeta)
class TBPlugin(object):
"""TensorBoard plugin interface.
Every plugin must extend from this class.
Subclasses should have a trivial constructor that takes a TBContext
argument. Any operation that might throw an exception should either be
done lazily or made safe with a TBLoader subclass, so the plugin won't
negatively impact the rest of TensorBoard.
Fields:
plugin_name: The plugin_name will also be a prefix in the http
handlers, e.g. `data/plugins/$PLUGIN_NAME/$HANDLER` The plugin
name must be unique for each registered plugin, or a ValueError
will be thrown when the application is constructed. The plugin
name must only contain characters among [A-Za-z0-9_.-], and must
be nonempty, or a ValueError will similarly be thrown.
"""
plugin_name = None
def __init__(self, context):
"""Initializes this plugin.
The default implementation does nothing. Subclasses are encouraged
to override this and save any necessary fields from the `context`.
Args:
context: A `base_plugin.TBContext` object.
"""
pass
@abstractmethod
def get_plugin_apps(self):
"""Returns a set of WSGI applications that the plugin implements.
Each application gets registered with the tensorboard app and is served
under a prefix path that includes the name of the plugin.
Returns:
A dict mapping route paths to WSGI applications. Each route path
should include a leading slash.
"""
raise NotImplementedError()
@abstractmethod
def is_active(self):
"""Determines whether this plugin is active.
A plugin may not be active for instance if it lacks relevant data. If a
plugin is inactive, the frontend may avoid issuing requests to its routes.
Returns:
A boolean value. Whether this plugin is active.
"""
raise NotImplementedError()
def frontend_metadata(self):
"""Defines how the plugin will be displayed on the frontend.
The base implementation returns a default value. Subclasses should
override this and specify either an `es_module_path` or (for legacy
plugins) an `element_name`, and are encouraged to set any other
relevant attributes.
"""
return FrontendMetadata()
class FrontendMetadata(object):
"""Metadata required to render a plugin on the frontend.
Each argument to the constructor is publicly accessible under a field
of the same name. See constructor docs for further details.
"""
def __init__(
self,
disable_reload=None,
element_name=None,
es_module_path=None,
remove_dom=None,
tab_name=None,
):
"""Creates a `FrontendMetadata` value.
The argument list is sorted and may be extended in the future;
therefore, callers must pass only named arguments to this
constructor.
Args:
disable_reload: Whether to disable the reload button and
auto-reload timer. A `bool`; defaults to `False`.
element_name: For legacy plugins, name of the custom element
defining the plugin frontend: e.g., `"tf-scalar-dashboard"`.
A `str` or `None` (for iframed plugins). Mutually exclusive
with `es_module_path`.
es_module_path: ES module to use as an entry point to this plugin.
A `str` that is a key in the result of `get_plugin_apps()`, or
`None` for legacy plugins bundled with TensorBoard as part of
`webfiles.zip`. Mutually exclusive with legacy `element_name`
remove_dom: Whether to remove the plugin DOM when switching to a
different plugin, to trigger the Polymer 'detached' event.
A `bool`; defaults to `False`.
tab_name: Name to show in the menu item for this dashboard within
the navigation bar. May differ from the plugin name: for
instance, the tab name should not use underscores to separate
words. Should be a `str` or `None` (the default; indicates to
use the plugin name as the tab name).
"""
self._disable_reload = False if disable_reload is None else disable_reload
self._element_name = element_name
self._es_module_path = es_module_path
self._remove_dom = False if remove_dom is None else remove_dom
self._tab_name = tab_name
@property
def disable_reload(self):
return self._disable_reload
@property
def element_name(self):
return self._element_name
@property
def es_module_path(self):
return self._es_module_path
@property
def remove_dom(self):
return self._remove_dom
@property
def tab_name(self):
return self._tab_name
def __eq__(self, other):
if not isinstance(other, FrontendMetadata):
return False
if self._disable_reload != other._disable_reload:
return False
if self._disable_reload != other._disable_reload:
return False
if self._element_name != other._element_name:
return False
if self._es_module_path != other._es_module_path:
return False
if self._remove_dom != other._remove_dom:
return False
if self._tab_name != other._tab_name:
return False
return True
def __hash__(self):
return hash((
self._disable_reload,
self._element_name,
self._es_module_path,
self._remove_dom,
self._tab_name,
))
def __repr__(self):
return "FrontendMetadata(%s)" % ", ".join((
"disable_reload=%r" % self._disable_reload,
"element_name=%r" % self._element_name,
"es_module_path=%r" % self._es_module_path,
"remove_dom=%r" % self._remove_dom,
"tab_name=%r" % self._tab_name,
))
class TBContext(object):
"""Magic container of information passed from TensorBoard core to plugins.
A TBContext instance is passed to the constructor of a TBPlugin class. Plugins
are strongly encouraged to assume that any of these fields can be None. In
cases when a field is considered mandatory by a plugin, it can either crash
with ValueError, or silently choose to disable itself by returning False from
its is_active method.
All fields in this object are thread safe.
"""
def __init__(
self,
assets_zip_provider=None,
data_provider=None,
db_connection_provider=None,
db_uri=None,
flags=None,
logdir=None,
multiplexer=None,
plugin_name_to_instance=None,
window_title=None):
"""Instantiates magic container.
The argument list is sorted and may be extended in the future; therefore,
callers must pass only named arguments to this constructor.
Args:
assets_zip_provider: A function that returns a newly opened file handle
for a zip file containing all static assets. The file names inside the
zip file are considered absolute paths on the web server. The file
handle this function returns must be closed. It is assumed that you
will pass this file handle to zipfile.ZipFile. This zip file should
also have been created by the tensorboard_zip_file build rule.
data_provider: Instance of `tensorboard.data.provider.DataProvider`. May
be `None` if `flags.generic_data` is set to `"false"`.
db_connection_provider: Function taking no arguments that returns a
PEP-249 database Connection object, or None if multiplexer should be
used instead. The returned value must be closed, and is safe to use in
a `with` statement. It is also safe to assume that calling this
function is cheap. The returned connection must only be used by a
single thread. Things like connection pooling are considered
implementation details of the provider.
db_uri: The string db URI TensorBoard was started with. If this is set,
the logdir should be None.
flags: An object of the runtime flags provided to TensorBoard to their
values.
logdir: The string logging directory TensorBoard was started with. If this
is set, the db_uri should be None.
multiplexer: An EventMultiplexer with underlying TB data. Plugins should
copy this data over to the database when the db fields are set.
plugin_name_to_instance: A mapping between plugin name to instance.
Plugins may use this property to access other plugins. The context
object is passed to plugins during their construction, so a given
plugin may be absent from this mapping until it is registered. Plugin
logic should handle cases in which a plugin is absent from this
mapping, lest a KeyError is raised.
window_title: A string specifying the window title.
"""
self.assets_zip_provider = assets_zip_provider
self.data_provider = data_provider
self.db_connection_provider = db_connection_provider
self.db_uri = db_uri
self.flags = flags
self.logdir = logdir
self.multiplexer = multiplexer
self.plugin_name_to_instance = plugin_name_to_instance
self.window_title = window_title
class TBLoader(object):
"""TBPlugin factory base class.
Plugins can override this class to customize how a plugin is loaded at
startup. This might entail adding command-line arguments, checking if
optional dependencies are installed, and potentially also specializing
the plugin class at runtime.
When plugins use optional dependencies, the loader needs to be
specified in its own module. That way it's guaranteed to be
importable, even if the `TBPlugin` itself can't be imported.
Subclasses must have trivial constructors.
"""
def define_flags(self, parser):
"""Adds plugin-specific CLI flags to parser.
The default behavior is to do nothing.
When overriding this method, it's recommended that plugins call the
`parser.add_argument_group(plugin_name)` method for readability. No
flags should be specified that would cause `parse_args([])` to fail.
Args:
parser: The argument parsing object, which may be mutated.
"""
pass
def fix_flags(self, flags):
"""Allows flag values to be corrected or validated after parsing.
Args:
flags: The parsed argparse.Namespace object.
Raises:
base_plugin.FlagsError: If a flag is invalid or a required
flag is not passed.
"""
pass
def load(self, context):
"""Loads a TBPlugin instance during the setup phase.
Args:
context: The TBContext instance.
Returns:
A plugin instance or None if it could not be loaded. Loaders that return
None are skipped.
:type context: TBContext
:rtype: TBPlugin | None
"""
return None
class BasicLoader(TBLoader):
"""Simple TBLoader that's sufficient for most plugins."""
def __init__(self, plugin_class):
"""Creates simple plugin instance maker.
:param plugin_class: :class:`TBPlugin`
"""
self.plugin_class = plugin_class
def load(self, context):
return self.plugin_class(context)
class FlagsError(ValueError):
"""Raised when a command line flag is not specified or is invalid."""
pass