Add a few annotations.

- Add a typing configuration file with pyright set to strict.
- Add annotations for normalizers.py and validators.py.

Author: Sachaa-Thanasius

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/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
@@ -141,8 +144,13 @@ 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:
+    ...
+@t.overload
+def encode_component(uri_component: str, encoding: str) -> str:
+    ...
+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

src/rfc3986/validators.py

@@ -12,9 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """Module containing the validation logic for rfc3986."""
+import typing as t
+
 from . import exceptions
 from . import misc
 from . import normalizers
+from . import uri
 
 
 class Validator:
@@ -50,9 +53,9 @@ class Validator:
 
     def __init__(self):
         """Initialize our default validations."""
-        self.allowed_schemes = set()
-        self.allowed_hosts = set()
-        self.allowed_ports = set()
+        self.allowed_schemes: set[str] = set()
+        self.allowed_hosts: set[str] = set()
+        self.allowed_ports: set[str] = set()
         self.allow_password = True
         self.required_components = {
             "scheme": False,
@@ -65,7 +68,7 @@ def __init__(self):
         }
         self.validated_components = self.required_components.copy()
 
-    def allow_schemes(self, *schemes):
+    def allow_schemes(self, *schemes: str):
         """Require the scheme to be one of the provided schemes.
 
         .. versionadded:: 1.0
@@ -81,7 +84,7 @@ def allow_schemes(self, *schemes):
             self.allowed_schemes.add(normalizers.normalize_scheme(scheme))
         return self
 
-    def allow_hosts(self, *hosts):
+    def allow_hosts(self, *hosts: str):
         """Require the host to be one of the provided hosts.
 
         .. versionadded:: 1.0
@@ -97,7 +100,7 @@ def allow_hosts(self, *hosts):
             self.allowed_hosts.add(normalizers.normalize_host(host))
         return self
 
-    def allow_ports(self, *ports):
+    def allow_ports(self, *ports: str):
         """Require the port to be one of the provided ports.
 
         .. versionadded:: 1.0
@@ -141,7 +144,7 @@ def forbid_use_of_password(self):
         self.allow_password = False
         return self
 
-    def check_validity_of(self, *components):
+    def check_validity_of(self, *components: str):
         """Check the validity of the components provided.
 
         This can be specified repeatedly.
@@ -155,7 +158,7 @@ def check_validity_of(self, *components):
         :rtype:
             Validator
         """
-        components = [c.lower() for c in components]
+        components = tuple(c.lower() for c in components)
         for component in components:
             if component not in self.COMPONENT_NAMES:
                 raise ValueError(f'"{component}" is not a valid component')
@@ -164,7 +167,7 @@ def check_validity_of(self, *components):
         )
         return self
 
-    def require_presence_of(self, *components):
+    def require_presence_of(self, *components: str):
         """Require the components provided.
 
         This can be specified repeatedly.
@@ -178,7 +181,7 @@ def require_presence_of(self, *components):
         :rtype:
             Validator
         """
-        components = [c.lower() for c in components]
+        components = tuple(c.lower() for c in components)
         for component in components:
             if component not in self.COMPONENT_NAMES:
                 raise ValueError(f'"{component}" is not a valid component')
@@ -187,7 +190,7 @@ def require_presence_of(self, *components):
         )
         return self
 
-    def validate(self, uri):
+    def validate(self, uri: "uri.URIReference"):
         """Check a URI for conditions specified on this validator.
 
         .. versionadded:: 1.0
@@ -229,7 +232,7 @@ def validate(self, uri):
         ensure_one_of(self.allowed_ports, uri, "port")
 
 
-def check_password(uri):
+def check_password(uri: "uri.URIReference") -> None:
     """Assert that there is no password present in the uri."""
     userinfo = uri.userinfo
     if not userinfo:
@@ -240,7 +243,11 @@ def check_password(uri):
     raise exceptions.PasswordForbidden(uri)
 
 
-def ensure_one_of(allowed_values, uri, attribute):
+def ensure_one_of(
+    allowed_values: t.Container[object],
+    uri: "uri.URIReference",
+    attribute: str,
+) -> None:
     """Assert that the uri's attribute is one of the allowed values."""
     value = getattr(uri, attribute)
     if value is not None and allowed_values and value not in allowed_values:
