tensorbored 2.21.0rc1769983804__py3-none-any.whl

tensorbored/util/grpc_util.py

@@ -0,0 +1,311 @@
+# Copyright 2019 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.
+# ==============================================================================
+"""Utilities for working with python gRPC stubs."""
+
+import enum
+import functools
+import random
+import threading
+import time
+
+import grpc
+
+from tensorbored import version
+from tensorbored.util import tb_logging
+
+logger = tb_logging.get_logger()
+
+# Default RPC timeout.
+_GRPC_DEFAULT_TIMEOUT_SECS = 30
+
+# Max number of times to attempt an RPC, retrying on transient failures.
+_GRPC_RETRY_MAX_ATTEMPTS = 5
+
+# Parameters to control the exponential backoff behavior.
+_GRPC_RETRY_EXPONENTIAL_BASE = 2
+_GRPC_RETRY_JITTER_FACTOR_MIN = 1.1
+_GRPC_RETRY_JITTER_FACTOR_MAX = 1.5
+
+# Status codes from gRPC for which it's reasonable to retry the RPC.
+_GRPC_RETRYABLE_STATUS_CODES = frozenset(
+    [
+        grpc.StatusCode.ABORTED,
+        grpc.StatusCode.DEADLINE_EXCEEDED,
+        grpc.StatusCode.RESOURCE_EXHAUSTED,
+        grpc.StatusCode.UNAVAILABLE,
+    ]
+)
+
+# gRPC metadata key whose value contains the client version.
+_VERSION_METADATA_KEY = "tensorboard-version"
+
+
+class AsyncCallFuture:
+    """Encapsulates the future value of a retriable async gRPC request.
+
+    Abstracts over the set of futures returned by a set of gRPC calls
+    comprising a single logical gRPC request with retries.  Communicates
+    to the caller the result or exception resulting from the request.
+
+    Args:
+      completion_event: The constructor should provide a `threding.Event` which
+        will be used to communicate when the set of gRPC requests is complete.
+    """
+
+    def __init__(self, completion_event):
+        self._active_grpc_future = None
+        self._active_grpc_future_lock = threading.Lock()
+        self._completion_event = completion_event
+
+    def _set_active_future(self, grpc_future):
+        if grpc_future is None:
+            raise RuntimeError(
+                "_set_active_future invoked with grpc_future=None."
+            )
+        with self._active_grpc_future_lock:
+            self._active_grpc_future = grpc_future
+
+    def result(self, timeout):
+        """Analogous to `grpc.Future.result`. Returns the value or exception.
+
+        This method will wait until the full set of gRPC requests is complete
+        and then act as `grpc.Future.result` for the single gRPC invocation
+        corresponding to the first successful call or final failure, as
+        appropriate.
+
+        Args:
+          timeout: How long to wait in seconds before giving up and raising.
+
+        Returns:
+          The result of the future corresponding to the single gRPC
+          corresponding to the successful call.
+
+        Raises:
+          * `grpc.FutureTimeoutError` if timeout seconds elapse before the gRPC
+          calls could complete, including waits and retries.
+          * The exception corresponding to the last non-retryable gRPC request
+          in the case that a successful gRPC request was not made.
+        """
+        if not self._completion_event.wait(timeout):
+            raise grpc.FutureTimeoutError(
+                f"AsyncCallFuture timed out after {timeout} seconds"
+            )
+        with self._active_grpc_future_lock:
+            if self._active_grpc_future is None:
+                raise RuntimeError("AsyncFuture never had an active future set")
+            return self._active_grpc_future.result()
+
+
+def async_call_with_retries(api_method, request, clock=None):
+    """Initiate an asynchronous call to a gRPC stub, with retry logic.
+
+    This is similar to the `async_call` API, except that the call is handled
+    asynchronously, and the completion may be handled by another thread. The
+    caller must provide a `done_callback` argument which will handle the
+    result or exception rising from the gRPC completion.
+
+    Retries are handled with jittered exponential backoff to spread out failures
+    due to request spikes.
+
+    This only supports unary-unary RPCs: i.e., no streaming on either end.
+
+    Args:
+      api_method: Callable for the API method to invoke.
+      request: Request protocol buffer to pass to the API method.
+      clock: an interface object supporting `time()` and `sleep()` methods
+        like the standard `time` module; if not passed, uses the normal module.
+
+    Returns:
+      An `AsyncCallFuture` which will encapsulate the `grpc.Future`
+      corresponding to the gRPC call which either completes successfully or
+      represents the final try.
+    """
+    if clock is None:
+        clock = time
+    logger.debug("Async RPC call %s with request: %r", api_method, request)
+
+    completion_event = threading.Event()
+    async_future = AsyncCallFuture(completion_event)
+
+    def async_call(handler):
+        """Invokes the gRPC future and orchestrates it via the AsyncCallFuture."""
+        future = api_method.future(
+            request,
+            timeout=_GRPC_DEFAULT_TIMEOUT_SECS,
+            metadata=version_metadata(),
+        )
+        # Ensure we set the active future before invoking the done callback, to
+        # avoid the case where the done callback completes immediately and
+        # triggers completion event while async_future still holds the old
+        # future.
+        async_future._set_active_future(future)
+        future.add_done_callback(handler)
+
+    # retry_handler is the continuation of the `async_call`.  It should:
+    #   * If the grpc call succeeds: trigger the `completion_event`.
+    #   * If there are no more retries: trigger the `completion_event`.
+    #   * Otherwise, invoke a new async_call with the same
+    #     retry_handler.
+    def retry_handler(future, num_attempts):
+        e = future.exception()
+        if e is None:
+            completion_event.set()
+            return
+        else:
+            logger.info("RPC call %s got error %s", api_method, e)
+            # If unable to retry, proceed to completion.
+            if e.code() not in _GRPC_RETRYABLE_STATUS_CODES:
+                completion_event.set()
+                return
+            if num_attempts >= _GRPC_RETRY_MAX_ATTEMPTS:
+                completion_event.set()
+                return
+            # If able to retry, wait then do so.
+            backoff_secs = _compute_backoff_seconds(num_attempts)
+            clock.sleep(backoff_secs)
+            async_call(
+                functools.partial(retry_handler, num_attempts=num_attempts + 1)
+            )
+
+    async_call(functools.partial(retry_handler, num_attempts=1))
+    return async_future
+
+
+def _compute_backoff_seconds(num_attempts):
+    """Compute appropriate wait time between RPC attempts."""
+    jitter_factor = random.uniform(
+        _GRPC_RETRY_JITTER_FACTOR_MIN, _GRPC_RETRY_JITTER_FACTOR_MAX
+    )
+    backoff_secs = (_GRPC_RETRY_EXPONENTIAL_BASE**num_attempts) * jitter_factor
+    return backoff_secs
+
+
+def call_with_retries(api_method, request, clock=None):
+    """Call a gRPC stub API method, with automatic retry logic.
+
+    This only supports unary-unary RPCs: i.e., no streaming on either end.
+    Streamed RPCs will generally need application-level pagination support,
+    because after a gRPC error one must retry the entire request; there is no
+    "retry-resume" functionality.
+
+    Retries are handled with jittered exponential backoff to spread out failures
+    due to request spikes.
+
+    Args:
+      api_method: Callable for the API method to invoke.
+      request: Request protocol buffer to pass to the API method.
+      clock: an interface object supporting `time()` and `sleep()` methods
+        like the standard `time` module; if not passed, uses the normal module.
+
+    Returns:
+      Response protocol buffer returned by the API method.
+
+    Raises:
+      grpc.RpcError: if a non-retryable error is returned, or if all retry
+        attempts have been exhausted.
+    """
+    if clock is None:
+        clock = time
+    # We can't actually use api_method.__name__ because it's not a real method,
+    # it's a special gRPC callable instance that doesn't expose the method name.
+    rpc_name = request.__class__.__name__.replace("Request", "")
+    logger.debug("RPC call %s with request: %r", rpc_name, request)
+    num_attempts = 0
+    while True:
+        num_attempts += 1
+        try:
+            return api_method(
+                request,
+                timeout=_GRPC_DEFAULT_TIMEOUT_SECS,
+                metadata=version_metadata(),
+            )
+        except grpc.RpcError as e:
+            logger.info("RPC call %s got error %s", rpc_name, e)
+            if e.code() not in _GRPC_RETRYABLE_STATUS_CODES:
+                raise
+            if num_attempts >= _GRPC_RETRY_MAX_ATTEMPTS:
+                raise
+        backoff_secs = _compute_backoff_seconds(num_attempts)
+        logger.info(
+            "RPC call %s attempted %d times, retrying in %.1f seconds",
+            rpc_name,
+            num_attempts,
+            backoff_secs,
+        )
+        clock.sleep(backoff_secs)
+
+
+def version_metadata():
+    """Creates gRPC invocation metadata encoding the TensorBoard version.
+
+    Usage: `stub.MyRpc(request, metadata=version_metadata())`.
+
+    Returns:
+      A tuple of key-value pairs (themselves 2-tuples) to be passed as the
+      `metadata` kwarg to gRPC stub API methods.
+    """
+    return ((_VERSION_METADATA_KEY, version.VERSION),)
+
+
+def extract_version(metadata):
+    """Extracts version from invocation metadata.
+
+    The argument should be the result of a prior call to `metadata` or the
+    result of combining such a result with other metadata.
+
+    Returns:
+      The TensorBoard version listed in this metadata, or `None` if none
+      is listed.
+    """
+    return dict(metadata).get(_VERSION_METADATA_KEY)
+
+
+@enum.unique
+class ChannelCredsType(enum.Enum):
+    LOCAL = "local"
+    SSL = "ssl"
+    SSL_DEV = "ssl_dev"
+
+    def channel_config(self):
+        """Create channel credentials and options.
+
+        Returns:
+          A tuple `(channel_creds, channel_options)`, where `channel_creds`
+          is a `grpc.ChannelCredentials` and `channel_options` is a
+          (potentially empty) list of `(key, value)` tuples. Both results
+          may be passed to `grpc.secure_channel`.
+        """
+
+        options = []
+        if self == ChannelCredsType.LOCAL:
+            creds = grpc.local_channel_credentials()
+        elif self == ChannelCredsType.SSL:
+            creds = grpc.ssl_channel_credentials()
+        elif self == ChannelCredsType.SSL_DEV:
+            # Configure the dev cert to use by passing the environment variable
+            # GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=path/to/cert.crt
+            creds = grpc.ssl_channel_credentials()
+            options.append(("grpc.ssl_target_name_override", "localhost"))
+        else:
+            raise AssertionError("unhandled ChannelCredsType: %r" % self)
+        return (creds, options)
+
+    @classmethod
+    def choices(cls):
+        return cls.__members__.values()
+
+    def __str__(self):
+        # Use user-facing string, because this is shown for flag choices.
+        return self.value

