Skip to content

Commit 44b8949

Browse files
untitakeruntitaker
authored
doc: Improve new API docs (getsentry#414)
* fix: Enable typing imports for docs * doc: More method docs, new doc theme * fix: Fix docs for Client
1 parent 1ba9013 commit 44b8949

37 files changed

+215
-128
lines changed

‎docs-requirements.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
sphinx
22
sphinx-rtd-theme
3-
git+https://github.com/untitaker/sphinx-autodoc-typehints@feat/type-hint-comments
3+
git+https://github.com/agronholm/sphinx-autodoc-typehints
44
typed_ast

‎docs/conf.py

+8-13
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
import os
44
import sys
55

6+
import typing
7+
8+
typing.TYPE_CHECKING = True
9+
610
#
711
# Configuration file for the Sphinx documentation builder.
812
#
@@ -36,6 +40,7 @@
3640
"sphinx_autodoc_typehints",
3741
"sphinx.ext.viewcode",
3842
"sphinx.ext.githubpages",
43+
"sphinx.ext.intersphinx",
3944
]
4045

4146
# Add any paths that contain templates here, relative to this directory.
@@ -74,19 +79,7 @@
7479

7580
on_rtd = os.environ.get("READTHEDOCS", None) == "True"
7681

77-
try:
78-
import sphinx_rtd_theme
79-
80-
html_theme = "sphinx_rtd_theme"
81-
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
82-
except ImportError:
83-
html_theme = "default"
84-
if not on_rtd:
85-
print("-" * 74)
86-
print(
87-
"Warning: sphinx-rtd-theme not installed, building with default " "theme."
88-
)
89-
print("-" * 74)
82+
html_theme = "alabaster"
9083

9184
# Theme options are theme-specific and customize the look and feel of a theme
9285
# further. For a list of options available for each theme, see the
@@ -188,3 +181,5 @@
188181

189182
# A list of files that should not be packed into the epub file.
190183
epub_exclude_files = ["search.html"]
184+
185+
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

‎docs/index.rst

+4
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,9 @@ This is the API documentation for `Sentry's Python SDK
66
<https://sentry.io/for/python/>`_. For full documentation and other resources
77
visit the `GitHub repository <https://github.com/getsentry/sentry-python>`_.
88

9+
.. inherited-members necessary because of hack for Client and init methods
10+
911
.. automodule:: sentry_sdk
1012
:members:
13+
14+
:inherited-members:

‎sentry_sdk/_compat.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import sys
22

3-
MYPY = False
3+
from sentry_sdk._types import MYPY
4+
45
if MYPY:
56
from typing import Optional
67
from typing import Tuple

‎sentry_sdk/_types.py

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
try:
2+
from typing import TYPE_CHECKING as MYPY
3+
except ImportError:
4+
MYPY = False
5+
6+
7+
if MYPY:
8+
from types import TracebackType
9+
from typing import Any
10+
from typing import Callable
11+
from typing import Dict
12+
from typing import Optional
13+
from typing import Tuple
14+
from typing import Type
15+
16+
ExcInfo = Tuple[
17+
Optional[Type[BaseException]], Optional[BaseException], Optional[TracebackType]
18+
]
19+
20+
Event = Dict[str, Any]
21+
Hint = Dict[str, Any]
22+
23+
Breadcrumb = Dict[str, Any]
24+
BreadcrumbHint = Dict[str, Any]
25+
26+
EventProcessor = Callable[[Event, Hint], Optional[Event]]
27+
ErrorProcessor = Callable[[Event, ExcInfo], Optional[Event]]
28+
BreadcrumbProcessor = Callable[[Breadcrumb, BreadcrumbHint], Optional[Breadcrumb]]

‎sentry_sdk/api.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,17 @@
44
from sentry_sdk.hub import Hub
55
from sentry_sdk.scope import Scope
66

7-
MYPY = False
7+
from sentry_sdk._types import MYPY
8+
89
if MYPY:
910
from typing import Any
1011
from typing import Optional
1112
from typing import overload
1213
from typing import Callable
1314
from typing import TypeVar
14-
from contextlib import ContextManager
15+
from typing import ContextManager
1516

16-
from sentry_sdk.utils import Event, Hint, Breadcrumb, BreadcrumbHint
17+
from sentry_sdk._types import Event, Hint, Breadcrumb, BreadcrumbHint
1718

1819
T = TypeVar("T")
1920
F = TypeVar("F", bound=Callable[..., Any])

‎sentry_sdk/client.py

+37-21
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
import uuid
33
import random
44
from datetime import datetime
5+
import socket
56

