MAINT: Test and clarify timing precision accessors

quantecon/tests/test_timings.py

@@ -0,0 +1,30 @@
+"""Tests for the public timing precision configuration API."""
+
+import pytest
+
+from quantecon.timings import float_precision, get_default_precision
+
+
+@pytest.fixture(autouse=True)
+def restore_float_precision():
+    """Keep the module-level timing precision isolated between tests."""
+    original_precision = float_precision()
+    yield
+    float_precision(original_precision)
+
+
+def test_float_precision_gets_and_sets_the_default():
+    float_precision(6)
+
+    assert float_precision() == 6
+    assert get_default_precision() == 6
+
+
+@pytest.mark.parametrize("precision", [-1, 1.5, "4"])
+def test_float_precision_rejects_invalid_values(precision):
+    with pytest.raises(ValueError, match="non-negative integer"):
+        float_precision(precision)
+
+
+def test_float_precision_examples_are_not_uncollected_doctests():
+    assert ">>>" not in float_precision.__doc__

quantecon/timings/__init__.py

@@ -4,4 +4,4 @@
 
 from .timings import float_precision, get_default_precision
 
-__all__ = ['float_precision', 'get_default_precision']
+__all__ = ['float_precision', 'get_default_precision']

quantecon/timings/timings.py

@@ -12,50 +12,47 @@
 def float_precision(precision=None):
     """
     Get or set the global float precision for timing outputs.
-    
+
     Parameters
     ----------
     precision : int, optional
-        Number of decimal places to display in timing outputs. 
+        Number of decimal places to display in timing outputs.
         If None, returns the current precision setting.
-        
+
     Returns
     -------
     int
         Current precision value if precision=None, otherwise None.
-        
+
     Examples
     --------
-    Get current precision:
-    >>> import quantecon as qe
-    >>> current = qe.timings.float_precision()
-    >>> print(f"Current precision: {current}")
-
-    Set new precision:
-    >>> qe.timings.float_precision(6)
-    >>> # All subsequent timing outputs will use 6 decimal places
-
-    Reset to default:
-    >>> qe.timings.float_precision(4)
+    To get the current precision, call ``float_precision()`` without an
+    argument. To update it, call ``float_precision(6)``. All subsequent
+    timing outputs then use six decimal places. Call ``float_precision(4)``
+    to restore the default setting.
     """
     global _DEFAULT_FLOAT_PRECISION
-    
+
     if precision is None:
         return _DEFAULT_FLOAT_PRECISION
-    
+
     if not isinstance(precision, int) or precision < 0:
         raise ValueError("precision must be a non-negative integer")
-    
+
     _DEFAULT_FLOAT_PRECISION = precision
 
 
 def get_default_precision():
     """
     Get the current default precision setting.
-
+
+    This is equivalent to calling :func:`float_precision` without an
+    argument. Prefer :func:`float_precision` for new code because it also
+    provides the corresponding setter.
+
     Returns
     -------
     int
         Current default precision for timing outputs.
     """
-    return _DEFAULT_FLOAT_PRECISION
+    return _DEFAULT_FLOAT_PRECISION