Fix compat.py and api.py parameter annotations to accept bytearray as well.

- This provides parity with the way urllib.parse is typed and the runtime implementation, since bytearray isn't a str and also has a `decode(encoding)` method.
- Adjusted compat functions to also accept bytearray for the same reasons.
- Adjusted the parameter types of the other functions called in api.py that are part of the `(U|I)RIReference` interfaces to make sure api.py fully type-checks.
- TODO: Consider making a typealias for `t.Union[str, bytes, bytearray]` and using that everywhere to avoid verbosity?
- TODO: For the **kwargs functions in api.py and `URLMixin.is_valid()`, consider enumerating the possible keyword-only parameters?

Author: Sachaa-Thanasius

src/rfc3986/_mixin.py

@@ -103,7 +103,7 @@ def is_absolute(self):
         """
         return bool(misc.ABSOLUTE_URI_MATCHER.match(self.unsplit()))
 
-    def is_valid(self, **kwargs):
+    def is_valid(self, **kwargs: bool) -> bool:
         """Determine if the URI is valid.
 
         .. deprecated:: 1.1.0

src/rfc3986/api.py

@@ -17,12 +17,17 @@
 This module defines functions and provides access to the public attributes
 and classes of rfc3986.
 """
+import typing as t
+
 from .iri import IRIReference
 from .parseresult import ParseResult
 from .uri import URIReference
 
 
-def uri_reference(uri: str, encoding: str = "utf-8") -> URIReference:
+def uri_reference(
+    uri: t.Union[str, bytes, bytearray],
+    encoding: str = "utf-8",
+) -> URIReference:
     """Parse a URI string into a URIReference.
 
     This is a convenience function. You could achieve the same end by using
@@ -36,7 +41,10 @@ def uri_reference(uri: str, encoding: str = "utf-8") -> URIReference:
     return URIReference.from_string(uri, encoding)
 
 
-def iri_reference(iri: str, encoding: str = "utf-8") -> IRIReference:
+def iri_reference(
+    iri: t.Union[str, bytes, bytearray],
+    encoding: str = "utf-8",
+) -> IRIReference:
     """Parse a IRI string into an IRIReference.
 
     This is a convenience function. You could achieve the same end by using
@@ -50,7 +58,11 @@ def iri_reference(iri: str, encoding: str = "utf-8") -> IRIReference:
     return IRIReference.from_string(iri, encoding)
 
 
-def is_valid_uri(uri: str, encoding: str = "utf-8", **kwargs: bool) -> bool:
+def is_valid_uri(
+    uri: t.Union[str, bytes, bytearray],
+    encoding: str = "utf-8",
+    **kwargs: bool,
+) -> bool:
     """Determine if the URI given is valid.
 
     This is a convenience function. You could use either
@@ -75,7 +87,10 @@ def is_valid_uri(uri: str, encoding: str = "utf-8", **kwargs: bool) -> bool:
     return URIReference.from_string(uri, encoding).is_valid(**kwargs)
 
 
-def normalize_uri(uri: str, encoding: str = "utf-8") -> str:
+def normalize_uri(
+    uri: t.Union[str, bytes, bytearray],
+    encoding: str = "utf-8",
+) -> str:
     """Normalize the given URI.
 
     This is a convenience function. You could use either
@@ -91,7 +106,10 @@ def normalize_uri(uri: str, encoding: str = "utf-8") -> str:
     return normalized_reference.unsplit()
 
 
-def urlparse(uri: str, encoding: str = "utf-8") -> ParseResult:
+def urlparse(
+    uri: t.Union[str, bytes, bytearray],
+    encoding: str = "utf-8",
+) -> ParseResult:
     """Parse a given URI and return a ParseResult.
 
     This is a partial replacement of the standard library's urlparse function.

src/rfc3986/compat.py

@@ -22,7 +22,7 @@
 
 @t.overload
 def to_str(  # noqa: D103
-    b: t.Union[str, bytes],
+    b: t.Union[str, bytes, bytearray],
     encoding: str = "utf-8",
 ) -> str:
     ...
@@ -34,7 +34,7 @@ def to_str(b: None, encoding: str = "utf-8") -> None:  # noqa: D103
 
 
 def to_str(
-    b: t.Optional[t.Union[str, bytes]],
+    b: t.Optional[t.Union[str, bytes, bytearray]],
     encoding: str = "utf-8",
 ) -> t.Optional[str]:
     """Ensure that b is text in the specified encoding."""
@@ -45,7 +45,7 @@ def to_str(
 
 @t.overload
 def to_bytes(  # noqa: D103
-    s: t.Union[str, bytes],
+    s: t.Union[str, bytes, bytearray],
     encoding: str = "utf-8",
 ) -> bytes:
     ...
@@ -57,7 +57,7 @@ def to_bytes(s: None, encoding: str = "utf-8") -> None:  # noqa: D103
 
 
 def to_bytes(
-    s: t.Optional[t.Union[str, bytes]],
+    s: t.Optional[t.Union[str, bytes, bytearray]],
     encoding: str = "utf-8",
 ) -> t.Optional[bytes]:
     """Ensure that s is converted to bytes from the encoding."""

src/rfc3986/iri.py

@@ -13,6 +13,7 @@
 # implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+import typing as t
 from collections import namedtuple
 
 from . import compat
@@ -80,7 +81,11 @@ def _match_subauthority(self):
         return misc.ISUBAUTHORITY_MATCHER.match(self.authority)
 
     @classmethod
-    def from_string(cls, iri_string, encoding="utf-8"):
+    def from_string(
+        cls,
+        iri_string: t.Union[str, bytes, bytearray],
+        encoding: str = "utf-8",
+    ):
         """Parse a IRI reference from the given unicode IRI string.
 
         :param str iri_string: Unicode IRI to be parsed into a reference.

src/rfc3986/parseresult.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Module containing the urlparse compatibility logic."""
+import typing as t
 from collections import namedtuple
 
 from . import compat
@@ -155,7 +156,11 @@ def from_parts(
 
     @classmethod
     def from_string(
-        cls, uri_string, encoding="utf-8", strict=True, lazy_normalize=True
+        cls,
+        uri_string: t.Union[str, bytes, bytearray],
+        encoding: str = "utf-8",
+        strict: bool = True,
+        lazy_normalize: bool = True,
     ):
         """Parse a URI from the given unicode URI string.
 

src/rfc3986/uri.py

@@ -13,6 +13,7 @@
 # implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+import typing as t
 from collections import namedtuple
 
 from . import compat
@@ -140,7 +141,11 @@ def normalize(self):
         )
 
     @classmethod
-    def from_string(cls, uri_string, encoding="utf-8"):
+    def from_string(
+        cls,
+        uri_string: t.Union[str, bytes, bytearray],
+        encoding: str = "utf-8",
+    ):
         """Parse a URI reference from the given unicode URI string.
 
         :param str uri_string: Unicode URI to be parsed into a reference.