API: rename to_list(), to_set(), … to as_list(), as_set(), … (#373)

src/pytools/api/_api.py

@@ -22,10 +22,10 @@
     "deprecation_warning",
     "get_generic_bases",
     "is_list_like",
-    "to_collection",
-    "to_list",
-    "to_set",
-    "to_tuple",
+    "as_collection",
+    "as_list",
+    "as_set",
+    "as_tuple",
     "validate_element_types",
     "validate_type",
 ]
@@ -85,7 +85,7 @@ def is_list_like(obj: Any) -> bool:
 
 
 @overload
-def to_tuple(
+def as_tuple(
     values: Iterable[T],
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -97,7 +97,7 @@ def to_tuple(
 
 
 @overload
-def to_tuple(
+def as_tuple(
     values: T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -108,7 +108,7 @@ def to_tuple(
     pass
 
 
-def to_tuple(
+def as_tuple(
     values: Iterable[T] | T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -135,7 +135,7 @@ def to_tuple(
     :raise TypeError: one or more values did not match the expected type(s)
     """
 
-    return _to_collection(
+    return _as_collection(
         values=values,
         collection_type=tuple,
         new_collection_type=tuple,
@@ -146,7 +146,7 @@ def to_tuple(
 
 
 @overload
-def to_list(
+def as_list(
     values: Iterable[T],
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -158,7 +158,7 @@ def to_list(
 
 
 @overload
-def to_list(
+def as_list(
     values: T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -169,8 +169,8 @@ def to_list(
     pass
 
 
-@subsdoc(pattern="tuple", replacement="list", using=to_tuple)
-def to_list(
+@subsdoc(pattern="tuple", replacement="list", using=as_tuple)
+def as_list(
     values: Iterable[T] | T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -179,7 +179,7 @@ def to_list(
 ) -> list[T]:
     """[will be substituted]"""
 
-    return _to_collection(
+    return _as_collection(
         values=values,
         collection_type=list,
         new_collection_type=list,
@@ -190,7 +190,7 @@ def to_list(
 
 
 @overload
-def to_set(
+def as_set(
     values: Iterable[T],
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -202,7 +202,7 @@ def to_set(
 
 
 @overload
-def to_set(
+def as_set(
     values: T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -213,8 +213,8 @@ def to_set(
     pass
 
 
-@subsdoc(pattern="tuple", replacement="set", using=to_tuple)
-def to_set(
+@subsdoc(pattern="tuple", replacement="set", using=as_tuple)
+def as_set(
     values: Iterable[T] | T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -223,7 +223,7 @@ def to_set(
 ) -> set[T]:
     """[will be substituted]"""
 
-    return _to_collection(
+    return _as_collection(
         values=values,
         collection_type=set,
         new_collection_type=set,
@@ -234,7 +234,7 @@ def to_set(
 
 
 @overload
-def to_collection(
+def as_collection(
     values: Iterable[T],
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -246,7 +246,7 @@ def to_collection(
 
 
 @overload
-def to_collection(
+def as_collection(
     values: T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
@@ -263,16 +263,16 @@ def to_collection(
     pattern=r"(given values as a collection)",
     replacement=r"\1, i.e., an iterable container",
 )
-@subsdoc(pattern="tuple", replacement="collection", using=to_tuple)
-def to_collection(
+@subsdoc(pattern="tuple", replacement="collection", using=as_tuple)
+def as_collection(
     values: Iterable[T] | T | None,
     *,
     element_type: type[T] | tuple[type[T], ...] | None = None,
     optional: bool = False,
     arg_name: str | None = None,
 ) -> Collection[T]:
     """[will be substituted]"""
-    return _to_collection(
+    return _as_collection(
         values=values,
         collection_type=None,
         new_collection_type=cast(type[tuple[Any, ...]], tuple),
@@ -282,7 +282,7 @@ def to_collection(
     )
 
 
-def _to_collection(
+def _as_collection(
     values: Iterable[T] | T | None,
     *,
     collection_type: type[Collection[Any]] | None,

src/pytools/api/_doc_validator.py

@@ -13,7 +13,7 @@
 from typing import Any, TypeVar
 
 from ._alltracker import AllTracker
-from ._api import to_tuple
+from ._api import as_tuple
 from .doc import (
     APIDefinition,
     DocTest,
@@ -110,7 +110,7 @@ def __init__(
             element
         """
         self.root_dir = root_dir
-        self.validate_protected = to_tuple(
+        self.validate_protected = as_tuple(
             validate_protected or self.DEFAULT_VALIDATE_PROTECTED,
             element_type=str,
         )

src/pytools/data/taxonomy/_category.py

@@ -10,7 +10,7 @@
 from collections.abc import Iterable
 from typing import Any, Self, cast, final
 
-from pytools.api import to_tuple
+from pytools.api import as_tuple
 
 log = logging.getLogger(__name__)
 
@@ -38,7 +38,7 @@ def __init__(self, *, children: Self | Iterable[Self] | None = None) -> None:
         """
         :param children: the subcategories of the category (optional)
         """
-        self._children = to_tuple(
+        self._children = as_tuple(
             children, element_type=type(self), arg_name="subcategories", optional=True
         )
 

src/pytools/expression/_expression.py

@@ -11,7 +11,7 @@
 import numpy as np
 import numpy.typing as npt
 
-from ..api import AllTracker, inheritdoc, to_list
+from ..api import AllTracker, as_list, inheritdoc
 from .operator import BinaryOperator, UnaryOperator
 
 log = logging.getLogger(__name__)
@@ -406,10 +406,10 @@ def __getitem__(self, key: Any) -> Expression:
         return Index(self, key)
 
     def __setitem__(self, key: Any, value: Any) -> None:
-        raise TypeError(f"cannot set indexed item of Expression: {to_list(key)}")
+        raise TypeError(f"cannot set indexed item of Expression: {as_list(key)}")
 
     def __delitem__(self, key: Any) -> None:
-        raise TypeError(f"cannot delete indexed item of Expression: {to_list(key)}")
+        raise TypeError(f"cannot delete indexed item of Expression: {as_list(key)}")
 
     def __getattr__(self, key: str) -> Expression:
         if key.startswith("_") or key.endswith("_"):

src/pytools/parallelization/_parallelization.py

@@ -15,7 +15,7 @@
 
 import joblib
 
-from ..api import AllTracker, inheritdoc, to_tuple
+from ..api import AllTracker, as_tuple, inheritdoc
 
 log = logging.getLogger(__name__)
 
@@ -281,7 +281,7 @@ def run_queues(
             :meth:`.JobQueue.aggregate`
         """
 
-        queues_seq: Sequence[JobQueue[T_Job_Result, T_Queue_Result]] = to_tuple(
+        queues_seq: Sequence[JobQueue[T_Job_Result, T_Queue_Result]] = as_tuple(
             queues,
             element_type=cast(type[JobQueue[T_Job_Result, T_Queue_Result]], JobQueue),
             arg_name="queues",
@@ -347,7 +347,7 @@ def __init__(self, jobs: Iterable[Job[T_Job_Result]]) -> None:
         :param jobs: jobs to be run by this queue in the given order
         """
         super().__init__()
-        self._jobs = to_tuple(
+        self._jobs = as_tuple(
             jobs, element_type=cast(type[Job[T_Job_Result]], Job), arg_name="jobs"
         )
 
@@ -379,7 +379,7 @@ def __init__(
             order
         """
         super().__init__()
-        self.queues = to_tuple(
+        self.queues = as_tuple(
             queues,
             element_type=cast(
                 type[JobQueue[T_Job_Result, list[T_Job_Result]]], JobQueue

src/pytools/text/_template.py

@@ -9,7 +9,7 @@
 from collections.abc import Iterable, Sized
 from typing import Any
 
-from pytools.api import inheritdoc, to_set
+from pytools.api import as_set, inheritdoc
 from pytools.expression import (
     Expression,
     HasExpressionRepr,
@@ -82,7 +82,7 @@ def __init__(
             ignored (default: ``False``)
         """
         super().__init__()
-        required_keys = to_set(
+        required_keys = as_set(
             required_keys,
             element_type=str,
             arg_name="formatting_keys",
@@ -153,7 +153,7 @@ def _validate_format_string(
         raise TypeError(f"Format string must be a string, but got: {format_string!r}")
 
     # ensure arg expected_keys is a set
-    required_keys = to_set(required_keys, element_type=str, arg_name="required_keys")
+    required_keys = as_set(required_keys, element_type=str, arg_name="required_keys")
 
     # get all keys from the format string
     actual_keys = {

src/pytools/viz/_matplot.py

@@ -20,7 +20,7 @@
 from matplotlib.ticker import Formatter
 from packaging.version import Version
 
-from ..api import AllTracker, inheritdoc, to_list
+from ..api import AllTracker, as_list, inheritdoc
 from ._viz import ColoredStyle
 from .color import MatplotColorScheme, RgbaColor
 
@@ -95,7 +95,7 @@ def __init__(
 
         if font_family is not None:
             font_family = (
-                to_list(font_family, element_type=str, arg_name="font")
+                as_list(font_family, element_type=str, arg_name="font")
                 + default_font_family
             )
         else: