Python SDK: Add strict mode (#1477)

* Python SDK: Add a decorator to all out logging function to early-out

This replaces explicit checks with a decorator.

This decorator declaration preserves type information
in Python 3.8 in my VSCode, which was a problem with previous attempts.

In a follow-up PR we can add a try-catch to the decorator to prevent
errors from bubbling up to the user.

* Catch and log exceptions in log_decorator

* Replace a few _send_warning with raise

* Make strict-mode opt-in

* Clean up scripts/lint.py

* emil should learn to type and and spellcheck

Co-authored-by: Andreas Reich <[email protected]>

* can we get automated spell checking of docstrings?

Co-authored-by: Andreas Reich <[email protected]>

* surely there is a spell checker for python docstrings, right?

Co-authored-by: Andreas Reich <[email protected]>

* not misuses - incorrect use

---------

Co-authored-by: Andreas Reich <[email protected]>

rerun_py/rerun_sdk/rerun/__init__.py

@@ -60,6 +60,11 @@
 ]
 
 
+# If `True`, we raise exceptions on use error (wrong parameter types etc).
+# If `False` we catch all errors and log a warning instead.
+_strict_mode = False
+
+
 def rerun_shutdown() -> None:
     bindings.shutdown()
 
@@ -118,7 +123,7 @@ def set_recording_id(value: str) -> None:
     bindings.set_recording_id(value)
 
 
-def init(application_id: str, spawn: bool = False, default_enabled: bool = True) -> None:
+def init(application_id: str, spawn: bool = False, default_enabled: bool = True, strict: bool = False) -> None:
     """
     Initialize the Rerun SDK with a user-chosen application id (name).
 
@@ -139,8 +144,13 @@ def init(application_id: str, spawn: bool = False, default_enabled: bool = True)
     default_enabled
         Should Rerun logging be on by default?
         Can overridden with the RERUN env-var, e.g. `RERUN=on` or `RERUN=off`.
+    strict
+        If `True`, an exceptions is raised on use error (wrong parameter types etc).
+        If `False`, errors are logged as warnings instead.
 
     """
+
+    _strict_mode = strict
     application_path = None
 
     # NOTE: It'd be even nicer to do such thing on the Rust-side so that this little trick would
@@ -216,6 +226,34 @@ def set_enabled(enabled: bool) -> None:
     bindings.set_enabled(enabled)
 
 
