Type annotations for nacl.encoding (#695)

* Type annotations for `nacl.encoding`

Pulled out from #692.

After we realised in #693 that we don't need `typing_extensions` to use
`SupportsBytes`, I didn't want to pull in `typing_extensions` again for
just one use of `Protocol`. (I have no other plans to use `Protocol` in
other annotations.)

My understanding: doing so means that we can't run `mypy` under Python
3.6 or 3.7 to fully typecheck the package. Maybe that's fine? I guess
the downside is that someone using `nacl` in a 3.6 or 3.7 project can't
fully benefit from these annotations. What're your thoughts here?

(As a compromise, I could do a `try-except` dance to use from
`typing_extensions.Protocol`, if it happens to be available.)

* Use an ABC instead of a protocol

* Format with black

* Docstrings to appease the `coverage` check

pyproject.toml

@@ -27,6 +27,7 @@ ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
 module = [
+    "nacl.encoding",
     "nacl.exceptions",
 ]
 disallow_any_unimported = true

src/nacl/encoding.py

@@ -11,73 +11,95 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-
 import base64
 import binascii
-from typing import SupportsBytes
+from abc import ABCMeta, abstractmethod
+from typing import SupportsBytes, Type
+
+
+# TODO: when the minimum supported version of Python is 3.8, we can import
+# Protocol from typing, and replace Encoder with a Protocol instead.
+class _Encoder(metaclass=ABCMeta):
+    @staticmethod
+    @abstractmethod
+    def encode(data: bytes) -> bytes:
+        """Transform raw data to encoded data."""
+
+    @staticmethod
+    @abstractmethod
+    def decode(data: bytes) -> bytes:
+        """Transform encoded data back to raw data.
+
+        Decoding after encoding should be a no-op, i.e. `decode(encode(x)) == x`.
+        """
+
+
+# Functions that use encoders are passed a subclass of _Encoder, not an instance
+# (because the methods are all static). Let's gloss over that detail by defining
+# an alias for Type[_Encoder].
+Encoder = Type[_Encoder]
 
 
-class RawEncoder:
+class RawEncoder(_Encoder):
     @staticmethod
-    def encode(data):
+    def encode(data: bytes) -> bytes:
         return data
 
     @staticmethod
-    def decode(data):
+    def decode(data: bytes) -> bytes:
         return data
 
 
-class HexEncoder:
+class HexEncoder(_Encoder):
     @staticmethod
-    def encode(data):
+    def encode(data: bytes) -> bytes:
         return binascii.hexlify(data)
 
     @staticmethod
-    def decode(data):
+    def decode(data: bytes) -> bytes:
         return binascii.unhexlify(data)
 
 
-class Base16Encoder:
+class Base16Encoder(_Encoder):
     @staticmethod
-    def encode(data):
+    def encode(data: bytes) -> bytes:
         return base64.b16encode(data)
 
     @staticmethod
-    def decode(data):
+    def decode(data: bytes) -> bytes:
         return base64.b16decode(data)
 
 
-class Base32Encoder:
+class Base32Encoder(_Encoder):
     @staticmethod
-    def encode(data):
+    def encode(data: bytes) -> bytes:
         return base64.b32encode(data)
 
     @staticmethod
-    def decode(data):
+    def decode(data: bytes) -> bytes:
         return base64.b32decode(data)
 
 
-class Base64Encoder:
+class Base64Encoder(_Encoder):
     @staticmethod
-    def encode(data):
+    def encode(data: bytes) -> bytes:
         return base64.b64encode(data)
 
     @staticmethod
-    def decode(data):
+    def decode(data: bytes) -> bytes:
         return base64.b64decode(data)
 
 
-class URLSafeBase64Encoder:
+class URLSafeBase64Encoder(_Encoder):
     @staticmethod
-    def encode(data):
+    def encode(data: bytes) -> bytes:
         return base64.urlsafe_b64encode(data)
 
     @staticmethod
-    def decode(data):
+    def decode(data: bytes) -> bytes:
         return base64.urlsafe_b64decode(data)
 
 
 class Encodable:
-    def encode(self: SupportsBytes, encoder=RawEncoder):
+    def encode(self: SupportsBytes, encoder: Encoder = RawEncoder) -> bytes:
         return encoder.encode(bytes(self))