Add parameter annotations to builder.py.

- TODO: Consider changing the insides of the URIBuilder.add_* methods to use `type(self)(...)` instead of `URIBuilder(...)`. That way, subclassing is supported. Would result in the return annotations being Self as well.
- Added trailing commas to function parameters in normalizers.py and validators.py for functions with multi-line signatures.

Author: Sachaa-Thanasius

src/rfc3986/builder.py

@@ -12,6 +12,7 @@
 # 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
 
@@ -33,13 +34,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 +77,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 +96,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 +120,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 +153,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 +173,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 +212,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 +239,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
@@ -314,7 +315,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 +335,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 +355,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/normalizers.py

@@ -156,7 +156,8 @@ def encode_component(uri_component: str, encoding: str) -> str:
 
 
 def encode_component(
-    uri_component: t.Optional[str], encoding: str
+    uri_component: t.Optional[str],
+    encoding: str,
 ) -> t.Optional[str]:
     """Encode the specific component in the provided encoding."""
     if uri_component is None:

src/rfc3986/validators.py

@@ -273,7 +273,9 @@ def ensure_required_components_exist(
 
 
 def is_valid(
-    value: t.Optional[str], matcher: t.Pattern[str], require: bool
+    value: t.Optional[str],
+    matcher: t.Pattern[str],
+    require: bool,
 ) -> bool:
     """Determine if a value is valid based on the provided matcher.
 
@@ -292,7 +294,9 @@ def is_valid(
 
 
 def authority_is_valid(
-    authority: str, host: t.Optional[str] = None, require: bool = False
+    authority: str,
+    host: t.Optional[str] = None,
+    require: bool = False,
 ) -> bool:
     """Determine if the authority string is valid.
 
@@ -379,7 +383,8 @@ def query_is_valid(query: t.Optional[str], require: bool = False) -> bool:
 
 
 def fragment_is_valid(
-    fragment: t.Optional[str], require: bool = False
+    fragment: t.Optional[str],
+    require: bool = False,
 ) -> bool:
     """Determine if the fragment component is valid.
 
@@ -413,7 +418,8 @@ def valid_ipv4_host_address(host: str) -> bool:
 
 
 def subauthority_component_is_valid(
-    uri: "uri.URIReference", component: str
+    uri: "uri.URIReference",
+    component: str,
 ) -> bool:
     """Determine if the userinfo, host, and port are valid."""
     try:
@@ -429,7 +435,7 @@ def subauthority_component_is_valid(
         return True
 
     try:
-        port = int(subauthority_dict["port"])
+        port = int(subauthority_dict["port"])  # pyright: ignore[reportArgumentType] # Guarded by "except TypeError".
     except TypeError:
         # If the port wasn't provided it'll be None and int(None) raises a
         # TypeError
@@ -439,7 +445,8 @@ def subauthority_component_is_valid(
 
 
 def ensure_components_are_valid(
-    uri: "uri.URIReference", validated_components: t.List[str]
+    uri: "uri.URIReference",
+    validated_components: t.List[str],
 ) -> None:
     """Assert that all components are valid in the URI."""
     invalid_components: set[str] = set()