+def strict_mode() -> bool:
+    """
+    Strict mode enabled.
+
+    In strict mode, incorrect use of the Rerun API (wrong parameter types etc.)
+    will result in exception being raised.
+    When strict mode is on, such problems are instead logged as warnings.
+
+    The default is OFF.
+    """
+
+    return _strict_mode
+
+
+def set_strict_mode(strict_mode: bool) -> None:
+    """
+    Turn strict mode on/off.
+
+    In strict mode, incorrect use of the Rerun API (wrong parameter types etc.)
+    will result in exception being raised.
+    When strict mode is off, such problems are instead logged as warnings.
+
+    The default is OFF.
+    """
+
+    _strict_mode = strict_mode
+
+
 def connect(addr: Optional[str] = None) -> None:
     """
     Connect to a remote Rerun Viewer on the given ip:port.

rerun_py/rerun_sdk/rerun/log/annotation.py

@@ -3,6 +3,7 @@
 
 from rerun import bindings
 from rerun.log import Color, _normalize_colors
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "AnnotationInfo",
@@ -72,6 +73,7 @@ def coerce_class_descriptor_like(arg: ClassDescriptionLike) -> ClassDescription:
         return ClassDescription(info=arg)  # type: ignore[arg-type]
 
 
+@log_decorator
 def log_annotation_context(
     entity_path: str,
     class_descriptions: Union[ClassDescriptionLike, Iterable[ClassDescriptionLike]],
@@ -114,9 +116,6 @@ def log_annotation_context(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     if not isinstance(class_descriptions, Iterable):
         class_descriptions = [class_descriptions]
 

rerun_py/rerun_sdk/rerun/log/arrow.py

@@ -11,12 +11,14 @@
 from rerun.components.radius import RadiusArray
 from rerun.log import _normalize_colors, _normalize_radii
 from rerun.log.extension_components import _add_extension_components
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "log_arrow",
 ]
 
 
+@log_decorator
 def log_arrow(
     entity_path: str,
     origin: Optional[npt.ArrayLike],
@@ -58,9 +60,6 @@ def log_arrow(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     instanced: Dict[str, Any] = {}
     splats: Dict[str, Any] = {}
 

rerun_py/rerun_sdk/rerun/log/bounding_box.py

@@ -14,12 +14,14 @@
 from rerun.components.vec import Vec3DArray
 from rerun.log import _normalize_colors, _normalize_ids, _normalize_radii
 from rerun.log.extension_components import _add_extension_components
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "log_obb",
 ]
 
 
+@log_decorator
 def log_obb(
     entity_path: str,
     half_size: Optional[npt.ArrayLike],
@@ -66,9 +68,6 @@ def log_obb(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     instanced: Dict[str, Any] = {}
     splats: Dict[str, Any] = {}
 

rerun_py/rerun_sdk/rerun/log/camera.py

@@ -2,12 +2,14 @@
 import numpy.typing as npt
 
 from rerun import bindings
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "log_pinhole",
 ]
 
 
+@log_decorator
 def log_pinhole(
     entity_path: str,
     *,
@@ -59,9 +61,6 @@ def log_pinhole(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     # Transform arrow handling happens inside the python bridge
     bindings.log_pinhole(
         entity_path,

rerun_py/rerun_sdk/rerun/log/error_utils.py

@@ -1,6 +1,7 @@
 import inspect
 import logging
 
+from rerun import bindings
 from rerun.log.text import LogLevel, log_text_entry
 
 __all__ = [
@@ -15,7 +16,17 @@ def _build_warning_context_string(skip_first: int) -> str:
 
 
 def _send_warning(message: str, depth_to_user_code: int) -> None:
-    """Sends a warning about the usage of the Rerun SDK."""
+    """
+    Sends a warning about the usage of the Rerun SDK.
+
+    Used for recoverable problems.
+    You can also use this fo unrecoverable problems,
+    or raise an exception and let the @log_decorator handle it instead.
+    """
+
+    if bindings.strict_mode():
+        raise TypeError(message)
+
     context_descriptor = _build_warning_context_string(skip_first=depth_to_user_code + 2)
     warning = f"{message}\n{context_descriptor}"
     log_text_entry("rerun", warning, level=LogLevel.WARN)

rerun_py/rerun_sdk/rerun/log/extension_components.py

@@ -8,6 +8,7 @@
 import rerun.log.error_utils
 from rerun import bindings
 from rerun.components.instance import InstanceArray
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "_add_extension_components",
@@ -61,6 +62,7 @@ def _add_extension_components(
             instanced[name] = pa_value
 
 
+@log_decorator
 def log_extension_components(
     entity_path: str,
     ext: Dict[str, Any],
@@ -109,9 +111,6 @@ def log_extension_components(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     identifiers_np = np.array((), dtype="uint64")
     if identifiers:
         try:

rerun_py/rerun_sdk/rerun/log/file.py

@@ -7,6 +7,7 @@
 import numpy.typing as npt
 
 from rerun import bindings
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "MeshFormat",
@@ -39,6 +40,7 @@ class ImageFormat(Enum):
     """JPEG format."""
 
 
+@log_decorator
 def log_mesh_file(
     entity_path: str,
     mesh_format: MeshFormat,
@@ -77,9 +79,6 @@ def log_mesh_file(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     if transform is None:
         transform = np.empty(shape=(0, 0), dtype=np.float32)
     else:
@@ -89,6 +88,7 @@ def log_mesh_file(
     bindings.log_mesh_file(entity_path, mesh_format.value, mesh_file, transform, timeless)
 
 
+@log_decorator
 def log_image_file(
     entity_path: str,
     *,
@@ -121,9 +121,6 @@ def log_image_file(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     img_format = getattr(img_format, "value", None)
 
     # Image file arrow handling happens inside the python bridge

rerun_py/rerun_sdk/rerun/log/image.py

@@ -5,6 +5,7 @@
 
 from rerun import bindings
 from rerun.log.error_utils import _send_warning
+from rerun.log.log_decorator import log_decorator
 from rerun.log.tensor import Tensor, _log_tensor, _to_numpy
 
 __all__ = [
@@ -14,6 +15,7 @@
 ]
 
 
+@log_decorator
 def log_image(
     entity_path: str,
     image: Tensor,
@@ -47,9 +49,6 @@ def log_image(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     image = _to_numpy(image)
 
     shape = image.shape
@@ -77,6 +76,7 @@ def log_image(
     _log_tensor(entity_path, image, ext=ext, timeless=timeless)
 
 
+@log_decorator
 def log_depth_image(
     entity_path: str,
     image: Tensor,
@@ -111,9 +111,6 @@ def log_depth_image(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     image = _to_numpy(image)
 
     # TODO(#635): Remove when issue with displaying f64 depth images is fixed.
@@ -142,6 +139,7 @@ def log_depth_image(
         )
 
 
+@log_decorator
 def log_segmentation_image(
     entity_path: str,
     image: npt.ArrayLike,
@@ -174,9 +172,6 @@ def log_segmentation_image(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     image = np.array(image, copy=False)
     if image.dtype not in (np.dtype("uint8"), np.dtype("uint16")):
         image = np.require(image, np.uint16)

rerun_py/rerun_sdk/rerun/log/lines.py

@@ -11,6 +11,7 @@
 from rerun.components.radius import RadiusArray
 from rerun.log import _normalize_colors, _normalize_radii
 from rerun.log.extension_components import _add_extension_components
+from rerun.log.log_decorator import log_decorator
 
 __all__ = [
     "log_path",
@@ -29,11 +30,10 @@ def log_path(
     ext: Optional[Dict[str, Any]] = None,
     timeless: bool = False,
 ) -> None:
-    if not bindings.is_enabled():
-        return
     log_line_strip(entity_path, positions, stroke_width=stroke_width, color=color, ext=ext, timeless=timeless)
 
 
+@log_decorator
 def log_line_strip(
     entity_path: str,
     positions: Optional[npt.ArrayLike],
@@ -73,9 +73,6 @@ def log_line_strip(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     if positions is not None:
         positions = np.require(positions, dtype="float32")
 
@@ -111,6 +108,7 @@ def log_line_strip(
         bindings.log_arrow_msg(entity_path, components=instanced, timeless=timeless)
 
 
+@log_decorator
 def log_line_segments(
     entity_path: str,
     positions: npt.ArrayLike,
@@ -149,9 +147,6 @@ def log_line_segments(
 
     """
 
-    if not bindings.is_enabled():
-        return
-
     if positions is None:
         positions = np.require([], dtype="float32")
     positions = np.require(positions, dtype="float32")