tensorbored/util/img_mime_type_detector.py

@@ -0,0 +1,40 @@
+# Copyright 2025 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.
+
+"""Utility to determine the MIME type of an image."""
+
+from PIL import Image
+import io
+
+_IMGHDR_TO_MIMETYPE = {
+    "bmp": "image/bmp",
+    "gif": "image/gif",
+    "jpeg": "image/jpeg",
+    "png": "image/png",
+}
+_DEFAULT_IMAGE_MIMETYPE = "application/octet-stream"
+
+
+def from_bytes(img_bytes: bytes) -> str:
+    """Returns the MIME type of an image from its bytes."""
+    format_lower = None
+    try:
+        img = Image.open(io.BytesIO(img_bytes))
+        format_lower = img.format.lower()
+        if format_lower == "jpg":
+            format_lower = "jpeg"
+    except:
+        # Let the default value be returned.
+        pass
+    return _IMGHDR_TO_MIMETYPE.get(format_lower, _DEFAULT_IMAGE_MIMETYPE)

tensorbored/util/io_util.py

@@ -0,0 +1,20 @@
+# Copyright 2021 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 IO helpers."""
+
+
+def IsCloudPath(path):
+    """Checks whether a given path is Cloud filesystem path."""
+    return path.startswith("gs://") or path.startswith("s3://")

