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/api.py

@@ -22,7 +22,7 @@
 from .uri import URIReference
 
 
-def uri_reference(uri, encoding="utf-8"):
+def uri_reference(uri: str, 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 +36,7 @@ def uri_reference(uri, encoding="utf-8"):
     return URIReference.from_string(uri, encoding)
 
 
-def iri_reference(iri, encoding="utf-8"):
+def iri_reference(iri: str, 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 +50,7 @@ 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: str, 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 +75,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: str, encoding: str = "utf-8") -> str:
     """Normalize the given URI.
 
     This is a convenience function. You could use either
@@ -91,7 +91,7 @@ def normalize_uri(uri, encoding="utf-8"):
     return normalized_reference.unsplit()
 
 
-def urlparse(uri, encoding="utf-8"):
+def urlparse(uri: str, 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/builder.py

@@ -12,13 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Module containing the logic for the URIBuilder object."""
+import typing as t
 from urllib.parse import parse_qsl
 from urllib.parse import urlencode
 
 from . import normalizers
 from . import uri
 from . import uri_reference
 
+# Copied from urllib.parse in typeshed.
+_QueryType = t.Union[
+    t.Mapping[t.Any, t.Any],
+    t.Mapping[t.Any, t.Sequence[t.Any]],
+    t.List[t.Tuple[t.Any, t.Any]],
+    t.List[t.Tuple[t.Any, t.Sequence[t.Any]]],
+]
+
 
 class URIBuilder:
     """Object to aid in building up a URI Reference from parts.
@@ -33,13 +42,13 @@ class URIBuilder:
 
     def __init__(
         self,
-        scheme=None,
-        userinfo=None,
-        host=None,
-        port=None,
-        path=None,
-        query=None,
-        fragment=None,
+        scheme: t.Optional[str] = None,
+        userinfo: t.Optional[str] = None,
+        host: t.Optional[str] = None,
+        port: t.Optional[str] = None,
+        path: t.Optional[str] = None,
+        query: t.Optional[str] = None,
+        fragment: t.Optional[str] = None,
     ):
         """Initialize our URI builder.
 
@@ -76,7 +85,7 @@ def __repr__(self):
         return formatstr.format(b=self)
 
     @classmethod
-    def from_uri(cls, reference):
+    def from_uri(cls, reference: t.Union["uri.URIReference", str]):
         """Initialize the URI builder from another URI.
 
         Takes the given URI reference and creates a new URI builder instance
@@ -95,7 +104,7 @@ def from_uri(cls, reference):
             fragment=reference.fragment,
         )
 
-    def add_scheme(self, scheme):
+    def add_scheme(self, scheme: str):
         """Add a scheme to our builder object.
 
         After normalizing, this will generate a new URIBuilder instance with
@@ -119,7 +128,7 @@ def add_scheme(self, scheme):
             fragment=self.fragment,
         )
 
-    def add_credentials(self, username, password):
+    def add_credentials(self, username: str, password: t.Optional[str]):
         """Add credentials as the userinfo portion of the URI.
 
         .. code-block:: python
@@ -152,7 +161,7 @@ def add_credentials(self, username, password):
             fragment=self.fragment,
         )
 
-    def add_host(self, host):
+    def add_host(self, host: str):
         """Add hostname to the URI.
 
         .. code-block:: python
@@ -172,7 +181,7 @@ def add_host(self, host):
             fragment=self.fragment,
         )
 
-    def add_port(self, port):
+    def add_port(self, port: t.Union[str, int]):
         """Add port to the URI.
 
         .. code-block:: python
@@ -211,7 +220,7 @@ def add_port(self, port):
             fragment=self.fragment,
         )
 
-    def add_path(self, path):
+    def add_path(self, path: str):
         """Add a path to the URI.
 
         .. code-block:: python
@@ -238,7 +247,7 @@ def add_path(self, path):
             fragment=self.fragment,
         )
 
-    def extend_path(self, path):
+    def extend_path(self, path: str):
         """Extend the existing path value with the provided value.
 
         .. versionadded:: 1.5.0
@@ -267,7 +276,7 @@ def extend_path(self, path):
 
         return self.add_path(path)
 
-    def add_query_from(self, query_items):
+    def add_query_from(self, query_items: _QueryType):
         """Generate and add a query a dictionary or list of tuples.
 
         .. code-block:: python
@@ -293,7 +302,7 @@ def add_query_from(self, query_items):
             fragment=self.fragment,
         )
 
-    def extend_query_with(self, query_items):
+    def extend_query_with(self, query_items: _QueryType):
         """Extend the existing query string with the new query items.
 
         .. versionadded:: 1.5.0
@@ -314,7 +323,7 @@ def extend_query_with(self, query_items):
 
         return self.add_query_from(original_query_items + query_items)
 
-    def add_query(self, query):
+    def add_query(self, query: str):
         """Add a pre-formated query string to the URI.
 
         .. code-block:: python
@@ -334,7 +343,7 @@ def add_query(self, query):
             fragment=self.fragment,
         )
 
-    def add_fragment(self, fragment):
+    def add_fragment(self, fragment: str):
         """Add a fragment to the URI.
 
         .. code-block:: python
@@ -354,7 +363,7 @@ def add_fragment(self, fragment):
             fragment=normalizers.normalize_fragment(fragment),
         )
 
-    def finalize(self):
+    def finalize(self) -> "uri.URIReference":
         """Create a URIReference from our builder.
 
         .. code-block:: python

