Merge branch 'when-then-user-guide' of https://github.com/dangotbanne…

…d/altair into when-then-user-guide

RELEASING.md

@@ -4,7 +4,7 @@
 
        hatch env prune
 
-2. Make certain your branch is in sync with head:
+2. Make certain your branch is in sync with head. If you work on a fork, replace `origin` with `upstream`:
 
        git pull origin main
 
@@ -17,48 +17,67 @@
    Navigate to http://localhost:8000 and ensure it looks OK (particularly
    do a visual scan of the gallery thumbnails).
 
-4. Update version to, e.g. 5.0.0:
+4. Create a new release branch:
+
+       git switch -c version_5.0.0
+
+5. Update version to, e.g. 5.0.0:
 
    - in ``altair/__init__.py``
    - in ``doc/conf.py``
 
-5. Commit change and push to main:
+6. Commit changes and push:
 
        git add . -u
        git commit -m "chore: Bump version to 5.0.0"
-       git push origin main
+       git push
+
+7. Merge release branch into main, make sure that all required checks pass
 
-6. Tag the release:
+8. Tag the release:
 
        git tag -a v5.0.0 -m "version 5.0.0 release"
        git push origin v5.0.0
 
-7. Build source & wheel distributions:
+9. On main, build source & wheel distributions. If you work on a fork, replace `origin` with `upstream`:
 
+       git switch main
+       git pull origin main
        hatch clean  # clean old builds & distributions
        hatch build  # create a source distribution and universal wheel
 
-8. publish to PyPI (Requires correct PyPI owner permissions):
+10. publish to PyPI (Requires correct PyPI owner permissions):
 
         hatch publish
 
-9. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io):
+11. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io):
 
         hatch run doc:publish-clean-build
 
-10. update version to, e.g. 5.1.0dev:
+12. On main, tag the release. If you work on a fork, replace `origin` with `upstream`:
+
+        git tag -a v5.0.0 -m "Version 5.0.0 release"
+        git push origin v5.0.0
+
+13. Create a new branch:
+
+       git switch -c maint_5.1.0dev
+
+14. Update version and add 'dev' suffix, e.g. 5.1.0dev:
 
     - in ``altair/__init__.py``
     - in ``doc/conf.py``
 
-11. Commit change and push to main:
+15. Commit changes and push:
 
         git add . -u
         git commit -m "chore: Bump version to 5.1.0dev"
-        git push origin main
+        git push
+        
+16. Merge maintenance branch into main
 
-12. Double-check that a conda-forge pull request is generated from the updated
+17. Double-check that a conda-forge pull request is generated from the updated
     pip package by the conda-forge bot (may take up to several hours):
     https://github.com/conda-forge/altair-feedstock/pulls
 
-13. Publish a new release in https://github.com/vega/altair/releases/
+18. Publish a new release in https://github.com/vega/altair/releases/

altair/utils/execeval.py

@@ -1,33 +1,70 @@
+from __future__ import annotations
+
 import ast
 import sys
+from typing import TYPE_CHECKING, Any, Callable, Literal, overload
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+    from _typeshed import ReadableBuffer
+
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    else:
+        from typing_extensions import Self
 
 
 class _CatchDisplay:
     """Class to temporarily catch sys.displayhook."""
 
-    def __init__(self):
-        self.output = None
+    def __init__(self) -> None:
+        self.output: Any | None = None
 
-    def __enter__(self):
-        self.old_hook = sys.displayhook
+    def __enter__(self) -> Self:
+        self.old_hook: Callable[[object], Any] = sys.displayhook
         sys.displayhook = self
         return self
 
-    def __exit__(self, type, value, traceback):
+    def __exit__(self, type, value, traceback) -> Literal[False]:
         sys.displayhook = self.old_hook
         # Returning False will cause exceptions to propagate
         return False
 
-    def __call__(self, output):
+    def __call__(self, output: Any) -> None:
         self.output = output
 
 
-def eval_block(code, namespace=None, filename="<string>"):
+@overload
+def eval_block(
+    code: str | Any,
+    namespace: dict[str, Any] | None = ...,
+    filename: str | ReadableBuffer | PathLike[Any] = ...,
+    *,
+    strict: Literal[False] = ...,
+) -> Any | None: ...
+@overload
+def eval_block(
+    code: str | Any,
+    namespace: dict[str, Any] | None = ...,
+    filename: str | ReadableBuffer | PathLike[Any] = ...,
+    *,
+    strict: Literal[True] = ...,
+) -> Any: ...
+def eval_block(
+    code: str | Any,
+    namespace: dict[str, Any] | None = None,
+    filename: str | ReadableBuffer | PathLike[Any] = "<string>",
+    *,
+    strict: bool = False,
+) -> Any | None:
     """
     Execute a multi-line block of code in the given namespace.
 
     If the final statement in the code is an expression, return
     the result of the expression.
+
+    If ``strict``, raise a ``TypeError`` when the return value would be ``None``.
     """
     tree = ast.parse(code, filename="<ast>", mode="exec")
     if namespace is None:
@@ -50,4 +87,12 @@ def eval_block(code, namespace=None, filename="<string>"):
             )
             exec(compiled, namespace)
 
-    return catch_display.output
+    if strict:
+        output = catch_display.output
+        if output is None:
+            msg = f"Expected a non-None value but got {output!r}"
+            raise TypeError(msg)
+        else:
+            return output
+    else:
+        return catch_display.output