Browse Source

📝 Use BaseException instead of Exception in raises as suggested by @Kludex

pull/10162/head
Sebastián Ramírez 3 years ago
parent
commit
116749ac7f
  1. 4
      typing_doc.md

4
typing_doc.md

@ -40,7 +40,7 @@ This `doc()` function would receive several parameters for metadata and document
* This could probably contain markup, like Markdown or reST. As that could be highly debated, that decision is left for a future proposal, to focus here on the main functionality.
* `deprecated: bool`: this would mark a parameter, class, function, or method as deprecated. Editors could display it with a strike-through or other appropriate formatting.
* `discouraged: bool`: this would mark a parameter, class, function, or method as discouraged. Editors could display them similar to `deprecated`. The reason why having a `discouraged` apart from `deprecated` is that there are cases where something is not gonna be removed for backward compatibility, but it shouldn't be used in new code. An example of this is `datetime.utcnow()`.
* `raises: Sequence[Type[Exception]]`: in a class, function, or method, this indicates the types of exceptions that could be raised by calling it. Editors and tooling could show a warning (e.g. a colored underline) if the call is not wrapped in a `try` block or the parent caller doesn't include the same exceptions in its `raises` parameter.
* `raises: Sequence[Type[BaseException]]`: in a class, function, or method, this indicates the types of exceptions that could be raised by calling it. Editors and tooling could show a warning (e.g. a colored underline) if the call is not wrapped in a `try` block or the parent caller doesn't include the same exceptions in its `raises` parameter.
* `extra: dict`: a dictionary containing any additional metadata that could be useful for developers or library authors.
* An `extra` parameter instead of `**kwargs` is proposed to allow adding future standard parameters.
* `**kwargs: Any`: allows arbitrary additional keyword args. This gives type checkers the freedom to support experimental parameters without needing to wait for changes in `typing.py`. Type checkers should report errors for any unrecognized parameters. This follows the same pattern designed in [PEP 681 – Data Class Transforms](https://peps.python.org/pep-0681/).
@ -140,7 +140,7 @@ def __typing_doc__(
description: str | None = None,
deprecated: bool = False,
discouraged: bool = False,
raises: Sequence[Type[Exception]] | None = None,
raises: Sequence[Type[BaseException]] | None = None,
extra: dict[Any, Any] | None = None,
) -> Callable[[_T], _T]:
# If used within a stub file, the following implementation can be

Loading…
Cancel
Save