refactor: consistent printline() across pose and quaternion classes

spatialmath/base/__init__.py

@@ -221,6 +221,7 @@
     "tr2jac2",
     "trinterp2",
     "trprint2",
+    "tr2str2",
     "trplot2",
     "tranimate2",
     "xyt2tr",
@@ -264,6 +265,7 @@
     "exp2jac",
     "rot2jac",
     "trprint",
+    "tr2str",
     "trplot",
     "tranimate",
     "tr2x",

spatialmath/base/quaternions.py

@@ -1156,10 +1156,10 @@ def qprint(
     q: Union[ArrayLike4, ArrayLike4],
     delim: Optional[Tuple[str, str]] = ("<", ">"),
     fmt: Optional[str] = "{: .4f}",
-    file: Optional[TextIO] = sys.stdout,
-) -> None:
+    file: Optional[TextIO] = False,
+) -> str:
     """
-    Format a quaternion to a file
+    Compact single-line display of a quaternion
 
     :arg q: unit-quaternion
     :type q: array_like(4)
@@ -1187,15 +1187,26 @@ def qprint(
         >>> q = qrand()   # a unit quaternion
         >>> qprint(q, delim=('<<', '>>'))
 
+    .. deprecated:: 1.1.15
+        ``file=None`` to get the string back without printing is
+        deprecated - call :func:`~q2str` directly instead.
+
     :seealso: :meth:`q2str`
     """
     q = smb.getvector(q, 4)
+    s = q2str(q, delim=delim, fmt=fmt)
     if file is None:
         warnings.warn(
             "Usage: qprint(..., file=None) -> str is deprecated, use q2str() instead",
             DeprecationWarning,
         )
-    print(q2str(q, delim=delim, fmt=fmt), file=file)
+    else:
+        # file=False (the default) resolves to None here so print() looks
+        # up the *current* sys.stdout at call time, not whatever it was
+        # when this function was defined - that's what makes
+        # contextlib.redirect_stdout() work.
+        print(s, file=None if file is False else file)
+    return s
 
 
 if __name__ == "__main__":  # pragma: no cover

spatialmath/base/transforms2d.py

@@ -17,6 +17,7 @@
 import sys
 import math
 import numpy as np
+import warnings
 
 try:
     import matplotlib.pyplot as plt
@@ -959,22 +960,19 @@ def trinterp2(start, end, s, shortest: bool = True):
         raise ValueError("Argument must be SO(2) or SE(2)")
 
 
-def trprint2(
+def tr2str2(
     T: Union[SO2Array, SE2Array],
     label: str = "",
-    file: TextIO = sys.stdout,
     fmt: str = "{:.3g}",
     unit: str = "deg",
 ) -> str:
     """
-    Compact display of SE(2) or SO(2) matrices
+    Convert SO(2) or SE(3) matrices to compact single-line string
 
     :param T: matrix to format
     :type T: ndarray(3,3) or ndarray(2,2)
     :param label: text label to put at start of line
     :type label: str
-    :param file: file to write formatted string to
-    :type file: file object
     :param fmt: conversion format for each number
     :type fmt: str
     :param unit: angular units: 'rad' [default], or 'deg'
@@ -985,12 +983,12 @@ def trprint2(
     The matrix is formatted and written to ``file`` and the
     string is returned.  To suppress writing to a file, set ``file=None``.
 
-    - ``trprint2(R)`` displays the SO(2) rotation matrix in a compact
+    - ``tr2str2(R)`` displays the SO(2) rotation matrix in a compact
       single-line format and returns the string::
 
         [LABEL:] θ UNIT
 
-    - ``trprint2(T)`` displays the SE(2) homogoneous transform in a compact
+    - ``tr2str2(T)`` displays the SE(2) homogoneous transform in a compact
       single-line format and returns the string::
 
         [LABEL:] [t=X, Y;] θ UNIT
@@ -999,17 +997,18 @@ def trprint2(
 
         >>> from spatialmath.base import *
         >>> T = transl2(1,2) @ trot2(0.3)
-        >>> trprint2(T, file=None, label='T')
-        >>> trprint2(T, file=None, label='T', fmt='{:8.4g}')
-
+        >>> tr2str2(T, label='T')
+        >>> tr2str2(T, label='T', fmt='{:8.4g}')
 
     .. note::
 
         - Default formatting is for compact display of data
         - For tabular data set ``fmt`` to a fixed width format such as
           ``fmt='{:.3g}'``
 
-    :seealso: trprint
+    .. versionadded:: 1.1.15
+
+    :seealso: :func:`~tr2str`
     """
 
     s = ""
@@ -1028,8 +1027,6 @@ def trprint2(
     else:
         s += " {} rad".format(_vec2s(fmt, [angle]))
 
-    if file:
-        print(s, file=file)
     return s
 
 
@@ -1052,6 +1049,76 @@ def _vec2s(fmt: str, v: ArrayLikePure, tol: float = 20) -> str:
     return ", ".join([fmt.format(x) for x in v])
 
 
+def trprint2(
+    T: Union[SO2Array, SE2Array],
+    label: str = "",
+    file: TextIO = False,
+    **kwargs,
+) -> str:
+    """
+    Compact single-line display of SE(2) or SO(2) matrices
+
+    :param T: matrix to format
+    :type T: ndarray(3,3) or ndarray(2,2)
+    :param label: text label to put at start of line
+    :type label: str
+    :param file: file to write formatted string to [default is stdout]
+    :type file: file object
+    :param fmt: conversion format for each number
+    :type fmt: str
+    :param unit: angular units: 'rad' [default], or 'deg'
+    :type unit: str
+    :return: formatted string
+    :rtype: str
+
+    The matrix is formatted and written to ``file`` and the
+    string is returned.  To suppress writing to a file, set ``file=None``.
+
+    - ``trprint2(R)`` displays the SO(2) rotation matrix in a compact
+      single-line format and returns the string::
+
+        [LABEL:] θ UNIT
+
+    - ``trprint2(T)`` displays the SE(2) homogoneous transform in a compact
+      single-line format and returns the string::
+
+        [LABEL:] [t=X, Y;] θ UNIT
+
+    .. runblock:: pycon
+
+        >>> from spatialmath.base import *
+        >>> T = transl2(1,2) @ trot2(0.3)
+        >>> trprint2(T, label='T')
+        >>> trprint2(T, label='T', fmt='{:8.4g}')
+
+
+    .. note::
+
+        - Default formatting is for compact display of data
+        - For tabular data set ``fmt`` to a fixed width format such as
+          ``fmt='{:.3g}'``
+
+    .. deprecated:: 1.1.15
+        ``file=None`` to get the string back without printing is
+        deprecated - call :func:`~tr2str2` directly instead.
+
+    :seealso: :func:`~tr2str2` :func:`~trprint`
+    """
+    s = tr2str2(T, label=label, **kwargs)
+    if file is None:
+        warnings.warn(
+            "Usage: trprint2(..., file=None) -> str is deprecated, use tr2str2() instead",
+            DeprecationWarning,
+        )
+    else:
+        # file=False (the default) resolves to None here so print() looks
+        # up the *current* sys.stdout at call time, not whatever it was
+        # when this function was defined - that's what makes
+        # contextlib.redirect_stdout() work.
+        print(s, file=None if file is False else file)
+    return s
+
+
 def points2tr2(p1: NDArray, p2: NDArray) -> SE2Array:
     """
     SE(2) transform from corresponding points