create utils.py and the to_qfont() function

docs/_api/msl.qt.utils.rst

@@ -0,0 +1,7 @@
+msl.qt.utils module
+===================
+
+.. automodule:: msl.qt.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api.rst

@@ -18,6 +18,7 @@ which has the following modules
    msl.qt.io
    msl.qt.prompt
    msl.qt.threading
+   msl.qt.utils
 
 the following custom :class:`~QtWidgets.QWidget`\'s
 
@@ -58,6 +59,7 @@ Package Structure
    msl.qt.prompt <_api/msl.qt.prompt>
    msl.qt.sleep <_api/msl.qt.sleep>
    msl.qt.threading <_api/msl.qt.threading>
+   msl.qt.utils <_api/msl.qt.utils>
    msl.qt.equipment <_api/msl.qt.equipment>
    msl.qt.widgets <_api/msl.qt.widgets>
 

msl/qt/__init__.py

@@ -68,3 +68,4 @@ def application(*args):
     DoubleSpinBox,
     SpinBox,
 )
+from . import utils

msl/qt/prompt.py

@@ -6,7 +6,12 @@
 """
 import traceback
 
-from . import QtWidgets, QtGui, Qt, application
+from . import (
+    QtWidgets,
+    Qt,
+    application,
+)
+from .utils import to_qfont
 
 
 def critical(message, *, title=None, font=None):
@@ -486,7 +491,7 @@ def _input_dialog(*, title=None, message=None, font=None):
     dialog.setWindowTitle(title)
     dialog.setLabelText(message)
     if font:
-        dialog.setFont(_to_qfont(font))
+        dialog.setFont(to_qfont(font))
     return app, dialog
 
 
@@ -496,36 +501,14 @@ def _message_box(*, title=None, message=None, font=None, buttons=None, default=N
     mb.setWindowTitle(title)
     mb.setText(message)
     if font:
-        mb.setFont(_to_qfont(font))
+        mb.setFont(to_qfont(font))
     if buttons:
         mb.setStandardButtons(buttons)
     if default:
         mb.setDefaultButton(default)
     return app, mb
 
 
-def _to_qfont(font):
-    """Convert int/float -> point size, str -> family name, tuple -> (family name, point size) to a QFont."""
-    if isinstance(font, QtGui.QFont):
-        return font
-    elif isinstance(font, int):
-        f = QtGui.QFont()
-        f.setPointSize(font)
-        return f
-    elif isinstance(font, float):
-        f = QtGui.QFont()
-        f.setPointSizeF(font)
-        return f
-    elif isinstance(font, str):
-        return QtGui.QFont(font)
-    elif isinstance(font, (tuple, list)):
-        if len(font) < 2:
-            raise ValueError('The font must be a (family name, point size) tuple')
-        return QtGui.QFont(font[0], pointSize=int(font[1]))
-    else:
-        raise TypeError('Must specify a QFont object')
-
-
 def _get_file_filters(filters):
     """Make the `filters` value be in the appropriate syntax."""
     def _check_extn(ex):

msl/qt/utils.py

@@ -0,0 +1,41 @@
+"""
+General helper functions.
+"""
+from . import QtGui
+
+
+def to_qfont(font):
+    """Convert the input argument into a :class:`QtGui.QFont` object.
+
+    Parameters
+    ----------
+    font : :class:`int`, :class:`float`, :class:`str` or :class:`tuple`
+        The value to convert to a :class:`QtGui.QFont`.
+
+        * If :class:`int` or :class:`float` then the point size.
+        * If :class:`str` then the font family name.
+        * If :class:`tuple` then (family name, point size).
+
+    Returns
+    -------
+    :class:`QtGui.QFont`
+        The input `value` converted to a :class:`QtGui.QFont` object.
+    """
+    if isinstance(font, QtGui.QFont):
+        return font
+    elif isinstance(font, int):
+        f = QtGui.QFont()
+        f.setPointSize(font)
+        return f
+    elif isinstance(font, float):
+        f = QtGui.QFont()
+        f.setPointSizeF(font)
+        return f
+    elif isinstance(font, str):
+        return QtGui.QFont(font)
+    elif isinstance(font, (tuple, list)):
+        if len(font) < 2:
+            raise ValueError('The font must be a (family name, point size) tuple')
+        return QtGui.QFont(font[0], pointSize=int(font[1]))
+    else:
+        raise TypeError('Must specify a QFont object')

tests/test_utils.py

@@ -0,0 +1,46 @@
+import pytest
+from msl.qt import QtGui, utils
+
+
+def test_to_qfont():
+
+    with pytest.raises(TypeError):
+        utils.to_qfont(None)
+
+    # the tuple/list must have length == 2
+    for obj in [(), [], (1,), [1]]:
+        with pytest.raises(ValueError):
+            utils.to_qfont(obj)
+
+    font = QtGui.QFont()
+    assert utils.to_qfont(font) is font
+
+    font = utils.to_qfont(100)
+    assert font.pointSize() == 100
+
+    font = utils.to_qfont(12.3)
+    assert font.pointSize() == 12
+    assert font.pointSizeF() == 12.3
+
+    font = utils.to_qfont('Papyrus')
+    assert font.family() == 'Papyrus'
+
+    font = utils.to_qfont(('Ariel', 48))
+    assert font.family() == 'Ariel'
+    assert font.pointSize() == 48
+
+    # the second item in the list will be cast to an integer
+    # also test that one can pass in a tuple or a list
+    for obj in [('Comic Sans MS', 36), ['Comic Sans MS', 36.6], ('Comic Sans MS', '36')]:
+        font = utils.to_qfont(obj)
+        assert font.family() == 'Comic Sans MS'
+        assert font.pointSize() == 36
+
+    # the second item in the list cannot be cast to an integer
+    with pytest.raises(ValueError):
+        utils.to_qfont(['Ariel', 'xxx'])
+
+    # the first item in the list must be a string
+    for obj in [1, 23.4, 5j, True, [1]]:
+        with pytest.raises(TypeError):
+            utils.to_qfont((obj, 12))