self review

Author: Archmonger

docs/examples/python/use-search-params.py

@@ -5,8 +5,8 @@
 
 @component
 def search():
-    query = use_search_params()
-    return html._(html.h1(f"Search Results for {query['q'][0]} 🔍"), html.p("Nothing (yet)."))
+    search_params = use_search_params()
+    return html._(html.h1(f"Search Results for {search_params['query'][0]} 🔍"), html.p("Nothing (yet)."))
 
 
 @component
@@ -16,7 +16,7 @@ def root():
             "/",
             html.div(
                 html.h1("Home Page 🏠"),
-                link("Search", to="/search?q=reactpy"),
+                link("Search", to="/search?query=reactpy"),
             ),
         ),
         route("/search", search()),

src/reactpy_router/converters.py

@@ -34,4 +34,4 @@
         "func": str,
     },
 }
-"""The conversion types supported by the default Resolver. You can add more types if needed."""
+"""The conversion types supported by the default Resolver."""

src/reactpy_router/hooks.py

@@ -53,14 +53,14 @@ def use_search_params(
     separator: str = "&",
 ) -> dict[str, list[str]]:
     """
-    The `use_search_params` hook is used to read and modify the query string in the URL \
-    for the current location. Like React's own `use_state` hook, `use_search_params` returns \
-    an array of two values: the current location's search parameters and a function that may \
-    be used to update them.
+    The `use_search_params` hook is used to read the query string in the URL \
+    for the current location.
 
     See `urllib.parse.parse_qs` for info on this hook's parameters."""
 