@@ -251,7 +258,10 @@ def ensure_one_of(allowed_values, uri, attribute):
         )
 
 
-def ensure_required_components_exist(uri, required_components):
+def ensure_required_components_exist(
+    uri: "uri.URIReference",
+    required_components: t.Iterable[str],
+):
     """Assert that all required components are present in the URI."""
     missing_components = sorted(
         component
@@ -262,7 +272,7 @@ def ensure_required_components_exist(uri, required_components):
         raise exceptions.MissingComponentError(uri, *missing_components)
 
 
-def is_valid(value, matcher, require):
+def is_valid(value: t.Optional[str], matcher: t.Pattern[str], require: bool) -> bool:
     """Determine if a value is valid based on the provided matcher.
 
     :param str value:
@@ -273,13 +283,13 @@ def is_valid(value, matcher, require):
         Whether or not the value is required.
     """
     if require:
-        return value is not None and matcher.match(value)
+        return value is not None and bool(matcher.match(value))
 
     # require is False and value is not None
-    return value is None or matcher.match(value)
+    return value is None or bool(matcher.match(value))
 
 
-def authority_is_valid(authority, host=None, require=False):
+def authority_is_valid(authority: str, host: t.Optional[str] = None, require: bool = False) -> bool:
     """Determine if the authority string is valid.
 
     :param str authority:
@@ -299,7 +309,7 @@ def authority_is_valid(authority, host=None, require=False):
     return validated
 
 
-def host_is_valid(host, require=False):
+def host_is_valid(host: t.Optional[str], require: bool = False) -> bool:
     """Determine if the host string is valid.
 
     :param str host:
@@ -319,7 +329,7 @@ def host_is_valid(host, require=False):
     return validated
 
 
-def scheme_is_valid(scheme, require=False):
+def scheme_is_valid(scheme: t.Optional[str], require: bool = False) -> bool:
     """Determine if the scheme is valid.
 
     :param str scheme:
@@ -334,7 +344,7 @@ def scheme_is_valid(scheme, require=False):
     return is_valid(scheme, misc.SCHEME_MATCHER, require)
 
 
-def path_is_valid(path, require=False):
+def path_is_valid(path: t.Optional[str], require: bool = False) -> bool:
     """Determine if the path component is valid.
 
     :param str path:
@@ -349,7 +359,7 @@ def path_is_valid(path, require=False):
     return is_valid(path, misc.PATH_MATCHER, require)
 
 
-def query_is_valid(query, require=False):
+def query_is_valid(query: t.Optional[str], require: bool = False) -> bool:
     """Determine if the query component is valid.
 
     :param str query:
@@ -364,7 +374,7 @@ def query_is_valid(query, require=False):
     return is_valid(query, misc.QUERY_MATCHER, require)
 
 
-def fragment_is_valid(fragment, require=False):
+def fragment_is_valid(fragment: t.Optional[str], require: bool = False) -> bool:
     """Determine if the fragment component is valid.
 
     :param str fragment:
@@ -379,7 +389,7 @@ def fragment_is_valid(fragment, require=False):
     return is_valid(fragment, misc.FRAGMENT_MATCHER, require)
 
 
-def valid_ipv4_host_address(host):
+def valid_ipv4_host_address(host: str) -> bool:
     """Determine if the given host is a valid IPv4 address."""
     # If the host exists, and it might be IPv4, check each byte in the
     # address.
@@ -396,7 +406,7 @@ def valid_ipv4_host_address(host):
 _SUBAUTHORITY_VALIDATORS = {"userinfo", "host", "port"}
 
 
-def subauthority_component_is_valid(uri, component):
+def subauthority_component_is_valid(uri: "uri.URIReference", component: str) -> bool:
     """Determine if the userinfo, host, and port are valid."""
     try:
         subauthority_dict = uri.authority_info()
@@ -420,9 +430,9 @@ def subauthority_component_is_valid(uri, component):
     return 0 <= port <= 65535
 
 
-def ensure_components_are_valid(uri, validated_components):
+def ensure_components_are_valid(uri: "uri.URIReference", validated_components: t.List[str]) -> None:
     """Assert that all components are valid in the URI."""
-    invalid_components = set()
+    invalid_components: set[str] = set()
     for component in validated_components:
         if component in _SUBAUTHORITY_VALIDATORS:
             if not subauthority_component_is_valid(uri, component):