(1) Add new scopes related API (but not yet calling it)

docs/api.rst

@@ -41,6 +41,19 @@ Distributed Tracing
 .. autofunction:: sentry_sdk.api.get_traceparent
 
 
+New Scopes/Client APIs
+======================
+
+.. autofunction:: sentry_sdk.api.get_client
+.. autofunction:: sentry_sdk.api.sentry_is_initialized
+.. autofunction:: sentry_sdk.api.get_current_scope
+.. autofunction:: sentry_sdk.api.get_isolation_scope
+.. autofunction:: sentry_sdk.api.get_global_scope    
+
+.. autofunction:: sentry_sdk.api.set_current_scope
+.. autofunction:: sentry_sdk.api.set_isolation_scope
+
+
 Managing Scope (advanced)
 =========================
 

docs/apidocs.rst

@@ -11,6 +11,12 @@ API Docs
 .. autoclass:: sentry_sdk.Client
     :members:
 
+.. autoclass:: sentry_sdk.client._Client
+    :members:
+
+.. autoclass:: sentry_sdk.client.NoopClient
+    :members:
+
 .. autoclass:: sentry_sdk.Transport
     :members:
 

sentry_sdk/api.py

@@ -1,5 +1,6 @@
 import inspect
 
+from sentry_sdk import scope
 from sentry_sdk._types import TYPE_CHECKING
 from sentry_sdk.hub import Hub
 from sentry_sdk.scope import Scope
@@ -15,6 +16,7 @@
     from typing import ContextManager
     from typing import Union
 