67
from sentry_sdk._compat import string_types, text_type, iteritems
78
from sentry_sdk.utils import (
@@ -17,15 +18,16 @@
1718
from sentry_sdk.integrations import setup_integrations
1819
from sentry_sdk.utils import ContextVar
1920

20-
MYPY = False
21+
from sentry_sdk._types import MYPY
22+
2123
if MYPY:
2224
from typing import Any
2325
from typing import Callable
2426
from typing import Dict
2527
from typing import Optional
2628

2729
from sentry_sdk.scope import Scope
28-
from sentry_sdk.utils import Event, Hint
30+
from sentry_sdk._types import Event, Hint
2931

3032

3133
_client_init_debug = ContextVar("client_init_debug")
@@ -58,6 +60,9 @@ def _get_options(*args, **kwargs):
5860
if rv["environment"] is None:
5961
rv["environment"] = os.environ.get("SENTRY_ENVIRONMENT")
6062

63+
if rv["server_name"] is None and hasattr(socket, "gethostname"):
64+
rv["server_name"] = socket.gethostname()
65+
6166
return rv # type: ignore
6267

6368

@@ -206,17 +211,20 @@ def _should_capture(
206211

207212
return True
208213

209-
def capture_event(self, event, hint=None, scope=None):
210-
# type: (Dict[str, Any], Optional[Any], Optional[Scope]) -> Optional[str]
214+
def capture_event(
215+
self,
216+
event, # type: Event
217+
hint=None, # type: Optional[Hint]
218+
scope=None, # type: Optional[Scope]
219+
):
220+
# type: (...) -> Optional[str]
211221
"""Captures an event.
212222
213-
This takes the ready made event and an optional hint and scope. The
214-
hint is internally used to further customize the representation of the
215-
error. When provided it's a dictionary of optional information such
216-
as exception info.
223+
:param event: A ready-made event that can be directly sent to Sentry.
224+
225+
: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.
217226
218-
If the transport is not set nothing happens, otherwise the return
219-
value of this function will be the ID of the captured event.
227+
: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.
220228
"""
221229
if self.transport is None:
222230
return None
@@ -233,26 +241,33 @@ def capture_event(self, event, hint=None, scope=None):
233241
self.transport.capture_event(event)
234242
return rv
235243

236-
def close(self, timeout=None, callback=None):
237-
# type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
244+
def close(
245+
self,
246+
timeout=None, # type: Optional[float]
247+
callback=None, # type: Optional[Callable[[int, float], None]]
248+
):
249+
# type: (...) -> None
238250
"""
239251
Close the client and shut down the transport. Arguments have the same
240-
semantics as `self.flush()`.
252+
semantics as :py:meth:`Client.flush`.
241253
"""
242254
if self.transport is not None:
243255
self.flush(timeout=timeout, callback=callback)
244256
self.transport.kill()
245257
self.transport = None
246258

247-
def flush(self, timeout=None, callback=None):
248-
# type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
259+
def flush(
260+
self,
261+
timeout=None, # type: Optional[float]
262+
callback=None, # type: Optional[Callable[[int, float], None]]
263+
):
264+
# type: (...) -> None
249265
"""
250-
Wait `timeout` seconds for the current events to be sent. If no
251-
`timeout` is provided, the `shutdown_timeout` option value is used.
266+
Wait for the current events to be sent.
267+
268+
:param timeout: Wait for at most `timeout` seconds. If no `timeout` is provided, the `shutdown_timeout` option value is used.
252269
253-
The `callback` is invoked with two arguments: the number of pending
254-
events and the configured timeout. For instance the default atexit
255-
integration will use this to render out a message on stderr.
270+
:param callback: Is invoked with the number of pending events and the configured timeout.
256271
"""
257272
if self.transport is not None:
258273
if timeout is None:
@@ -268,7 +283,8 @@ def __exit__(self, exc_type, exc_value, tb):
268283
self.close()
269284

270285

271-
MYPY = False
286+
from sentry_sdk._types import MYPY
287+
272288
if MYPY:
273289
# Make mypy, PyCharm and other static analyzers think `get_options` is a
274290
# type to have nicer autocompletion for params.

‎sentry_sdk/consts.py

+3-7
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
1-
import socket
1+
from sentry_sdk._types import MYPY
22

3-
MYPY = False
43
if MYPY:
54
from typing import Optional
65
from typing import Callable
@@ -13,10 +12,7 @@
1312
from sentry_sdk.transport import Transport
1413
from sentry_sdk.integrations import Integration
1514

16-
from sentry_sdk.utils import Event, EventProcessor, BreadcrumbProcessor
17-
18-
19-
DEFAULT_SERVER_NAME = socket.gethostname() if hasattr(socket, "gethostname") else None
15+
from sentry_sdk._types import Event, EventProcessor, BreadcrumbProcessor
2016

2117

2218
# This type exists to trick mypy and PyCharm into thinking `init` and `Client`
@@ -29,7 +25,7 @@ def __init__(
2925
max_breadcrumbs=100, # type: int
3026
release=None, # type: Optional[str]
3127
environment=None, # type: Optional[str]
32-
server_name=DEFAULT_SERVER_NAME, # type: Optional[str]
28+
server_name=None, # type: Optional[str]
3329
shutdown_timeout=2, # type: int
3430
integrations=[], # type: List[Integration]
3531
in_app_include=[], # type: List[str]

0 commit comments

Comments
 (0)