Add comments

Author: ayjayt

src/py/kaleido/_utils/fig_tools.py

@@ -58,8 +58,8 @@ class Spec(TypedDict):
 )
 
 
-# validation function
 def is_figurish(o: Any) -> TypeGuard[Figurish]:
+    """Detect if input is a plotly figure or equivalent."""
     # so if data isn't in the dict things get weird.
     valid = hasattr(o, "to_dict") or (isinstance(o, dict) and "data" in o)
     if not valid:
@@ -72,7 +72,8 @@ def is_figurish(o: Any) -> TypeGuard[Figurish]:
 
 
 def _coerce_format(extension: str) -> FormatString:
-    # wrap this condition as a typeguard for typechecker's sake
+    """Satisfies a type checker that our format string is an accepted format."""
+
     def is_fmt(s: str) -> TypeGuard[FormatString]:
         return s in SUPPORTED_FORMATS
 
@@ -93,6 +94,14 @@ def coerce_for_js(
     path: Path | str | None,
     opts: LayoutOpts | None,
 ) -> Spec:
+    """
+    Package fig, path, and opts into a dictionary that javascript understands.
+
+    This will
+        - validate the inputs
+        - coerce the inputs if needed (eg. jpeg --> jpg)
+        - provide defaults if we can
+    """
     if not is_figurish(fig):  # VALIDATE FIG
         raise TypeError("Figure supplied doesn't seem to be a valid plotly figure.")
     if hasattr(fig, "to_dict"):  # COERCE FIG

src/py/kaleido/_utils/path_tools.py

@@ -16,6 +16,7 @@
 
 
 def _next_filename(path: Path | str, prefix: str, ext: str) -> str:
+    """Figure out proper suffix for generated file name."""
     path = path if isinstance(path, Path) else Path(path)
     default = 1 if (path / f"{prefix}.{ext}").exists() else 0
     re_number = re.compile(
@@ -37,6 +38,17 @@ def determine_path(
     fig: dict,
     ext: fig_tools.FormatString,
 ) -> Path:
+    """
+    Determine the filename by the algorithm described below.
+
+    If path is a directory (which exists), we try to create a filename from the
+    chart title, or we use the word "fig". If we are generating these filenames,
+    we check to see if a file with that name already exists and if so, we suffix
+    our generated name with a number.
+
+    If we are given a full path name, we simple make sure that all the subdirs
+    exist and we accept the user's argument.
+    """
     path = Path(path) if path else Path()
 
     if not path.suffix or path.is_dir():  # they gave us a directory
@@ -62,6 +74,17 @@ def determine_path(
 
 
 def get_path(p: str | Path) -> Path:
+    """
+    Ensure we have a path object.
+
+    Args:
+        p: p might be a Path or a string, which might be a plain path: /path/to
+        or a URI format: file:///path/to.
+
+    Returns:
+        A coerced and parsed path, obeying operating system weirdness.
+
+    """
     if isinstance(p, Path):
         return p
     elif not isinstance(p, str):
@@ -75,4 +98,5 @@ def get_path(p: str | Path) -> Path:
 
 
 def is_httpish(p: str) -> bool:
+    """Use urlparser to see if the path we've been given is a URL."""
     return urlparse(str(p)).scheme.startswith("http")

src/py/kaleido/kaleido.py

@@ -190,7 +190,7 @@ def __init__(
         self._saved_page_arg = page
 
     async def open(self):
-        """Build page and temporary file if we need one, then opens browser."""
+        """Build page and temporary file if we need one, then open browser."""
         page = self._saved_page_arg
         del self._saved_page_arg
 
@@ -423,7 +423,35 @@ async def write_fig_from_object(
         _write: bool = True,  # backwards compatibility!
         stepper: bool = False,
     ) -> None | bytes | tuple[Exception]:
-        """Temp."""
+        """
+        Create one or more plotly figures from a specification dictionary.
+
+        If every figure needs a different `opts` or `path` argument, you use
+        this instead of `write_fig`.
+
+        Args:
+            fig_dicts:
+                Any single figure dict, or an iterable of figure dictionaries. The
+                figure dictionaries *must* have a "fig" key with a plotly figure or
+                its dict representation. It can have the following keys: path, opts,
+                and topojson. This is roughly equal to the `write_fig` arguments.
+
+            cancel_on_error (boolean, default: False):
+                If False, any errors during rendering will be returned from the function
+                call in a list. If True, any error will be raised immediately and the
+                rest of the renders will be cancelled.
+
+            stepper (boolean, default False):
+                This is a debugging argument and is not part of the stable API.
+                If set to true, kaleido will wait for a key press to render each
+                image, in case one would want to inspect the browser environment.
+
+        Returns:
+            If cancel_on_error is True, it always returns None on success.
+            If cancel_on_error is False, it always returns a tuple, possibly
+            with errors.
+
+        """
         if not _write:
             cancel_on_error = True
 
@@ -479,7 +507,51 @@ async def write_fig(  # noqa: PLR0913
         cancel_on_error: bool = False,
         stepper: bool = False,
     ) -> tuple[Exception] | None:
-        """Temp."""
+        """
+        Create one or more plotly figures.
+
+        While fig may be an iterable, only a single path and opts may be passed.
+        Use write_fig_from_object if you need to specify different paths or opts
+        for each figure.
+
+        Args:
+            fig:
+                A plotly figure or its dict representation. It can have the
+                following keys: path, opts, and topojson. This is roughly equal
+                to the `write_fig` arguments.
+
+            path (None, Path, str):
+                The path where the image will be written. The default is the
+                current directory. If a filename isn't specified, we try to
+                generate one from the title or use a default "fig-". If you
+                pass many figures, this argument should be a directory.
+
+            opts (None, LayoutOpts dict):
+                The layout options are a dictionary with the following optional keys:
+                - scale: a number to multiply the image by.
+                - width: a number to set the pixel width.
+                - height: a number to set the pixel height.
+                - format: One of jpg, png, svg, pdf, json, or webp.
+
+            topojson:
+                An optional json-format map specification when using geomaps.
+
+            cancel_on_error (boolean, default: False):
+                If False, any errors during rendering will be returned from the function
+                call in a list. If True, any error will be raised immediately and the
+                rest of the renders will be cancelled.
+
+            stepper (boolean, default False):
+                This is a debugging argument and is not part of the stable API.
+                If set to true, kaleido will wait for a key press to render each
+                image, in case one would want to inspect the browser environment.
+
+        Returns:
+            If cancel_on_error is True, it always returns None on success.
+            If cancel_on_error is False, it always returns a tuple, possibly
+            with errors.
+
+        """
         if fig_tools.is_figurish(fig) or not isinstance(
             fig,
             (Iterable, AsyncIterable),
@@ -511,7 +583,15 @@ async def calc_fig(
         topojson: str | None = None,
         stepper: bool = False,
     ) -> bytes:
-        """Temp."""
+        """
+        Run write_fig but instead of writing a file, return the bytes.
+
+        The arguments are the same as write_fig, but path does nothing.
+
+        Returns:
+            The calculated bytes.
+
+        """
         if path is not None:
             warnings.warn(
                 "The path argument is deprecated in `kaleido.calc_fig`. "