1# Copyright 2015 gRPC authors. 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"""Utilities for working with callables.""" 15 16import abc 17import collections 18import enum 19import functools 20import logging 21 22import six 23 24_LOGGER = logging.getLogger(__name__) 25 26 27class Outcome(six.with_metaclass(abc.ABCMeta)): 28 """A sum type describing the outcome of some call. 29 30 Attributes: 31 kind: One of Kind.RETURNED or Kind.RAISED respectively indicating that the 32 call returned a value or raised an exception. 33 return_value: The value returned by the call. Must be present if kind is 34 Kind.RETURNED. 35 exception: The exception raised by the call. Must be present if kind is 36 Kind.RAISED. 37 """ 38 39 @enum.unique 40 class Kind(enum.Enum): 41 """Identifies the general kind of the outcome of some call.""" 42 43 RETURNED = object() 44 RAISED = object() 45 46 47class _EasyOutcome( 48 collections.namedtuple('_EasyOutcome', 49 ['kind', 'return_value', 'exception']), Outcome): 50 """A trivial implementation of Outcome.""" 51 52 53def _call_logging_exceptions(behavior, message, *args, **kwargs): 54 try: 55 return _EasyOutcome(Outcome.Kind.RETURNED, behavior(*args, **kwargs), 56 None) 57 except Exception as e: # pylint: disable=broad-except 58 _LOGGER.exception(message) 59 return _EasyOutcome(Outcome.Kind.RAISED, None, e) 60 61 62def with_exceptions_logged(behavior, message): 63 """Wraps a callable in a try-except that logs any exceptions it raises. 64 65 Args: 66 behavior: Any callable. 67 message: A string to log if the behavior raises an exception. 68 69 Returns: 70 A callable that when executed invokes the given behavior. The returned 71 callable takes the same arguments as the given behavior but returns a 72 future.Outcome describing whether the given behavior returned a value or 73 raised an exception. 74 """ 75 76 @functools.wraps(behavior) 77 def wrapped_behavior(*args, **kwargs): 78 return _call_logging_exceptions(behavior, message, *args, **kwargs) 79 80 return wrapped_behavior 81 82 83def call_logging_exceptions(behavior, message, *args, **kwargs): 84 """Calls a behavior in a try-except that logs any exceptions it raises. 85 86 Args: 87 behavior: Any callable. 88 message: A string to log if the behavior raises an exception. 89 *args: Positional arguments to pass to the given behavior. 90 **kwargs: Keyword arguments to pass to the given behavior. 91 92 Returns: 93 An Outcome describing whether the given behavior returned a value or raised 94 an exception. 95 """ 96 return _call_logging_exceptions(behavior, message, *args, **kwargs) 97