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