src/rfc3986/compat.py

@@ -12,21 +12,54 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Compatibility module for Python 2 and 3 support."""
+import typing as t
 
 __all__ = (
     "to_bytes",
     "to_str",
 )
 
 
-def to_str(b, encoding="utf-8"):
+@t.overload
+def to_str(  # noqa: D103
+    b: t.Union[str, bytes],
+    encoding: str = "utf-8",
+) -> str:
+    ...
+
+
+@t.overload
+def to_str(b: None, encoding: str = "utf-8") -> None:  # noqa: D103
+    ...
+
+
+def to_str(
+    b: t.Optional[t.Union[str, bytes]],
+    encoding: str = "utf-8",
+) -> t.Optional[str]:
     """Ensure that b is text in the specified encoding."""
     if hasattr(b, "decode") and not isinstance(b, str):
         b = b.decode(encoding)
     return b
 
 
-def to_bytes(s, encoding="utf-8"):
+@t.overload
+def to_bytes(  # noqa: D103
+    s: t.Union[str, bytes],
+    encoding: str = "utf-8",
+) -> bytes:
+    ...
+
+
+@t.overload
+def to_bytes(s: None, encoding: str = "utf-8") -> None:  # noqa: D103
+    ...
+
+
+def to_bytes(
+    s: t.Optional[t.Union[str, bytes]],
+    encoding: str = "utf-8",
+) -> t.Optional[bytes]:
     """Ensure that s is converted to bytes from the encoding."""
     if hasattr(s, "encode") and not isinstance(s, bytes):
         s = s.encode(encoding)

src/rfc3986/normalizers.py

@@ -13,18 +13,21 @@
 # limitations under the License.
 """Module with functions to normalize components."""
 import re
+import typing as t
 from urllib.parse import quote as urlquote
 
 from . import compat
 from . import misc
 
 
-def normalize_scheme(scheme):
+def normalize_scheme(scheme: str) -> str:
     """Normalize the scheme component."""
     return scheme.lower()
 
 
-def normalize_authority(authority):
+def normalize_authority(
+    authority: t.Tuple[t.Optional[str], t.Optional[str], t.Optional[str]],
+) -> str:
     """Normalize an authority tuple to a string."""
     userinfo, host, port = authority
     result = ""
@@ -37,17 +40,17 @@ def normalize_authority(authority):
     return result
 
 
-def normalize_username(username):
+def normalize_username(username: str) -> str:
     """Normalize a username to make it safe to include in userinfo."""
     return urlquote(username)
 
 
-def normalize_password(password):
+def normalize_password(password: str) -> str:
     """Normalize a password to make safe for userinfo."""
     return urlquote(password)
 
 
-def normalize_host(host):
+def normalize_host(host: str) -> str:
     """Normalize a host string."""
     if misc.IPv6_MATCHER.match(host):
         percent = host.find("%")
@@ -70,7 +73,7 @@ def normalize_host(host):
     return host.lower()
 
 
-def normalize_path(path):
+def normalize_path(path: str) -> str:
     """Normalize the path string."""
     if not path:
         return path
@@ -79,14 +82,14 @@ def normalize_path(path):
     return remove_dot_segments(path)
 
 
-def normalize_query(query):
+def normalize_query(query: str) -> str:
     """Normalize the query string."""
     if not query:
         return query
     return normalize_percent_characters(query)
 
 
-def normalize_fragment(fragment):
+def normalize_fragment(fragment: str) -> str:
     """Normalize the fragment string."""
     if not fragment:
         return fragment
@@ -96,7 +99,7 @@ def normalize_fragment(fragment):
 PERCENT_MATCHER = re.compile("%[A-Fa-f0-9]{2}")
 
 
-def normalize_percent_characters(s):
+def normalize_percent_characters(s: str) -> str:
     """All percent characters should be upper-cased.
 
     For example, ``"%3afoo%DF%ab"`` should be turned into ``"%3Afoo%DF%AB"``.
@@ -108,14 +111,14 @@ def normalize_percent_characters(s):
     return s
 
 
-def remove_dot_segments(s):
+def remove_dot_segments(s: str) -> str:
     """Remove dot segments from the string.
 
     See also Section 5.2.4 of :rfc:`3986`.
     """
     # See http://tools.ietf.org/html/rfc3986#section-5.2.4 for pseudo-code
     segments = s.split("/")  # Turn the path into a list of segments
-    output = []  # Initialize the variable to use to store output
+    output: list[str] = []  # Initialize the variable to use to store output
 
     for segment in segments:
         # '.' is the current directory, so ignore it, it is superfluous
@@ -142,7 +145,20 @@ def remove_dot_segments(s):
     return "/".join(output)
 
 
-def encode_component(uri_component, encoding):
+@t.overload
+def encode_component(uri_component: None, encoding: str) -> None:  # noqa: D103
+    ...
+
+
+@t.overload
+def encode_component(uri_component: str, encoding: str) -> str:  # noqa: D103
+    ...
+
+
+def encode_component(
+    uri_component: t.Optional[str],
+    encoding: str,
+) -> t.Optional[str]:
     """Encode the specific component in the provided encoding."""
     if uri_component is None:
         return uri_component