feat: Adds ChartType type and type guard is_chart_type. Change PurePath to Path type hints

altair/utils/save.py

@@ -9,28 +9,26 @@
 
 
 def write_file_or_filename(
-    fp: Union[str, pathlib.PurePath, IO],
+    fp: Union[pathlib.Path, IO],
     content: Union[str, bytes],
     mode: str = "w",
     encoding: Optional[str] = None,
 ) -> None:
     """Write content to fp, whether fp is a string, a pathlib Path or a
     file-like object"""
-    if isinstance(fp, str) or isinstance(fp, pathlib.PurePath):
+    if isinstance(fp, pathlib.Path):
         with open(file=fp, mode=mode, encoding=encoding) as f:
             f.write(content)
     else:
         fp.write(content)
 
 
 def set_inspect_format_argument(
-    format: Optional[str], fp: Union[str, pathlib.PurePath, IO], inline: bool
+    format: Optional[str], fp: Union[pathlib.Path, IO], inline: bool
 ) -> str:
     """Inspect the format argument in the save function"""
     if format is None:
-        if isinstance(fp, str):
-            format = fp.split(".")[-1]
-        elif isinstance(fp, pathlib.PurePath):
+        if isinstance(fp, pathlib.Path):
             format = fp.suffix.lstrip(".")
         else:
             raise ValueError(
@@ -70,7 +68,7 @@ def set_inspect_mode_argument(
 
 def save(
     chart,
-    fp: Union[str, pathlib.PurePath, IO],
+    fp: Union[str, pathlib.Path, IO],
     vega_version: Optional[str],
     vegaembed_version: Optional[str],
     format: Optional[Literal["json", "html", "png", "svg", "pdf"]] = None,
@@ -130,6 +128,8 @@ def save(
     """
     if json_kwds is None:
         json_kwds = {}
+    fp = pathlib.Path(fp) if isinstance(fp, str) else fp
+    encoding = kwargs.get("encoding", "utf-8")
 
     format = set_inspect_format_argument(format, fp, inline)  # type: ignore[assignment]
 
@@ -142,9 +142,7 @@ def perform_save():
 
         if format == "json":
             json_spec = json.dumps(spec, **json_kwds)
-            write_file_or_filename(
-                fp, json_spec, mode="w", encoding=kwargs.get("encoding", "utf-8")
-            )
+            write_file_or_filename(fp, json_spec, mode="w", encoding=encoding)
         elif format == "html":
             if inline:
                 kwargs["template"] = "inline"
@@ -160,12 +158,9 @@ def perform_save():
                 **kwargs,
             )
             write_file_or_filename(
-                fp,
-                mimebundle["text/html"],
-                mode="w",
-                encoding=kwargs.get("encoding", "utf-8"),
+                fp, mimebundle["text/html"], mode="w", encoding=encoding
             )
-        elif format in ["png", "svg", "pdf", "vega"]:
+        elif format in {"png", "svg", "pdf", "vega"}:
             mimebundle = spec_to_mimebundle(
                 spec=spec,
                 format=format,
@@ -184,7 +179,6 @@ def perform_save():
             elif format == "pdf":
                 write_file_or_filename(fp, mimebundle["application/pdf"], mode="wb")
             else:
-                encoding = kwargs.get("encoding", "utf-8")
                 write_file_or_filename(
                     fp, mimebundle["image/svg+xml"], mode="w", encoding=encoding
                 )

altair/vegalite/v5/api.py

@@ -8,6 +8,7 @@
 from toolz.curried import pipe as _pipe
 import itertools
 import sys
+import pathlib
 from typing import cast, List, Optional, Any, Iterable, Union, Literal, IO
 
 # Have to rename it here as else it overlaps with schema.core.Type and schema.core.Dict
@@ -29,6 +30,10 @@
 from ...utils.core import DataFrameLike
 from ...utils.data import DataType
 
+if sys.version_info >= (3, 13):
+    from typing import TypeIs
+else:
+    from typing_extensions import TypeIs
 if sys.version_info >= (3, 11):
     from typing import Self
 else:
@@ -1137,7 +1142,7 @@ def open_editor(self, *, fullscreen: bool = False) -> None:
 
     def save(
         self,
-        fp: Union[str, IO],
+        fp: Union[str, pathlib.Path, IO],
         format: Optional[Literal["json", "html", "png", "svg", "pdf"]] = None,
         override_data_transformer: bool = True,
         scale_factor: float = 1.0,
@@ -4089,3 +4094,24 @@ def graticule(**kwds):
 def sphere() -> core.SphereGenerator:
     """Sphere generator."""
     return core.SphereGenerator(sphere=True)
+
+
+_ChartType = Union[
+    Chart, RepeatChart, ConcatChart, HConcatChart, VConcatChart, FacetChart, LayerChart
+]
+
+
+def _is_chart_type(obj: Any) -> TypeIs[_ChartType]:
+    """Return `True` if the object is basic or compound `Chart`."""
+    return isinstance(
+        obj,
+        (
+            Chart,
+            RepeatChart,
+            ConcatChart,
+            HConcatChart,
+            VConcatChart,
+            FacetChart,
+            LayerChart,
+        ),
+    )

tools/update_init_file.py

@@ -21,6 +21,10 @@
     cast,
 )
 
+if sys.version_info >= (3, 13):
+    from typing import TypeIs
+else:
+    from typing_extensions import TypeIs
 if sys.version_info >= (3, 11):
     from typing import Self
 else:
@@ -97,6 +101,7 @@ def _is_relevant_attribute(attr_name: str) -> bool:
         or attr is Protocol
         or attr is Sequence
         or attr is IO
+        or attr is TypeIs
         or attr_name == "TypingDict"
         or attr_name == "TypingGenerator"
         or attr_name == "ValueOrDatum"