tensorbored/util/lazy_tensor_creator.py

@@ -0,0 +1,110 @@
+# Copyright 2019 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.
+# ==============================================================================
+"""Provides a lazy wrapper for deferring Tensor creation."""
+
+import threading
+
+from tensorbored.compat import tf2 as tf
+
+# Sentinel used for LazyTensorCreator._tensor to indicate that a value is
+# currently being computed, in order to fail hard on reentrancy.
+_CALL_IN_PROGRESS_SENTINEL = object()
+
+
+class LazyTensorCreator:
+    """Lazy auto-converting wrapper for a callable that returns a `tf.Tensor`.
+
+    This class wraps an arbitrary callable that returns a `Tensor` so that it
+    will be automatically converted to a `Tensor` by any logic that calls
+    `tf.convert_to_tensor()`. This also memoizes the callable so that it is
+    called at most once.
+
+    The intended use of this class is to defer the construction of a `Tensor`
+    (e.g. to avoid unnecessary wasted computation, or ensure any new ops are
+    created in a context only available later on in execution), while remaining
+    compatible with APIs that expect to be given an already materialized value
+    that can be converted to a `Tensor`.
+
+    This class is thread-safe.
+    """
+
+    def __init__(self, tensor_callable):
+        """Initializes a LazyTensorCreator object.
+
+        Args:
+          tensor_callable: A callable that returns a `tf.Tensor`.
+        """
+        if not callable(tensor_callable):
+            raise ValueError("Not a callable: %r" % tensor_callable)
+        self._tensor_callable = tensor_callable
+        self._tensor = None
+        self._tensor_lock = threading.RLock()
+        _register_conversion_function_once()
+
+    def __call__(self):
+        if self._tensor is None or self._tensor is _CALL_IN_PROGRESS_SENTINEL:
+            with self._tensor_lock:
+                if self._tensor is _CALL_IN_PROGRESS_SENTINEL:
+                    raise RuntimeError(
+                        "Cannot use LazyTensorCreator with reentrant callable"
+                    )
+                elif self._tensor is None:
+                    self._tensor = _CALL_IN_PROGRESS_SENTINEL
+                    self._tensor = self._tensor_callable()
+        return self._tensor
+
+
+def _lazy_tensor_creator_converter(value, dtype=None, name=None, as_ref=False):
+    del name  # ignored
+    if not isinstance(value, LazyTensorCreator):
+        raise RuntimeError("Expected LazyTensorCreator, got %r" % value)
+    if as_ref:
+        raise RuntimeError("Cannot use LazyTensorCreator to create ref tensor")
+    tensor = value()
+    if dtype not in (None, tensor.dtype):
+        raise RuntimeError(
+            "Cannot convert LazyTensorCreator returning dtype %s to dtype %s"
+            % (tensor.dtype, dtype)
+        )
+    return tensor
+
+
+# Use module-level bit and lock to ensure that registration of the
+# LazyTensorCreator conversion function happens only once.
+_conversion_registered = False
+_conversion_registered_lock = threading.Lock()
+
+
+def _register_conversion_function_once():
+    """Performs one-time registration of `_lazy_tensor_creator_converter`.
+
+    This helper can be invoked multiple times but only registers the conversion
+    function on the first invocation, making it suitable for calling when
+    constructing a LazyTensorCreator.
+
+    Deferring the registration is necessary because doing it at at module import
+    time would trigger the lazy TensorFlow import to resolve, and that in turn
+    would break the delicate `tf.summary` import cycle avoidance scheme.
+    """
+    global _conversion_registered
+    if not _conversion_registered:
+        with _conversion_registered_lock:
+            if not _conversion_registered:
+                _conversion_registered = True
+                tf.register_tensor_conversion_function(
+                    base_type=LazyTensorCreator,
+                    conversion_func=_lazy_tensor_creator_converter,
+                    priority=0,
+                )

