From eb0e435dae182363500c3e291f757a24b9df2e9d Mon Sep 17 00:00:00 2001
From: Adi Roiban <adi.roiban@chevah.com>
Date: Thu, 21 Dec 2023 09:18:42 +0000
Subject: [PATCH] Initial update for deprecation helpers.

---
 src/twisted/newsfragments/12063.removal   |  2 ++
 src/twisted/python/deprecate.py           |  8 +++++-
 src/twisted/python/test/test_deprecate.py | 30 +++++++++--------------
 3 files changed, 21 insertions(+), 19 deletions(-)
 create mode 100644 src/twisted/newsfragments/12063.removal

diff --git a/src/twisted/newsfragments/12063.removal b/src/twisted/newsfragments/12063.removal
new file mode 100644
index 00000000000..7958fc00d6e
--- /dev/null
+++ b/src/twisted/newsfragments/12063.removal
@@ -0,0 +1,2 @@
+twisted.python.deprecate helper function will now always strip the docstrings.
+This is done to have the same behaviour as with Python 3.13.
diff --git a/src/twisted/python/deprecate.py b/src/twisted/python/deprecate.py
index c85b98d6272..ffc2103a65c 100644
--- a/src/twisted/python/deprecate.py
+++ b/src/twisted/python/deprecate.py
@@ -258,8 +258,14 @@ def _appendToDocstring(thingWithDoc, textToAppend):
     elif len(docstringLines) == 1:
         docstringLines.extend(["", textToAppend, ""])
     else:
-        spaces = docstringLines.pop()
+        trailer = docstringLines[-1]
+        spaces = ""
+        if not trailer.strip():
+            # On Python 3.13 the docstring is already stripped.
+            # For older Python version we keep the trailer.
+            spaces = docstringLines.pop()
         docstringLines.extend(["", spaces + textToAppend, spaces])
+        docstringLines = [l.lstrip(" ") for l in docstringLines]
     thingWithDoc.__doc__ = "\n".join(docstringLines)
 
 
diff --git a/src/twisted/python/test/test_deprecate.py b/src/twisted/python/test/test_deprecate.py
index ff3b21cb469..fc91e1f22b4 100644
--- a/src/twisted/python/test/test_deprecate.py
+++ b/src/twisted/python/test/test_deprecate.py
@@ -876,12 +876,11 @@ def test_deprecatedReplacement(self):
         self.assertEqual(
             dummy.__doc__,
             "\n"
-            "    Do nothing.\n\n"
-            "    This is used to test the deprecation decorators.\n\n"
-            "    Deprecated in Twisted 8.0.0; please use "
+            "Do nothing.\n\n"
+            "This is used to test the deprecation decorators.\n\n"
+            "Deprecated in Twisted 8.0.0; please use "
             "something.foobar"
-            " instead.\n"
-            "    ",
+            " instead.\n",
         )
 
     def test_deprecatedReplacementWithCallable(self):
@@ -897,11 +896,10 @@ def test_deprecatedReplacementWithCallable(self):
         self.assertEqual(
             dummy.__doc__,
             "\n"
-            "    Do nothing.\n\n"
-            "    This is used to test the deprecation decorators.\n\n"
-            "    Deprecated in Twisted 8.0.0; please use "
-            "%s.dummyReplacementMethod instead.\n"
-            "    " % (__name__,),
+            "Do nothing.\n\n"
+            "This is used to test the deprecation decorators.\n\n"
+            "Deprecated in Twisted 8.0.0; please use "
+            "{}.dummyReplacementMethod instead.\n".format(__name__),
         )
 
     def test_deprecatedKeywordParameter(self):
@@ -993,15 +991,11 @@ def multiLineDocstring():
             This is a multi-line docstring.
             """
 
-        def expectedDocstring():
-            """
-            This is a multi-line docstring.
-
-            Appended text.
-            """
-
         _appendToDocstring(multiLineDocstring, "Appended text.")
-        self.assertEqual(expectedDocstring.__doc__, multiLineDocstring.__doc__)
+        self.assertEqual(
+            "\n" "This is a multi-line docstring.\n" "\n" "Appended text.\n",
+            multiLineDocstring.__doc__,
+        )
 
 
 class MutualArgumentExclusionTests(SynchronousTestCase):