Add type annotations

.github/workflows/main.yml

@@ -19,6 +19,10 @@ jobs:
         - os: windows-latest
           python: '3.12'
           toxenv: py
+        # typing
+        - os: ubuntu-latest
+          python: '3.8'
+          toxenv: typing
         # misc
         - os: ubuntu-latest
           python: '3.12'

pyproject.toml

@@ -0,0 +1,10 @@
+[tool.pyright]
+include = ["src/rfc3986"]
+ignore = ["tests"]
+pythonVersion = "3.8"
+typeCheckingMode = "strict"
+
+reportPrivateUsage = "none"
+reportImportCycles = "warning"
+reportPropertyTypeMismatch = "warning"
+reportUnnecessaryTypeIgnoreComment = "warning"

src/rfc3986/_mixin.py

@@ -1,18 +1,35 @@
 """Module containing the implementation of the URIMixin class."""
+import typing as t
 import warnings
 
 from . import exceptions as exc
 from . import misc
 from . import normalizers
+from . import uri
 from . import validators
+from ._typing_compat import Self as _Self
+
+
+class _AuthorityInfo(t.TypedDict):
+    """A typed dict for the authority info triple: userinfo, host, and port."""
+
+    userinfo: t.Optional[str]
+    host: t.Optional[str]
+    port: t.Optional[str]
 
 
 class URIMixin:
     """Mixin with all shared methods for URIs and IRIs."""
 
-    __hash__ = tuple.__hash__
+    if t.TYPE_CHECKING:
+        scheme: t.Optional[str]
+        authority: t.Optional[str]
+        path: t.Optional[str]
+        query: t.Optional[str]
+        fragment: t.Optional[str]
+        encoding: str
 
-    def authority_info(self):
+    def authority_info(self) -> _AuthorityInfo:
         """Return a dictionary with the ``userinfo``, ``host``, and ``port``.
 
         If the authority is not valid, it will raise a
@@ -53,11 +70,11 @@ def authority_info(self):
 
         return matches
 
-    def _match_subauthority(self):
+    def _match_subauthority(self) -> t.Optional[t.Match[str]]:
         return misc.SUBAUTHORITY_MATCHER.match(self.authority)
 
     @property
-    def _validator(self):
+    def _validator(self) -> validators.Validator:
         v = getattr(self, "_cached_validator", None)
         if v is not None:
             return v
@@ -67,7 +84,7 @@ def _validator(self):
         return self._cached_validator
 
     @property
-    def host(self):
+    def host(self) -> t.Optional[str]:
         """If present, a string representing the host."""
         try:
             authority = self.authority_info()
@@ -76,7 +93,7 @@ def host(self):
         return authority["host"]
 
     @property
-    def port(self):
+    def port(self) -> t.Optional[str]:
         """If present, the port extracted from the authority."""
         try:
             authority = self.authority_info()
@@ -85,15 +102,15 @@ def port(self):
         return authority["port"]
 
     @property
-    def userinfo(self):
+    def userinfo(self) -> t.Optional[str]:
         """If present, the userinfo extracted from the authority."""
         try:
             authority = self.authority_info()
         except exc.InvalidAuthority:
             return None
         return authority["userinfo"]
 
-    def is_absolute(self):
+    def is_absolute(self) -> bool:
         """Determine if this URI Reference is an absolute URI.
 
         See http://tools.ietf.org/html/rfc3986#section-4.3 for explanation.
@@ -103,7 +120,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
@@ -137,7 +154,7 @@ def is_valid(self, **kwargs):
         ]
         return all(v(r) for v, r in validators)
 
-    def authority_is_valid(self, require=False):
+    def authority_is_valid(self, require: bool = False) -> bool:
         """Determine if the authority component is valid.
 
         .. deprecated:: 1.1.0
@@ -167,7 +184,7 @@ def authority_is_valid(self, require=False):
             require=require,
         )
 
-    def scheme_is_valid(self, require=False):
+    def scheme_is_valid(self, require: bool = False) -> bool:
         """Determine if the scheme component is valid.
 
         .. deprecated:: 1.1.0
@@ -186,7 +203,7 @@ def scheme_is_valid(self, require=False):
         )
         return validators.scheme_is_valid(self.scheme, require)
 
-    def path_is_valid(self, require=False):
+    def path_is_valid(self, require: bool = False) -> bool:
         """Determine if the path component is valid.
 
         .. deprecated:: 1.1.0
@@ -205,7 +222,7 @@ def path_is_valid(self, require=False):
         )
         return validators.path_is_valid(self.path, require)
 
-    def query_is_valid(self, require=False):
+    def query_is_valid(self, require: bool = False) -> bool:
         """Determine if the query component is valid.
 
         .. deprecated:: 1.1.0
@@ -224,7 +241,7 @@ def query_is_valid(self, require=False):
         )
         return validators.query_is_valid(self.query, require)
 
