Spaces:
Sleeping
Sleeping
File size: 13,544 Bytes
cf2a15a |
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 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 |
# 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 abc import ABCMeta
from abc import abstractmethod
class TBPlugin(metaclass=ABCMeta):
"""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()
def data_plugin_names(self):
"""Experimental. Lists plugins whose summary data this plugin reads.
Returns:
A collection of strings representing plugin names (as read
from `SummaryMetadata.plugin_data.plugin_name`) from which
this plugin may read data. Defaults to `(self.plugin_name,)`.
"""
return (self.plugin_name,)
class FrontendMetadata:
"""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,
is_ng_component=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).
is_ng_component: Set to `True` only for built-in Angular plugins.
In this case, the `plugin_name` property of the Plugin, which is
mapped to the `id` property in JavaScript's `UiPluginMetadata` type,
is used to select the Angular component. A `True` value is mutually
exclusive with `element_name` and `es_module_path`.
"""
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
self._is_ng_component = (
False if is_ng_component is None else is_ng_component
)
@property
def disable_reload(self):
return self._disable_reload
@property
def element_name(self):
return self._element_name
@property
def is_ng_component(self):
return self._is_ng_component
@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,
self._is_ng_component,
)
)
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,
"is_ng_component=%r" % self._is_ng_component,
)
)
class TBContext:
"""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,
flags=None,
logdir=None,
multiplexer=None,
plugin_name_to_instance=None,
sampling_hints=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"`.
flags: An object of the runtime flags provided to TensorBoard to their
values.
logdir: The string logging directory TensorBoard was started with.
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.
sampling_hints: Map from plugin name to `int` or `NoneType`, where
the value represents the user-specified downsampling limit as
given to the `--samples_per_plugin` flag, or `None` if none was
explicitly given for this plugin.
window_title: A string specifying the window title.
"""
self.assets_zip_provider = assets_zip_provider
self.data_provider = data_provider
self.flags = flags
self.logdir = logdir
self.multiplexer = multiplexer
self.plugin_name_to_instance = plugin_name_to_instance
self.sampling_hints = sampling_hints
self.window_title = window_title
class TBLoader:
"""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
|