ref: Documentation improvements and removed some unused code (#51)

* ref: Make atexit print to stderr

* ref: Kill most of minimal and update docstrings

* ref: Documentation improvements and removed some unused code

Author: mitsuhiko

sentry_sdk/api.py

@@ -1,9 +1,20 @@
+from contextlib import contextmanager
+
 from .hub import Hub
+from .scope import Scope
 from .utils import EventHint
 from .client import Client, get_options
 from .integrations import setup_integrations
 
 
+__all__ = ["Hub", "Scope", "Client", "EventHint"]
+
+
+def public(f):
+    __all__.append(f.__name__)
+    return f
+
+
 class _InitGuard(object):
     def __init__(self, client):
         self._client = client
@@ -25,8 +36,12 @@ def _init_on_hub(hub, args, kwargs):
     return _InitGuard(client)
 
 
+@public
 def init(*args, **kwargs):
-    """Initializes the SDK and optionally integrations."""
+    """Initializes the SDK and optionally integrations.
+
+    This takes the same arguments as the client constructor.
+    """
     return _init_on_hub(Hub.main, args, kwargs)
 
 
@@ -37,8 +52,62 @@ def _init_on_current(*args, **kwargs):
     return _init_on_hub(Hub.current, args, kwargs)
 
 
-from . import minimal as sentry_minimal
-from .minimal import *  # noqa
+@public
+def capture_event(event, hint=None):
+    """Alias for `Hub.current.capture_event`"""
+    hub = Hub.current
+    if hub is not None:
+        return hub.capture_event(event, hint)
+
+
+@public
+def capture_message(message, level=None):
+    """Alias for `Hub.current.capture_message`"""
+    hub = Hub.current
+    if hub is not None:
+        return hub.capture_message(message, level)
+
+
+@public
+def capture_exception(error=None):
+    """Alias for `Hub.current.capture_exception`"""
+    hub = Hub.current
+    if hub is not None:
+        return hub.capture_exception(error)
+
+
+@public
+def add_breadcrumb(*args, **kwargs):
+    """Alias for `Hub.current.add_breadcrumb`"""
+    hub = Hub.current
+    if hub is not None:
+        return hub.add_breadcrumb(*args, **kwargs)
+
+
+@public
+def configure_scope(callback=None):
+    """Alias for `Hub.current.configure_scope`"""
+    hub = Hub.current
+    if hub is not None:
+        return hub.configure_scope(callback)
+    elif callback is None:
+
+        @contextmanager
+        def inner():
+            yield Scope()
+
+        return inner()
+
+
+@public
+def get_current_hub():
+    """Alias for `Hub.current`"""
+    return Hub.current
+
 
-__all__ = ["Hub", "Scope", "Client", "EventHint", "init"]
-__all__ += sentry_minimal.__all__
+@public
+def last_event_id():
+    """Alias for `Hub.last_event_id`"""
+    hub = Hub.current
+    if hub is not None:
+        return hub.last_event_id()

sentry_sdk/client.py

@@ -40,6 +40,12 @@ def get_options(*args, **kwargs):
 
 
 class Client(object):
+    """The client is internally responsible for capturing the events and
+    forwarding them to sentry through the configured transport.  It takes
+    the client options as keyword arguments and optionally the DSN as first
+    argument.
+    """
+
     def __init__(self, *args, **kwargs):
         self.options = options = get_options(*args, **kwargs)
         self.transport = make_transport(options)
@@ -54,7 +60,7 @@ def __init__(self, *args, **kwargs):
 
     @property
     def dsn(self):
-        """Returns the configured dsn."""
+        """Returns the configured DSN as string."""
         return self.options["dsn"]
 
     def _prepare_event(self, event, hint, scope):
@@ -128,7 +134,15 @@ def _should_capture(self, event, hint=None, scope=None):
         return True
 
     def capture_event(self, event, hint=None, scope=None):
-        """Captures an event."""
+        """Captures an event.
+
+        This takes the ready made event and an optoinal hint and scope.  The
+        hint is internally used to further customize the representation of the
+        error.  For more information see `EventHint`.
+
+        If the transport is not set nothing happens, otherwise the return
+        value of this function will be the ID of the captured event.
+        """
         if self.transport is None:
             return
         rv = event.get("event_id")
@@ -143,6 +157,11 @@ def capture_event(self, event, hint=None, scope=None):
     def close(self, timeout=None, shutdown_callback=None):
         """Closes the client which shuts down the transport in an
         orderly manner.
+
+        The `shutdown_callback` is invoked with two arguments: the number of
+        pending events and the configured shutdown timeout.  For instance the
+        default atexit integration will use this to render out a message on
+        stderr.
         """
         if self.transport is not None:
             if timeout is None:

sentry_sdk/hub.py

@@ -35,6 +35,7 @@ def _should_send_default_pii():
 class HubMeta(type):
     @property
     def current(self):
+        """Returns the current instance of the hub."""
         rv = _local.get(None)
         if rv is None:
             rv = Hub(GLOBAL_HUB)
@@ -43,6 +44,7 @@ def current(self):
 
     @property
     def main(self):
+        """Returns the main instance of the hub."""
         return GLOBAL_HUB
 
 
@@ -68,6 +70,13 @@ def __exit__(self, exc_type, exc_value, tb):
 
 
 class Hub(with_metaclass(HubMeta)):
+    """The hub wraps the concurrency management of the SDK.  Each thread has
+    its own hub but the hub might transfer with the flow of execution if
+    context vars are available.
+
+    If the hub is used with a with statement it's temporarily activated.
+    """
+
     def __init__(self, client_or_hub=None, scope=None):
         if isinstance(client_or_hub, Hub):
             hub = client_or_hub
@@ -96,7 +105,7 @@ def run(self, callback):
         with statement can be used on the hub directly.
         """
         with self:
-            callback()
+            return callback()
 
     @property
     def client(self):

sentry_sdk/integrations/atexit.py

@@ -1,6 +1,7 @@
 from __future__ import absolute_import
 
 import os
+import sys
 import atexit
 
 from sentry_sdk.hub import Hub
@@ -9,9 +10,13 @@
 
 
 def default_shutdown_callback(pending, timeout):
-    print("Sentry is attempting to send %i pending error messages" % pending)
-    print("Waiting up to %s seconds" % timeout)
-    print("Press Ctrl-%s to quit" % (os.name == "nt" and "Break" or "C"))
+    def echo(msg):
+        sys.stderr.write(msg + "\n")
+
+    echo("Sentry is attempting to send %i pending error messages" % pending)
+    echo("Waiting up to %s seconds" % timeout)
+    echo("Press Ctrl-%s to quit" % (os.name == "nt" and "Break" or "C"))
+    sys.stderr.flush()
 
 
 class AtexitIntegration(Integration):