-    def fragment_is_valid(self, require=False):
+    def fragment_is_valid(self, require: bool = False) -> bool:
         """Determine if the fragment component is valid.
 
         .. deprecated:: 1.1.0
@@ -243,7 +260,7 @@ def fragment_is_valid(self, require=False):
         )
         return validators.fragment_is_valid(self.fragment, require)
 
-    def normalized_equality(self, other_ref):
+    def normalized_equality(self, other_ref: "uri.URIReference") -> bool:
         """Compare this URIReference to another URIReference.
 
         :param URIReference other_ref: (required), The reference with which
@@ -253,7 +270,11 @@ def normalized_equality(self, other_ref):
         """
         return tuple(self.normalize()) == tuple(other_ref.normalize())
 
-    def resolve_with(self, base_uri, strict=False):
+    def resolve_with(
+        self,
+        base_uri: t.Union[str, "uri.URIReference"],
+        strict: bool = False,
+    ) -> _Self:
         """Use an absolute URI Reference to resolve this relative reference.
 
         Assuming this is a relative reference that you would like to resolve,
@@ -272,6 +293,9 @@ def resolve_with(self, base_uri, strict=False):
         if not isinstance(base_uri, URIMixin):
             base_uri = type(self).from_string(base_uri)
 
+        if t.TYPE_CHECKING:
+            base_uri = t.cast(uri.URIReference, base_uri)
+
         try:
             self._validator.validate(base_uri)
         except exc.ValidationError:
@@ -325,14 +349,14 @@ def resolve_with(self, base_uri, strict=False):
                     )
         return target
 
-    def unsplit(self):
+    def unsplit(self) -> str:
         """Create a URI string from the components.
 
         :returns: The URI Reference reconstituted as a string.
         :rtype: str
         """
         # See http://tools.ietf.org/html/rfc3986#section-5.3
-        result_list = []
+        result_list: list[str] = []
         if self.scheme:
             result_list.extend([self.scheme, ":"])
         if self.authority:
@@ -347,12 +371,12 @@ def unsplit(self):
 
     def copy_with(
         self,
-        scheme=misc.UseExisting,
-        authority=misc.UseExisting,
-        path=misc.UseExisting,
-        query=misc.UseExisting,
-        fragment=misc.UseExisting,
-    ):
+        scheme: t.Optional[str] = misc.UseExisting,
+        authority: t.Optional[str] = misc.UseExisting,
+        path: t.Optional[str] = misc.UseExisting,
+        query: t.Optional[str] = misc.UseExisting,
+        fragment: t.Optional[str] = misc.UseExisting,
+    ) -> _Self:
         """Create a copy of this reference with the new components.
 
         :param str scheme:
@@ -380,6 +404,6 @@ def copy_with(
         for key, value in list(attributes.items()):
             if value is misc.UseExisting:
                 del attributes[key]
-        uri = self._replace(**attributes)
+        uri: _Self = self._replace(**attributes)
         uri.encoding = self.encoding
         return uri

src/rfc3986/_typing_compat.py

@@ -0,0 +1,19 @@
+import sys
+import typing as t
+
+__all__ = ("Self",)
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+elif t.TYPE_CHECKING:
+    from typing_extensions import Self
+else:
+
+    class _PlaceholderMeta(type):
+        # This is meant to make it easier to debug the presence of placeholder
+        # classes.
+        def __repr__(self):
+            return f"placeholder for typing.{self.__name__}"
+
+    class Self(metaclass=_PlaceholderMeta):
+        """Placeholder for "typing.Self"."""

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, encoding="utf-8"):
+def uri_reference(
+    uri: t.Union[str, bytes],
+    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, encoding="utf-8"):
     return URIReference.from_string(uri, encoding)
 
 
-def iri_reference(iri, encoding="utf-8"):
+def iri_reference(
+    iri: t.Union[str, bytes],
+    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, encoding="utf-8"):
     return IRIReference.from_string(iri, encoding)
 
 
-def is_valid_uri(uri, encoding="utf-8", **kwargs):
+def is_valid_uri(
+    uri: t.Union[str, bytes],
+    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,7 @@ def is_valid_uri(uri, encoding="utf-8", **kwargs):
     return URIReference.from_string(uri, encoding).is_valid(**kwargs)
 
 
-def normalize_uri(uri, encoding="utf-8"):
+def normalize_uri(uri: t.Union[str, bytes], encoding: str = "utf-8") -> str:
     """Normalize the given URI.
 
     This is a convenience function. You could use either
@@ -91,7 +103,7 @@ def normalize_uri(uri, encoding="utf-8"):
     return normalized_reference.unsplit()
 
 
-def urlparse(uri, encoding="utf-8"):
+def urlparse(uri: t.Union[str, bytes], 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.