tensorbored/util/op_evaluator.py

@@ -0,0 +1,104 @@
+# Copyright 2018 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 helper routine for TF op evaluator.
+
+Requires TensorFlow.
+"""
+
+import threading
+
+
+class PersistentOpEvaluator:
+    """Evaluate a fixed TensorFlow graph repeatedly, safely, efficiently.
+
+    Extend this class to create a particular kind of op evaluator, like an
+    image encoder. In `initialize_graph`, create an appropriate TensorFlow
+    graph with placeholder inputs. In `run`, evaluate this graph and
+    return its result. This class will manage a singleton graph and
+    session to preserve memory usage, and will ensure that this graph and
+    session do not interfere with other concurrent sessions.
+
+    A subclass of this class offers a threadsafe, highly parallel Python
+    entry point for evaluating a particular TensorFlow graph.
+
+    Example usage:
+
+        class FluxCapacitanceEvaluator(PersistentOpEvaluator):
+          \"\"\"Compute the flux capacitance required for a system.
+
+          Arguments:
+            x: Available power input, as a `float`, in jigawatts.
+
+          Returns:
+            A `float`, in nanofarads.
+          \"\"\"
+
+          def initialize_graph(self):
+            self._placeholder = tf.placeholder(some_dtype)
+            self._op = some_op(self._placeholder)
+
+          def run(self, x):
+            return self._op.eval(feed_dict: {self._placeholder: x})
+
+        evaluate_flux_capacitance = FluxCapacitanceEvaluator()
+
+        for x in xs:
+          evaluate_flux_capacitance(x)
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._session = None
+        self._initialization_lock = threading.Lock()
+
+    def _lazily_initialize(self):
+        """Initialize the graph and session, if this has not yet been done."""
+        # TODO(nickfelt): remove on-demand imports once dep situation is fixed.
+        import tensorflow.compat.v1 as tf
+
+        with self._initialization_lock:
+            if self._session:
+                return
+            graph = tf.Graph()
+            with graph.as_default():
+                self.initialize_graph()
+            # Don't reserve GPU because libpng can't run on GPU.
+            config = tf.ConfigProto(device_count={"GPU": 0})
+            self._session = tf.Session(graph=graph, config=config)
+
+    def initialize_graph(self):
+        """Create the TensorFlow graph needed to compute this operation.
+
+        This should write ops to the default graph and return `None`.
+        """
+        raise NotImplementedError(
+            'Subclasses must implement "initialize_graph".'
+        )
+
+    def run(self, *args, **kwargs):
+        """Evaluate the ops with the given input.
+
+        When this function is called, the default session will have the
+        graph defined by a previous call to `initialize_graph`. This
+        function should evaluate any ops necessary to compute the result
+        of the query for the given *args and **kwargs, likely returning
+        the result of a call to `some_op.eval(...)`.
+        """
+        raise NotImplementedError('Subclasses must implement "run".')
+
+    def __call__(self, *args, **kwargs):
+        self._lazily_initialize()
+        with self._session.as_default():
+            return self.run(*args, **kwargs)

tensorbored/util/platform_util.py

@@ -0,0 +1,20 @@
+# Copyright 2018 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 helper routine for platform."""
+
+
+def readahead_file_path(path, unused_readahead=None):
+    """Readahead files not implemented; simply returns given path."""
+    return path

tensorbored/util/tb_logging.py

@@ -0,0 +1,24 @@
+# Copyright 2018 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 logging module."""
+
+import logging
+
+_logger = logging.getLogger("tensorboard")
+
+
+def get_logger():
+    """Returns TensorBoard logger."""
+    return _logger