Added try-except-raise message example (#6540)

Co-authored-by: Vladyslav Krylasov <vladyslav.krylasov@gmail.com>
Co-authored-by: Pierre Sassoulas <pierre.sassoulas@gmail.com>
Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>

3 files changed, 30 insertions, 0 deletions

diff --git a/doc/data/messages/t/try-except-raise/bad.py b/doc/data/messages/t/try-except-raise/bad.py
new file mode 100644
index 000000000..8db8da44c
--- /dev/null
+++ b/doc/data/messages/t/try-except-raise/bad.py
@@ -0,0 +1,4 @@
+try:
+    1 / 0
+except ZeroDivisionError as e:  # [try-except-raise]
+    raise
diff --git a/doc/data/messages/t/try-except-raise/details.rst b/doc/data/messages/t/try-except-raise/details.rst
new file mode 100644
index 000000000..8d5423c7d
--- /dev/null
+++ b/doc/data/messages/t/try-except-raise/details.rst
@@ -0,0 +1,18 @@
+There is a legitimate use case for re-raising immediately. E.g. with the following inheritance tree::
+
+    +-- ArithmeticError
+         +-- FloatingPointError
+         +-- OverflowError
+         +-- ZeroDivisionError
+
+The following code shows valid case for re-raising exception immediately::
+
+    def execute_calculation(a, b):
+        try:
+            return some_calculation(a, b)
+        except ZeroDivisionError:
+            raise
+        except ArithmeticError:
+            return float('nan')
+
+The pylint is able to detect this case and does not produce error.
diff --git a/doc/data/messages/t/try-except-raise/good.py b/doc/data/messages/t/try-except-raise/good.py
new file mode 100644
index 000000000..27f19afc6
--- /dev/null
+++ b/doc/data/messages/t/try-except-raise/good.py
@@ -0,0 +1,8 @@
+# The try except might be removed entirely:
+1 / 0
+
+# Or another more detailed exception can be raised:
+try:
+    1 / 0
+except ZeroDivisionError as e:
+    raise ValueError("The area of the rectangle cannot be zero") from e