From a8832b3d51b7d74287f714ce068787f277a1facd Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Fri, 6 Sep 2024 10:16:16 -0500
Subject: [PATCH] Make ``SimpleQuery``, ``QueryVariable``, and ``Query`` types
 available

closes #1050
---
 tests/test_url_query.py | 24 ++++++++++++------------
 yarl/__init__.py        | 20 ++++++++++++++++++--
 yarl/_url.py            | 26 +++++++++++++-------------
 3 files changed, 43 insertions(+), 27 deletions(-)

diff --git a/tests/test_url_query.py b/tests/test_url_query.py
index 0a6fe3fd..8560a4d8 100644
--- a/tests/test_url_query.py
+++ b/tests/test_url_query.py
@@ -134,10 +134,10 @@ def test_query_separators_from_parsing(
     URLS_WITH_RESERVED_CHARS_IN_QUERY_VALUES_W_XFAIL,
 )
 def test_query_separators_from_update_query(
-    original_url,
-    expected_query_len,
-    expected_value_a,
-):
+    original_url: URL,
+    expected_query_len: int,
+    expected_value_a: str,
+) -> None:
     new_url = original_url.update_query({"c": expected_value_a})
     assert new_url.query["a"] == expected_value_a
     assert new_url.query["c"] == expected_value_a
@@ -148,10 +148,10 @@ def test_query_separators_from_update_query(
     URLS_WITH_RESERVED_CHARS_IN_QUERY_VALUES,
 )
 def test_query_separators_from_with_query(
-    original_url,
-    expected_query_len,
-    expected_value_a,
-):
+    original_url: URL,
+    expected_query_len: int,
+    expected_value_a: int,
+) -> None:
     new_url = original_url.with_query({"c": expected_value_a})
     assert new_url.query["c"] == expected_value_a
 
@@ -161,10 +161,10 @@ def test_query_separators_from_with_query(
     URLS_WITH_RESERVED_CHARS_IN_QUERY_VALUES,
 )
 def test_query_from_empty_update_query(
-    original_url,
-    expected_query_len,
-    expected_value_a,
-):
+    original_url: URL,
+    expected_query_len: int,
+    expected_value_a: str,
+) -> None:
     new_url = original_url.update_query({})
 
     assert new_url.query["a"] == original_url.query["a"]
diff --git a/yarl/__init__.py b/yarl/__init__.py
index ba13ab77..59816acc 100644
--- a/yarl/__init__.py
+++ b/yarl/__init__.py
@@ -1,5 +1,21 @@
-from ._url import URL, cache_clear, cache_configure, cache_info
+from ._url import (
+    URL,
+    Query,
+    QueryVariable,
+    SimpleQuery,
+    cache_clear,
+    cache_configure,
+    cache_info,
+)
 
 __version__ = "1.9.12.dev0"
 
-__all__ = ("URL", "cache_clear", "cache_configure", "cache_info")
+__all__ = (
+    "URL",
+    "SimpleQuery",
+    "QueryVariable",
+    "Query",
+    "cache_clear",
+    "cache_configure",
+    "cache_info",
+)
diff --git a/yarl/_url.py b/yarl/_url.py
index 8faf7198..3f4fc64e 100644
--- a/yarl/_url.py
+++ b/yarl/_url.py
@@ -41,10 +41,10 @@
 
 sentinel = object()
 
-_SimpleQuery = Union[str, int, float]
-_QueryVariable = Union[_SimpleQuery, "Sequence[_SimpleQuery]"]
-_Query = Union[
-    None, str, "Mapping[str, _QueryVariable]", "Sequence[Tuple[str, _QueryVariable]]"
+SimpleQuery = Union[str, int, float]
+QueryVariable = Union[SimpleQuery, "Sequence[SimpleQuery]"]
+Query = Union[
+    None, str, "Mapping[str, QueryVariable]", "Sequence[Tuple[str, QueryVariable]]"
 ]
 _T = TypeVar("_T")
 
@@ -255,7 +255,7 @@ def build(
         host: str = "",
         port: Optional[int] = None,
         path: str = "",
-        query: Optional[_Query] = None,
+        query: Optional[Query] = None,
         query_string: str = "",
         fragment: str = "",
         encoded: bool = False,
@@ -394,7 +394,7 @@ def __truediv__(self, name: str) -> "URL":
             return NotImplemented
         return self._make_child((str(name),))
 
-    def __mod__(self, query: _Query) -> "URL":
+    def __mod__(self, query: Query) -> "URL":
         return self.update_query(query)
 
     def __bool__(self) -> bool:
@@ -1043,7 +1043,7 @@ def with_path(self, path: str, *, encoded: bool = False) -> "URL":
 
     @classmethod
     def _query_seq_pairs(
-        cls, quoter: Callable[[str], str], pairs: Iterable[Tuple[str, _QueryVariable]]
+        cls, quoter: Callable[[str], str], pairs: Iterable[Tuple[str, QueryVariable]]
     ) -> Iterator[str]:
         for key, val in pairs:
             if isinstance(val, (list, tuple)):
@@ -1053,7 +1053,7 @@ def _query_seq_pairs(
                 yield quoter(key) + "=" + quoter(cls._query_var(val))
 
     @staticmethod
-    def _query_var(v: _QueryVariable) -> str:
+    def _query_var(v: QueryVariable) -> str:
         cls = type(v)
         if issubclass(cls, str):
             if TYPE_CHECKING:
@@ -1078,7 +1078,7 @@ def _query_var(v: _QueryVariable) -> str:
         )
 
     def _get_str_query(self, *args: Any, **kwargs: Any) -> Optional[str]:
-        query: Optional[Union[str, Mapping[str, _QueryVariable]]]
+        query: Optional[Union[str, Mapping[str, QueryVariable]]]
         if kwargs:
             if len(args) > 0:
                 raise ValueError(
@@ -1119,10 +1119,10 @@ def _get_str_query(self, *args: Any, **kwargs: Any) -> Optional[str]:
         return query
 
     @overload
-    def with_query(self, query: _Query) -> "URL": ...
+    def with_query(self, query: Query) -> "URL": ...
 
     @overload
-    def with_query(self, **kwargs: _QueryVariable) -> "URL": ...
+    def with_query(self, **kwargs: QueryVariable) -> "URL": ...
 
     def with_query(self, *args: Any, **kwargs: Any) -> "URL":
         """Return a new URL with query part replaced.
@@ -1145,10 +1145,10 @@ def with_query(self, *args: Any, **kwargs: Any) -> "URL":
         )
 
     @overload
-    def update_query(self, query: _Query) -> "URL": ...
+    def update_query(self, query: Query) -> "URL": ...
 
     @overload
-    def update_query(self, **kwargs: _QueryVariable) -> "URL": ...
+    def update_query(self, **kwargs: QueryVariable) -> "URL": ...
 
     def update_query(self, *args: Any, **kwargs: Any) -> "URL":
         """Return a new URL with query part updated."""