move MACContext to mac.py and eliminate interfaces.py (#3631)

* move MACContext to mac.py and eliminate interfaces.py finally

* improve title

* re-add and deprecate interfaces.MACContext

* use pytest.warns instead of deprecated_call

The pytest docs insist that deprecation warnings are handled differently
and that you should use deprecated_call, but this works so okay then

6 files changed, 38 insertions, 87 deletions

diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index e3c67474..4d0520fa 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -159,14 +159,14 @@ A specific ``backend`` may provide one or more of these interfaces.
     .. method:: create_cmac_ctx(algorithm)
 
         Create a
-        :class:`~cryptography.hazmat.primitives.interfaces.MACContext` that
+        :class:`~cryptography.hazmat.primitives.mac.MACContext` that
         uses the specified ``algorithm`` to calculate a message authentication code.
 
         :param algorithm: An instance of
             :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`.
 
         :returns:
-            :class:`~cryptography.hazmat.primitives.interfaces.MACContext`
+            :class:`~cryptography.hazmat.primitives.mac.MACContext`
 
 
 .. class:: PBKDF2HMACBackend
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index cf27622a..022cb9fb 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -14,5 +14,4 @@ Primitives
     keywrap
     asymmetric/index
     constant-time
-    interfaces
     twofactor
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
deleted file mode 100644
index d60fe186..00000000
--- a/docs/hazmat/primitives/interfaces.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-.. hazmat::
-
-.. module:: cryptography.hazmat.primitives.interfaces
-
-Interfaces
-==========
-
-
-``cryptography`` uses `Abstract Base Classes`_ as interfaces to describe the
-properties and methods of most primitive constructs. Backends may also use
-this information to influence their operation. Interfaces should also be used
-to document argument and return types.
-
-.. _`Abstract Base Classes`: https://docs.python.org/3/library/abc.html
-
-
-Asymmetric interfaces
----------------------
-
-In 0.8 the asymmetric signature and verification interfaces were moved to the
-:mod:`cryptography.hazmat.primitives.asymmetric` module.
-
-In 0.8 the asymmetric padding interface was moved to the
-:mod:`cryptography.hazmat.primitives.asymmetric.padding` module.
-
-DSA
-~~~
-
-In 0.8 the DSA key interfaces were moved to the
-:mod:`cryptography.hazmat.primitives.asymmetric.dsa` module.
-
-
-RSA
-~~~
-
-In 0.8 the RSA key interfaces were moved to the
-:mod:`cryptography.hazmat.primitives.asymmetric.rsa` module.
-
-
-Elliptic Curve
-~~~~~~~~~~~~~~
-
-In 0.8 the EC key interfaces were moved to the
-:mod:`cryptography.hazmat.primitives.asymmetric.ec` module.
-
-
-Key derivation functions
-------------------------
-
-In 0.8 the key derivation function interface was moved to the
-:mod:`cryptography.hazmat.primitives.kdf` module.
-
-
-.. class:: MACContext
-
-    .. versionadded:: 0.7
-
-    .. method:: update(data)
-
-        :param bytes data: The data you want to authenticate.
-
-    .. method:: finalize()
-
-        :return: The message authentication code.
-
-    .. method:: copy()
-
-        :return: A
-            :class:`~cryptography.hazmat.primitives.interfaces.MACContext` that
-            is a copy of the current context.
-
-    .. method:: verify(signature)
-
-        :param bytes signature: The signature to verify.
-
-        :raises cryptography.exceptions.InvalidSignature: This is raised when
-            the provided signature does not match the expected signature.
-
-
-.. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst
index e170db31..b316e4c3 100644
--- a/docs/hazmat/primitives/mac/cmac.rst
+++ b/docs/hazmat/primitives/mac/cmac.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-Cipher-based message authentication code
-========================================
+Cipher-based message authentication code (CMAC)
+===============================================
 
 .. currentmodule:: cryptography.hazmat.primitives.cmac
 
diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
index e00c4de2..a0e2014d 100644
--- a/docs/hazmat/primitives/mac/hmac.rst
+++ b/docs/hazmat/primitives/mac/hmac.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-Hash-based message authentication codes
-=======================================
+Hash-based message authentication codes (HMAC)
+==============================================
 
 .. currentmodule:: cryptography.hazmat.primitives.hmac
 
diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst
index 05db708c..86c407c4 100644
--- a/docs/hazmat/primitives/mac/index.rst
+++ b/docs/hazmat/primitives/mac/index.rst
@@ -9,6 +9,38 @@ recommend that HMAC should be used unless you have a good reason otherwise.
 For more information on why HMAC is preferred, see `Use cases for CMAC vs.
 HMAC?`_
 
+HMAC and CMAC both use the ``MACContext`` interface:
+
+.. currentmodule:: cryptography.hazmat.primitives.mac
+
+.. class:: MACContext
+
+    .. versionadded:: 0.7
+
+    .. method:: update(data)
+
+        :param bytes data: The data you want to authenticate.
+
+    .. method:: finalize()
+
+        :return: The message authentication code.
+
+    .. method:: copy()
+
+        :return: A
+            :class:`~cryptography.hazmat.primitives.mac.MACContext` that
+            is a copy of the current context.
+
+    .. method:: verify(signature)
+
+        :param bytes signature: The signature to verify.
+
+        :raises cryptography.exceptions.InvalidSignature: This is raised when
+            the provided signature does not match the expected signature.
+
+
+
+.. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
 .. _`Use cases for CMAC vs. HMAC?`: https://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac
 
 .. toctree::