From ced20b5cab8dfddaa719200334ee928b7cc3cf21 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <stephen@that.guru>
Date: Mon, 13 Dec 2021 17:26:04 +0000
Subject: [PATCH] Deprecate distutils integration

We don't want to remove this immediately, but we should try to do so
sooner rather than later.

Signed-off-by: Stephen Finucane <stephen@that.guru>
Closes: #316
---
 NEWS                      |  5 ++++-
 doc/for-test-authors.rst  |  8 ++++++++
 testtools/distutilscmd.py | 12 ++++++++++--
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/NEWS b/NEWS
index cf7f84f0..a805a12f 100644
--- a/NEWS
+++ b/NEWS
@@ -12,6 +12,9 @@ Improvements
 * Add support for Python 3.10.
   (Jürgen Gmach)
 
+* Distutils integration is deprecated and will be removed in the next major
+  version.
+
 2.5.0
 ~~~~~
 
@@ -39,7 +42,7 @@ Changes
 
 * The ``safe_hasattr`` utility has been removed from ``testtools.helpers``.
   This was a compat wrapper introduced in 0.9.25 when the utility itself was
-  moved to the ``extras`` package. It is no longer useless on Python 3-only
+  moved to the ``extras`` package. It is not necessary with Python 3-only
   projects.
 
 * The ``try_imports`` utility has been removed from ``testtools.helpers``.
diff --git a/doc/for-test-authors.rst b/doc/for-test-authors.rst
index 90bd3cac..52611544 100644
--- a/doc/for-test-authors.rst
+++ b/doc/for-test-authors.rst
@@ -92,6 +92,14 @@ From now on, we'll assume that you know how to run your tests.
 Running test with Distutils
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. deprecated:: 2.6.0
+
+    Distutils integration was deprecated in 2.6.0. You should consider
+    replacing invocations of ``python setup.py test`` with a suitable
+    alternative such as ``tox``. Refer to `this issue`__ for more information.
+
+    .. __: https://github.com/pypa/setuptools/issues/1684
+
 If you are using Distutils_ to build your Python project, you can use the testtools
 Distutils_ command to integrate testtools into your Distutils_ workflow::
 
diff --git a/testtools/distutilscmd.py b/testtools/distutilscmd.py
index a4d79dc8..eedc4ff2 100644
--- a/testtools/distutilscmd.py
+++ b/testtools/distutilscmd.py
@@ -3,6 +3,7 @@
 """Extensions to the standard Python unittest library."""
 
 import sys
+import warnings
 
 from distutils.core import Command
 from distutils.errors import DistutilsOptionError
@@ -19,8 +20,8 @@ class TestCommand(Command):
         ('catch', 'c', "Catch ctrl-C and display results so far"),
         ('buffer', 'b', "Buffer stdout and stderr during tests"),
         ('failfast', 'f', "Stop on first fail or error"),
-        ('test-module=','m', "Run 'test_suite' in specified module"),
-        ('test-suite=','s',
+        ('test-module=', 'm', "Run 'test_suite' in specified module"),
+        ('test-suite=', 's',
          "Test suite to run (e.g. 'some_module.test_suite')")
     ]
 
@@ -28,6 +29,13 @@ def __init__(self, dist):
         Command.__init__(self, dist)
         self.runner = TestToolsTestRunner(stdout=sys.stdout)
 
+        warnings.warn(
+            "Distutils integration is deprecated and will be removed in the "
+            "next major release. "
+            "Refer to https://github.com/pypa/setuptools/issues/1684 for more "
+            "information.",
+            DeprecationWarning,
+        )
 
     def initialize_options(self):
         self.test_suite = None