Make SimpleQuery, QueryVariable, and Query types available

CHANGES/1050.contrib.rst

@@ -0,0 +1 @@
+1113.contrib.rst

CHANGES/1113.contrib.rst

@@ -0,0 +1 @@
+The previously protected types ``_SimpleQuery``, ``_QueryVariable``, and ``_Query`` are now available for use externally as ``SimpleQuery``, ``QueryVariable``, and ``Query`` -- by :user:`bdraco`.

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"]

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.10.0.dev0"
 
-__all__ = ("URL", "cache_clear", "cache_configure", "cache_info")
+__all__ = (
+    "URL",
+    "SimpleQuery",
+    "QueryVariable",
+    "Query",
+    "cache_clear",
+    "cache_configure",
+    "cache_info",
+)

yarl/_url.py

@@ -40,10 +40,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")
 
@@ -254,7 +254,7 @@ def build(
         host: str = "",
         port: Union[int, None] = None,
         path: str = "",
-        query: Union[_Query, None] = None,
+        query: Union[Query, None] = None,
         query_string: str = "",
         fragment: str = "",
         encoded: bool = False,
@@ -393,7 +393,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:
@@ -1042,7 +1042,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)):
@@ -1052,7 +1052,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:
@@ -1077,7 +1077,7 @@ def _query_var(v: _QueryVariable) -> str:
         )
 
     def _get_str_query(self, *args: Any, **kwargs: Any) -> Union[str, None]:
-        query: Union[str, Mapping[str, _QueryVariable], None]
+        query: Union[str, Mapping[str, QueryVariable], None]
         if kwargs:
             if len(args) > 0:
                 raise ValueError(
@@ -1118,10 +1118,10 @@ def _get_str_query(self, *args: Any, **kwargs: Any) -> Union[str, None]:
         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.
@@ -1144,10 +1144,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."""