document that we raise CryptographyDeprecationWarning on deprecation …

…more clearly (#10053)

* document we raise CryptographyDeprecationWarning clearly

* be a little louder about our deprecated ciphers

docs/api-stability.rst

@@ -66,9 +66,9 @@ entirely. In that case, here's how the process will work:
 
 * In ``cryptography X.0.0`` the feature exists.
 * In ``cryptography (X + 1).0.0`` using that feature will emit a
-  ``UserWarning``.
+  ``CryptographyDeprecationWarning`` (base class ``UserWarning``).
 * In ``cryptography (X + 2).0.0`` using that feature will emit a
-  ``UserWarning``.
+  ``CryptographyDeprecationWarning``.
 * In ``cryptography (X + 3).0.0`` the feature will be removed or changed.
 
 In short, code that runs without warnings will always continue to work for a

src/cryptography/hazmat/primitives/ciphers/algorithms.py

@@ -104,7 +104,7 @@ def key_size(self) -> int:
 utils.deprecated(
     Blowfish,
     __name__,
-    "Blowfish has been deprecated",
+    "Blowfish has been deprecated and will be removed in a future release",
     utils.DeprecatedIn37,
     name="Blowfish",
 )
@@ -127,7 +127,7 @@ def key_size(self) -> int:
 utils.deprecated(
     CAST5,
     __name__,
-    "CAST5 has been deprecated",
+    "CAST5 has been deprecated and will be removed in a future release",
     utils.DeprecatedIn37,
     name="CAST5",
 )
@@ -162,7 +162,7 @@ def key_size(self) -> int:
 utils.deprecated(
     IDEA,
     __name__,
-    "IDEA has been deprecated",
+    "IDEA has been deprecated and will be removed in a future release",
     utils.DeprecatedIn37,
     name="IDEA",
 )
@@ -185,7 +185,7 @@ def key_size(self) -> int:
 utils.deprecated(
     SEED,
     __name__,
-    "SEED has been deprecated",
+    "SEED has been deprecated and will be removed in a future release",
     utils.DeprecatedIn37,
     name="SEED",
 )