+    from sentry_sdk.client import Client, NoopClient
     from sentry_sdk._types import (
         Event,
         Hint,
@@ -77,36 +79,93 @@
     return f
 
 
+def sentry_is_initialized():
+    # type: () -> bool
+    """
+    Returns whether Sentry has been initialized or not.
+    If an client is available Sentry is initialized.
+
+    .. versionadded:: 1.XX.0
+    """
+    return Scope.get_client().is_active()
+
+
+@scopemethod
+def get_client():
+    # type: () -> Union[Client, NoopClient]
+    return Scope.get_client()
+
+
+@scopemethod
+def get_current_scope():
+    # type: () -> Scope
+    return Scope.get_current_scope()
+
+
+@scopemethod
+def get_isolation_scope():
+    # type: () -> Scope
+    return Scope.get_isolation_scope()
+
+
+@scopemethod
+def get_global_scope():
+    # type: () -> Scope
+    return Scope.get_global_scope()
+
+
+def set_current_scope(new_current_scope):
+    # type: (Scope) -> None
+    """
+    Sets the given scope as the new current scope overwritting the existing current scope.
+    :param new_current_scope: The scope to set as the new current scope.
+
+    .. versionadded:: 1.XX.0
+    """
+    scope.sentry_current_scope.set(new_current_scope)
+
+
+def set_isolation_scope(new_isolation_scope):
+    # type: (Scope) -> None
+    """
+    Sets the given scope as the new isolation scope overwritting the existing isolation scope.
+    :param new_isolation_scope: The scope to set as the new isolation scope.
+
+    .. versionadded:: 1.XX.0
+    """
+    scope.sentry_isolation_scope.set(new_isolation_scope)
+
+
 @hubmethod
 def capture_event(
     event,  # type: Event
     hint=None,  # type: Optional[Hint]
     scope=None,  # type: Optional[Any]
-    **scope_args  # type: Any
+    **scope_kwargs  # type: Any
 ):
     # type: (...) -> Optional[str]
-    return Hub.current.capture_event(event, hint, scope=scope, **scope_args)
+    return Hub.current.capture_event(event, hint, scope=scope, **scope_kwargs)
 
 
 @hubmethod
 def capture_message(
     message,  # type: str
     level=None,  # type: Optional[str]
     scope=None,  # type: Optional[Any]
-    **scope_args  # type: Any
+    **scope_kwargs  # type: Any
 ):
     # type: (...) -> Optional[str]
-    return Hub.current.capture_message(message, level, scope=scope, **scope_args)
+    return Hub.current.capture_message(message, level, scope=scope, **scope_kwargs)
 
 
 @hubmethod
 def capture_exception(
     error=None,  # type: Optional[Union[BaseException, ExcInfo]]
     scope=None,  # type: Optional[Any]
-    **scope_args  # type: Any
+    **scope_kwargs  # type: Any
 ):
     # type: (...) -> Optional[str]
-    return Hub.current.capture_exception(error, scope=scope, **scope_args)
+    return Hub.current.capture_exception(error, scope=scope, **scope_kwargs)
 
 
 @hubmethod

sentry_sdk/client.py

@@ -43,7 +43,10 @@
     from typing import Dict
     from typing import Optional
     from typing import Sequence
+    from typing import Type
+    from typing import Union
 
+    from sentry_sdk.integrations import Integration
     from sentry_sdk.scope import Scope
     from sentry_sdk._types import Event, Hint
     from sentry_sdk.session import Session
@@ -148,11 +151,116 @@
     module_not_found_error = ImportError  # type: ignore
 
 
-class _Client(object):
+class NoopClient:
+    """
+    A client that does not send any events to Sentry. This is used as a fallback when the Sentry SDK is not yet initialized.
+
+    .. versionadded:: 1.XX.0
+    """
+
+    options = _get_options()  # type: Dict[str, Any]
+    metrics_aggregator = None  # type: Optional[Any]
+    monitor = None  # type: Optional[Any]
+    transport = None  # type: Optional[Any]
+
+    def __repr__(self):
+        # type: () -> str
+        return "<{} id={}>".format(self.__class__.__name__, id(self))
+
+    def should_send_default_pii(self):
+        # type: () -> bool
+        return False
+
+    def __init__(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def __getstate__(self, *args, **kwargs):
+        # type: (*Any, **Any) -> Any
+        return {"options": {}}
+
+    def __setstate__(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        pass
+
+    def _setup_instrumentation(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def _init_impl(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def is_active(self):
+        # type: () -> bool
+        """
+        Returns weither the client is active (able to send data to Sentry)
+
+        .. versionadded:: 1.XX.0
+        """
+        return False
+
+    @property
+    def dsn(self):
+        # type: () -> Optional[str]
+        return None
+
+    def _prepare_event(self, *args, **kwargs):
+        # type: (*Any, **Any) -> Optional[Any]
+        return None
+
+    def _is_ignored_error(self, *args, **kwargs):
+        # type: (*Any, **Any) -> bool
+        return True
+
+    def _should_capture(self, *args, **kwargs):
+        # type: (*Any, **Any) -> bool
+        return False
+
+    def _should_sample_error(self, *args, **kwargs):
+        # type: (*Any, **Any) -> bool
+        return False
+
+    def _update_session_from_event(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def capture_event(self, *args, **kwargs):
+        # type: (*Any, **Any) -> Optional[str]
+        return None
+
+    def capture_session(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def get_integration(self, *args, **kwargs):
+        # type: (*Any, **Any) -> Any
+        return None
+
+    def close(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def flush(self, *args, **kwargs):
+        # type: (*Any, **Any) -> None
+        return None
+
+    def __enter__(self):
+        # type: () -> NoopClient
+        return self
+
+    def __exit__(self, exc_type, exc_value, tb):
+        # type: (Any, Any, Any) -> None
+        return None
+
+
+class _Client(NoopClient):
     """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.
+
+    Alias of :py:class:`sentry_sdk.Client`. (Was created for better intelisense support)
     """
 
     def __init__(self, *args, **kwargs):
@@ -292,6 +400,15 @@
 
         self._setup_instrumentation(self.options.get("functions_to_trace", []))
 
+    def is_active(self):
+        # type: () -> bool
+        """
+        Returns weither the client is active (able to send data to Sentry)
+
+        .. versionadded:: 1.XX.0
+        """
+        return True
+
     @property
     def dsn(self):
         # type: () -> Optional[str]
@@ -557,8 +674,8 @@
 
         :param hint: Contains metadata about the event that can be read from `before_send`, such as the original exception object or a HTTP request object.
 
-        :param scope: An optional scope to use for determining whether this event
-            should be captured.
+        :param scope: An optional :py:class:`sentry_sdk.Scope` to apply to events.
+            The `scope` and `scope_kwargs` parameters are mutually exclusive.
 
         :returns: An event ID. May be `None` if there is no DSN set or of if the SDK decided to discard the event for other reasons. In such situations setting `debug=True` on `init()` may help.
         """
@@ -661,6 +778,22 @@
         else:
             self.session_flusher.add_session(session)
 
+    def get_integration(
+        self, name_or_class  # type: Union[str, Type[Integration]]
+    ):
+        # type: (...) -> Any
+        """Returns the integration for this client by name or class.
+        If the client does not have that integration then `None` is returned.
+        """
+        if isinstance(name_or_class, str):
+            integration_name = name_or_class
+        elif name_or_class.identifier is not None:
+            integration_name = name_or_class.identifier
+        else:
+            raise ValueError("Integration has no name")
+
+        return self.integrations.get(integration_name)
+
     def close(
         self,
         timeout=None,  # type: Optional[float]