refactor: expose catalog as Colormap classmethod (#22)

* refactor: update catalog, make public

* name methods

* test: add tests

* fix lint

* test: add test

* add unique names

.pre-commit-config.yaml

@@ -6,11 +6,6 @@ ci:
 exclude: ^LICENSE
 
 repos:
-  # - repo: https://github.com/crate-ci/typos
-  #   rev: v1.16.10
-  #   hooks:
-  #     - id: typos
-
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:

docs/_gen_cmaps.py

@@ -1,10 +1,13 @@
 import json
 from pathlib import Path
+from typing import TYPE_CHECKING, cast
 
 import mkdocs_gen_files
 import numpy as np
 
-from cmap import Colormap, _catalog
+if TYPE_CHECKING:
+    from cmap import _catalog
+from cmap import Colormap
 from cmap._util import report
 
 # TODO: convert to jinja
@@ -80,7 +83,7 @@
 )
 
 
-def build_catalog(catalog: _catalog.Catalog) -> None:
+def build_catalog(catalog: "_catalog.Catalog") -> None:
     for name in catalog:
         if ":" not in name:
             continue
@@ -132,4 +135,4 @@ def _make_aliases_md(aliases: list[str]) -> str:
     return "**Aliases**:  " + ", ".join(f"`{a}`" for a in aliases)
 
 
-build_catalog(_catalog.catalog)
+build_catalog(cast("_catalog.Catalog", Colormap.catalog()))

docs/_hooks.py

@@ -3,14 +3,18 @@
 import sys
 from functools import partial
 from pathlib import Path
-from typing import Any, Sequence
+from typing import TYPE_CHECKING, Any, Sequence, cast
 
 import numpy as np
 
 from cmap import Colormap, _util
-from cmap._catalog import CATALOG
+
+if TYPE_CHECKING:
+    from cmap._catalog import CatalogDict
 from cmap._color import NAME_TO_RGB
 
+CATALOG = cast("CatalogDict", Colormap.catalog()._data)  # type: ignore
+
 # the template for a single colormap
 CMAP_DIV = """
 <div class="cmap {class_list}" id="cmap-{name}">
@@ -92,7 +96,7 @@ def _cmap_catalog() -> str:
             continue
         category = details.get("category") or "Uncategorized"
         categories.add(category)
-        classes = ["filterDiv"] + [category.lower()]
+        classes = ["filterDiv", category.lower()]
         lines.append(_cmap_div(cmap_name, classes))
 
     btns = [

src/cmap/__init__.py

@@ -1,17 +1,70 @@
 """Scientific colormaps for python, without dependencies."""
 from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Iterator, Mapping
 
 try:
     __version__ = version("cmap")
 except PackageNotFoundError:  # pragma: no cover
     __version__ = "uninstalled"
 
+
 from ._color import HSLA, HSVA, RGBA, RGBA8, Color
 from ._colormap import Colormap
 
+if TYPE_CHECKING:
+    from ._catalog import CatalogItem
+
+    class Catalog(Mapping[str, CatalogItem]):
+        """Catalog of available colormaps."""
+
+        def __getitem__(self, name: str) -> CatalogItem:
+            """Get a catalog item by name."""
+
+        def __iter__(self) -> Iterator[str]:
+            """Iterate over available colormap keys."""
+
+        def __len__(self) -> int:
+            """Return the number of available colormap keys.
+
+            Note: this is greater than the number of colormaps, as each colormap
+            may have multiple aliases.
+            """
+
+        def unique_keys(
+            self, prefer_short_names: bool = True, normalized_names: bool = False
+        ) -> set[str]:
+            """Return names that refer to unique colormap data.
+
+            Parameters
+            ----------
+            prefer_short_names : bool, optional
+                If True (default), short names (without the namespace prefix) will be
+                preferred over fully qualified names. In cases where the same short name
+                is used in multiple namespaces, they will *all* be referred to by their
+                fully qualified (namespaced) name.
+            normalized_names : bool, optional
+                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).
+            """
+
+        def short_keys(self) -> set[str]:
+            """Return a set of available short colormap names, without namespace."""
+
+        def namespaced_keys(self) -> set[str]:
+            """Return a set of available short colormap names, with namespace."""
+
+        def resolve(self, name: str) -> str:
+            """Return the fully qualified, normalized name of a colormap or alias."""
+
+else:
+    from ._catalog import Catalog, CatalogItem
+
 __all__ = [
     "Color",
     "Colormap",
+    "CatalogItem",
+    "Catalog",
     "HSLA",
     "HSVA",
     "RGBA",