feat: select unique names by category (#25)

Author: tlambert03

src/cmap/_catalog.py

@@ -14,6 +14,7 @@
 from typing import (
     TYPE_CHECKING,
     Any,
+    Container,
     Iterable,
     Iterator,
     Literal,
@@ -94,7 +95,7 @@ class CatalogItem:
     interpolation: bool | Interpolation
         The interpolation method to use when sampling the colormap.  One of
         {False, True, "linear", "nearest"}, where False is equivalent to "nearest"
-        and True is equivalent to "linear".
+        and True is equivalent to "linear".  If not provided, defaults to "linear".
     tags: list[str]
         A list of tags for the colormap. These are displayed in the documentation.
     aliases: list[str]
@@ -235,7 +236,11 @@ def __init__(
                 )
 
     def unique_keys(
-        self, prefer_short_names: bool = True, normalized_names: bool = False
+        self,
+        prefer_short_names: bool = True,
+        normalized_names: bool = False,
+        categories: Container[Category] = (),
+        interpolation: Interpolation | None = None,
     ) -> set[str]:
         """Return names that refer to unique colormap data.
 
@@ -250,6 +255,10 @@ def unique_keys(
             If True, return the normalized names of the colormaps.  If False (default),
             return the original names of the colormaps (which may include spaces and/or
             capital letters).
+        categories : Container[Category], optional
+            If provided, only return colormaps in the given categories.
+        interpolation : Interpolation, optional
+            If provided, only return colormaps with the given interpolation method.
 
         Returns
         -------
@@ -258,8 +267,18 @@ def unique_keys(
         """
         keys: set[str] = set()
         for original_name, normed_name in self._original_names.items():
-            if "alias" in self._data[normed_name]:
+            data = self._data[normed_name]
+            if "alias" in data:
                 continue
+            if categories and data["category"] not in categories:
+                continue
+            if interpolation is not None:
+                interp = data.get("interpolation", "linear")
+                if isinstance(interp, bool):
+                    interp = "linear" if interp else "nearest"
+                if interp != interpolation:
+                    continue
+
             if prefer_short_names:
                 short_name = normed_name.split(NAMESPACE_DELIMITER, 1)[-1]
                 data2 = self._data[short_name]

src/cmap/_colormap.py

@@ -4,28 +4,17 @@
 import warnings
 from functools import partial
 from numbers import Number
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Iterable,
-    Iterator,
-    Mapping,
-    NamedTuple,
-    Sequence,
-    Union,
-    cast,
-    overload,
-)
+from typing import TYPE_CHECKING, NamedTuple, Sequence, cast, overload
 
 import numpy as np
 import numpy.typing as npt
 
 from . import _external
+from ._catalog import Catalog
 from ._color import Color
 
 if TYPE_CHECKING:
-    from typing import Literal
+    from typing import Any, Callable, Iterable, Iterator, Literal, Union
 
     import bokeh.models
     import matplotlib.colors
@@ -130,14 +119,12 @@ class Colormap:
     interpolation: Interpolation
     info: CatalogItem | None
 
-    _catalog_instance: Mapping[str, CatalogItem] | None = None
+    _catalog_instance: Catalog | None = None
 
     @classmethod
-    def catalog(cls) -> Mapping[str, CatalogItem]:
+    def catalog(cls) -> Catalog:
         """Return the global colormaps catalog."""
         if cls._catalog_instance is None:
-            from ._catalog import Catalog
-
             cls._catalog_instance = Catalog()
         return cls._catalog_instance
 

tests/test_catalog.py

@@ -64,3 +64,8 @@ def test_catalog_names() -> None:
     assert "viridis" not in unique
     assert "bids:viridis" in unique
     assert "matplotlib:viridis" not in unique
+
+    assert "viridis" not in catalog.unique_keys(categories=("cyclic",))
+    assert "viridis" in catalog.unique_keys(categories=("sequential",))
+    assert "viridis" not in catalog.unique_keys(interpolation="nearest")
+    assert "viridis" in catalog.unique_keys(interpolation="linear")