Skip to content

Commit 7719950

Browse files
sentrivanasentrivana
authored
Allow (some) autocompletion for top-level API (#2213)
1 parent 8051d92 commit 7719950

File tree

5 files changed

+106
-79
lines changed

5 files changed

+106
-79
lines changed

‎docs/api.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,9 @@ Main API
77
.. automodule:: sentry_sdk
88
:members:
99
:inherited-members:
10+
11+
.. autoclass:: sentry_sdk.tracing.Span
12+
:members:
13+
14+
.. autoclass:: sentry_sdk.tracing.Transaction
15+
:members:

‎sentry_sdk/api.py‎

Lines changed: 28 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
import inspect
2+
from functools import partial
23

34
from sentry_sdk._types import TYPE_CHECKING
45
from sentry_sdk.hub import Hub
56
from sentry_sdk.scope import Scope
6-
from sentry_sdk.tracing import NoOpSpan, Transaction
7+
from sentry_sdk.tracing import Transaction
78

89
if TYPE_CHECKING:
910
from typing import Any
@@ -13,16 +14,8 @@
1314
from typing import Callable
1415
from typing import TypeVar
1516
from typing import ContextManager
16-
from typing import Union
17-
18-
from sentry_sdk._types import (
19-
Event,
20-
Hint,
21-
Breadcrumb,
22-
BreadcrumbHint,
23-
ExcInfo,
24-
MeasurementUnit,
25-
)
17+
18+
from sentry_sdk._types import MeasurementUnit
2619
from sentry_sdk.tracing import Span
2720

2821
T = TypeVar("T")
@@ -77,46 +70,36 @@ def scopemethod(f):
7770
return f
7871

7972

80-
@hubmethod
81-
def capture_event(
82-
event, # type: Event
83-
hint=None, # type: Optional[Hint]
84-
scope=None, # type: Optional[Any]
85-
**scope_args # type: Any
86-
):
87-
# type: (...) -> Optional[str]
88-
return Hub.current.capture_event(event, hint, scope=scope, **scope_args)
73+
# Alias these functions to have nice auto completion for the arguments without
74+
# having to specify them here. The `partial(..., None)` hack is needed for Sphinx
75+
# to generate proper docs for these.
76+
if TYPE_CHECKING:
77+
capture_event = partial(Hub.capture_event, None)
78+
capture_message = partial(Hub.capture_message, None)
79+
capture_exception = partial(Hub.capture_exception, None)
80+
add_breadcrumb = partial(Hub.add_breadcrumb, None)
81+
start_span = partial(Hub.start_span, None)
82+
start_transaction = partial(Hub.start_transaction, None)
8983

84+
else:
9085

91-
@hubmethod
92-
def capture_message(
93-
message, # type: str
94-
level=None, # type: Optional[str]
95-
scope=None, # type: Optional[Any]
96-
**scope_args # type: Any
97-
):
98-
# type: (...) -> Optional[str]
99-
return Hub.current.capture_message(message, level, scope=scope, **scope_args)
86+
def capture_event(*args, **kwargs):
87+
return Hub.current.capture_event(*args, **kwargs)
10088

89+
def capture_message(*args, **kwargs):
90+
return Hub.current.capture_message(*args, **kwargs)
10191

102-
@hubmethod
103-
def capture_exception(
104-
error=None, # type: Optional[Union[BaseException, ExcInfo]]
105-
scope=None, # type: Optional[Any]
106-
**scope_args # type: Any
107-
):
108-
# type: (...) -> Optional[str]
109-
return Hub.current.capture_exception(error, scope=scope, **scope_args)
92+
def capture_exception(*args, **kwargs):
93+
return Hub.current.capture_exception(*args, **kwargs)
11094

95+
def add_breadcrumb(*args, **kwargs):
96+
return Hub.current.add_breadcrumb(*args, **kwargs)
11197

112-
@hubmethod
113-
def add_breadcrumb(
114-
crumb=None, # type: Optional[Breadcrumb]
115-
hint=None, # type: Optional[BreadcrumbHint]
116-
**kwargs # type: Any
117-
):
118-
# type: (...) -> None
119-
return Hub.current.add_breadcrumb(crumb, hint, **kwargs)
98+
def start_span(*args, **kwargs):
99+
return Hub.current.start_span(*args, **kwargs)
100+
101+
def start_transaction(*args, **kwargs):
102+
return Hub.current.start_transaction(*args, **kwargs)
120103

121104

122105
@overload
@@ -208,24 +191,6 @@ def last_event_id():
208191
return Hub.current.last_event_id()
209192

210193

211-
@hubmethod
212-
def start_span(
213-
span=None, # type: Optional[Span]
214-
**kwargs # type: Any
215-
):
216-
# type: (...) -> Span
217-
return Hub.current.start_span(span=span, **kwargs)
218-
219-
220-
@hubmethod
221-
def start_transaction(
222-
transaction=None, # type: Optional[Transaction]
223-
**kwargs # type: Any
224-
):
225-
# type: (...) -> Union[Transaction, NoOpSpan]
226-
return Hub.current.start_transaction(transaction, **kwargs)
227-
228-
229194
def set_measurement(name, value, unit=""):
230195
# type: (str, float, MeasurementUnit) -> None
231196
transaction = Hub.current.scope.transaction

‎sentry_sdk/client.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -469,6 +469,9 @@ def capture_event(
469469
470470
: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.
471471
472+
:param scope: An optional scope to use for determining whether this event
473+
should be captured.
474+
472475
: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.
473476
"""
474477
if disable_capture_event.get(False):

‎sentry_sdk/hub.py‎

Lines changed: 61 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -335,7 +335,14 @@ def bind_client(
335335

336336
def capture_event(self, event, hint=None, scope=None, **scope_args):
337337
# type: (Event, Optional[Hint], Optional[Scope], Any) -> Optional[str]
338-
"""Captures an event. Alias of :py:meth:`sentry_sdk.Client.capture_event`."""
338+
"""
339+
Captures an event.
340+
341+
Alias of :py:meth:`sentry_sdk.Client.capture_event`.
342+
343+
:param scope_args: For supported `**scope_args` see
344+
:py:meth:`sentry_sdk.Scope.update_from_kwargs`.
345+
"""
339346
client, top_scope = self._stack[-1]
340347
scope = _update_scope(top_scope, scope, scope_args)
341348
if client is not None:
@@ -348,8 +355,17 @@ def capture_event(self, event, hint=None, scope=None, **scope_args):
348355

349356
def capture_message(self, message, level=None, scope=None, **scope_args):
350357
# type: (str, Optional[str], Optional[Scope], Any) -> Optional[str]
351-
"""Captures a message. The message is just a string. If no level
352-
is provided the default level is `info`.
358+
"""
359+
Captures a message.
360+
361+
:param message: The string to send as the message.
362+
363+
:param level: If no level is provided, the default level is `info`.
364+
365+
:param scope: An optional :py:class:`sentry_sdk.Scope` to use.
366+
367+
:param scope_args: For supported `**scope_args` see
368+
:py:meth:`sentry_sdk.Scope.update_from_kwargs`.
353369
354370
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
355371
"""
@@ -367,6 +383,9 @@ def capture_exception(self, error=None, scope=None, **scope_args):
367383
368384
:param error: An exception to catch. If `None`, `sys.exc_info()` will be used.
369385
386+
:param scope_args: For supported `**scope_args` see
387+
:py:meth:`sentry_sdk.Scope.update_from_kwargs`.
388+
370389
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
371390
"""
372391
client = self.client
@@ -397,22 +416,48 @@ def _capture_internal_exception(
397416
"""
398417
logger.error("Internal error in sentry_sdk", exc_info=exc_info)
399418

400-
def add_breadcrumb(self, crumb=None, hint=None, **kwargs):
401-
# type: (Optional[Breadcrumb], Optional[BreadcrumbHint], Any) -> None
419+
def add_breadcrumb(
420+
self,
421+
crumb=None, # type: Optional[Breadcrumb]
422+
hint=None, # type: Optional[BreadcrumbHint]
423+
timestamp=None, # type: Optional[datetime]
424+
type=None, # type: Optional[str]
425+
data=None, # type: Optional[Dict[str, Any]]
426+
**kwargs # type: Any
427+
):
428+
# type: (...) -> None
402429
"""
403430
Adds a breadcrumb.
404431
405-
:param crumb: Dictionary with the data as the sentry v7/v8 protocol expects.
432+
:param crumb: Dictionary with the data as the Sentry v7/v8 protocol expects.
406433
407434
:param hint: An optional value that can be used by `before_breadcrumb`
408435
to customize the breadcrumbs that are emitted.
436+
437+
:param timestamp: The timestamp associated with this breadcrumb. Defaults
438+
to now if not provided.
439+
440+
:param type: The type of the breadcrumb. Will be set to "default" if
441+
not provided.
442+
443+
:param data: Additional custom data to put on the breadcrumb.
444+
445+
:param kwargs: Adding any further keyword arguments will not result in
446+
an error, but the breadcrumb will be dropped before arriving to
447+
Sentry.
409448
"""
410449
client, scope = self._stack[-1]
411450
if client is None:
412451
logger.info("Dropped breadcrumb because no client bound")
413452
return
414453

415454
crumb = dict(crumb or ()) # type: Breadcrumb
455+
if timestamp is not None:
456+
crumb["timestamp"] = timestamp
457+
if type is not None:
458+
crumb["type"] = type
459+
if data is not None:
460+
crumb["data"] = data
416461
crumb.update(kwargs)
417462
if not crumb:
418463
return
@@ -441,15 +486,19 @@ def add_breadcrumb(self, crumb=None, hint=None, **kwargs):
441486
def start_span(self, span=None, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
442487
# type: (Optional[Span], str, Any) -> Span
443488
"""
444-
Create and start timing a new span whose parent is the currently active
445-
span or transaction, if any. The return value is a span instance,
489+
Start a span whose parent is the currently active span or transaction, if any.
490+
491+
The return value is a :py:class:`sentry_sdk.tracing.Span` instance,
446492
typically used as a context manager to start and stop timing in a `with`
447493
block.
448494
449495
Only spans contained in a transaction are sent to Sentry. Most
450496
integrations start a transaction at the appropriate time, for example
451-
for every incoming HTTP request. Use `start_transaction` to start a new
452-
transaction when one is not already in progress.
497+
for every incoming HTTP request. Use
498+
:py:meth:`sentry_sdk.start_transaction` to start a new transaction when
499+
one is not already in progress.
500+
501+
For supported `**kwargs` see :py:class:`sentry_sdk.tracing.Span`.
453502
"""
454503
configuration_instrumenter = self.client and self.client.options["instrumenter"]
455504

@@ -515,6 +564,8 @@ def start_transaction(
515564
516565
When the transaction is finished, it will be sent to Sentry with all its
517566
finished child spans.
567+
568+
For supported `**kwargs` see :py:class:`sentry_sdk.tracing.Transaction`.
518569
"""
519570
configuration_instrumenter = self.client and self.client.options["instrumenter"]
520571

‎sentry_sdk/tracing.py‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -241,7 +241,7 @@ def start_child(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
241241

242242
def new_span(self, **kwargs):
243243
# type: (**Any) -> Span
244-
"""Deprecated: use start_child instead."""
244+
"""Deprecated: use :py:meth:`sentry_sdk.tracing.Span.start_child` instead."""
245245
logger.warning("Deprecated: use Span.start_child instead of Span.new_span.")
246246
return self.start_child(**kwargs)
247247

@@ -330,11 +330,10 @@ def from_traceparent(
330330
):
331331
# type: (...) -> Optional[Transaction]
332332
"""
333-
DEPRECATED: Use Transaction.continue_from_headers(headers, **kwargs)
334-
335-
Create a Transaction with the given params, then add in data pulled from
336-
the given 'sentry-trace' header value before returning the Transaction.
333+
DEPRECATED: Use :py:meth:`sentry_sdk.tracing.Transaction.continue_from_headers`.
337334
335+
Create a `Transaction` with the given params, then add in data pulled from
336+
the given 'sentry-trace' header value before returning the `Transaction`.
338337
"""
339338
logger.warning(
340339
"Deprecated: Use Transaction.continue_from_headers(headers, **kwargs) "
@@ -826,7 +825,9 @@ def trace(func=None):
826825
Decorator to start a child span under the existing current transaction.
827826
If there is no current transaction, then nothing will be traced.
828827
829-
Usage:
828+
.. code-block::
829+
:caption: Usage
830+
830831
import sentry_sdk
831832
832833
@sentry_sdk.trace
@@ -836,6 +837,7 @@ def my_function():
836837
@sentry_sdk.trace
837838
async def my_async_function():
838839
...
840+
839841
"""
840842
if PY2:
841843
from sentry_sdk.tracing_utils_py2 import start_child_span_decorator

0 commit comments

Comments
 (0)