From 836b6838f528f353c0dfb0a469a27f40ec9e1285 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 5 Dec 2022 21:02:56 +0100 Subject: [PATCH] =?utf8?q?=F0=9F=93=9D=20=F0=9F=93=9D=20Add=20raises=20par?= =?utf8?q?ameter=20as=20suggested=20in=20an=20informal=20chat=20with=20@Kl?= =?utf8?q?udex?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit --- typing_doc.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/typing_doc.md b/typing_doc.md index a92a0a76f2..0dbff4ab0f 100644 --- a/typing_doc.md +++ b/typing_doc.md @@ -40,6 +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. * `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/). @@ -73,7 +74,7 @@ An example documenting a function could look like this: ```python from typing import Annotated, doc -@doc(description="Create a new user in the system") +@doc(description="Create a new user in the system", raises=[InvalidUserError, UserExistsError]) def create_user( lastname: Annotated[ str, doc(description="The **last name** of the newly created user") -- 2.47.3