-    # FIXME: This needs to return a tuple of the search params and a function to update them
+    # TODO: In order to match `react-router`, this will need to return a tuple of the search params \
+    # and a function to update them. This is currently not possible without reactpy core having a \
+    # communication layer.
     return parse_qs(
         use_location().search[1:],
         keep_blank_values=keep_blank_values,

src/reactpy_router/resolvers.py

@@ -10,9 +10,9 @@
 
 
 class StarletteResolver:
-    """URL resolver that matches routes that match the starlette URL routing syntax.
+    """URL resolver that matches routes using starlette's URL routing syntax.
 
-    However, we add a few additional parameter types on top of Starlette's syntax."""
+    However, this resolver adds a few additional parameter types on top of Starlette's syntax."""
 
     def __init__(
         self,
@@ -34,10 +34,14 @@ def parse_path(self, path: str) -> re.Pattern[str]:
 
         # Iterate through matches of the parameter pattern
         for match in self.param_regex.finditer(path):
-            # Extract parameter name and type
+            # Extract parameter name
             name = match.group("name")
             if name[0].isnumeric():
+                # Regex group names can't begin with a number, so we must prefix them with
+                # "_numeric_". This prefix is removed later within this function.
                 name = f"_numeric_{name}"
+
+            # Extract the parameter type
             param_type = (match.group("type") or "str").strip(":")
 
             # Check if a converter exists for the type

src/reactpy_router/routers.py

@@ -4,7 +4,7 @@
 
 from dataclasses import replace
 from logging import getLogger
-from typing import Any, Iterator, Literal, Sequence, TypeVar
+from typing import Any, Iterator, Literal, Sequence
 
 from reactpy import (
     component,
@@ -20,33 +20,32 @@
 from reactpy_router.components import History
 from reactpy_router.hooks import _route_state_context, _RouteState
 from reactpy_router.resolvers import StarletteResolver
-from reactpy_router.types import Route, RouteCompiler, Router, RouteResolver
+from reactpy_router.types import CompiledRoute, Resolver, Router, RouteType
 
 __all__ = ["browser_router", "create_router"]
 _logger = getLogger(__name__)
-R = TypeVar("R", bound=Route)
 
 
-def create_router(compiler: RouteCompiler[R]) -> Router[R]:
-    """A decorator that turns a route compiler into a router"""
+def create_router(resolver: Resolver[RouteType]) -> Router[RouteType]:
+    """A decorator that turns a resolver into a router"""
 
-    def wrapper(*routes: R) -> ComponentType:
-        return router(*routes, compiler=compiler)
+    def wrapper(*routes: RouteType) -> ComponentType:
+        return router(*routes, resolver=resolver)
 
     return wrapper
 
 
 browser_router = create_router(StarletteResolver)
 """This is the recommended router for all ReactPy Router web projects.
-It uses the DOM History API to update the URL and manage the history stack."""
+It uses the JavaScript DOM History API to manage the history stack."""
 
 
 @component
 def router(
-    *routes: R,
-    compiler: RouteCompiler[R],
+    *routes: RouteType,
+    resolver: Resolver[RouteType],
 ) -> VdomDict | None:
-    """A component that renders matching route(s) using the given compiler function.
+    """A component that renders matching route(s) using the given resolver.
 
     This typically should never be used by a user. Instead, use `create_router` if creating
     a custom routing engine."""
@@ -55,8 +54,8 @@ def router(
     location, set_location = use_state(old_conn.location)
 
     resolvers = use_memo(
-        lambda: tuple(map(compiler, _iter_routes(routes))),
-        dependencies=(compiler, hash(routes)),
+        lambda: tuple(map(resolver, _iter_routes(routes))),
+        dependencies=(resolver, hash(routes)),
     )
 
     match = use_memo(lambda: _match_route(resolvers, location, select="first"))
@@ -80,15 +79,15 @@ def router(
     return None
 
 
-def _iter_routes(routes: Sequence[R]) -> Iterator[R]:
+def _iter_routes(routes: Sequence[RouteType]) -> Iterator[RouteType]:
     for parent in routes:
         for child in _iter_routes(parent.routes):
             yield replace(child, path=parent.path + child.path)  # type: ignore[misc]
         yield parent
 
 
 def _match_route(
-    compiled_routes: Sequence[RouteResolver],
+    compiled_routes: Sequence[CompiledRoute],
     location: Location,
     select: Literal["first", "all"],
 ) -> list[tuple[Any, dict[str, Any]]]:
@@ -100,8 +99,9 @@ def _match_route(
             if select == "first":
                 return [match]
 
-            # This is no longer used by `reactpy-router`, since `react-router>=6.0.0` no longer supports
-            # multiple matches. However, it's kept here to support future changes.
+            # Matching multiple routes is disabled since `react-router` no longer supports multiple
+            # matches via the `Route` component. However, it's kept here to support future changes
+            # or third-party routers.
             matches.append(match)  # pragma: no cover
 
     if not matches:

src/reactpy_router/types.py

@@ -32,22 +32,23 @@ def __hash__(self) -> int:
         return hash((self.path, key, self.routes))
 
 
-R_contra = TypeVar("R_contra", bound=Route, contravariant=True)
+RouteType = TypeVar("RouteType", bound=Route)
+RouteType_contra = TypeVar("RouteType_contra", bound=Route, contravariant=True)
 
 
-class Router(Protocol[R_contra]):
+class Router(Protocol[RouteType_contra]):
     """Return a component that renders the first matching route."""
 
-    def __call__(self, *routes: R_contra) -> ComponentType: ...
+    def __call__(self, *routes: RouteType_contra) -> ComponentType: ...
 
 
-class RouteCompiler(Protocol[R_contra]):
-    """Compile a route into a resolver that can be matched against a path."""
+class Resolver(Protocol[RouteType_contra]):
+    """Compile a route into a resolver that can be matched against a given path."""
 
-    def __call__(self, route: R_contra) -> RouteResolver: ...
+    def __call__(self, route: RouteType_contra) -> CompiledRoute: ...
 
 
-class RouteResolver(Protocol):
+class CompiledRoute(Protocol):
     """A compiled route that can be matched against a path."""
 
     @property