testing/docs: add a section to "tox.ini" that includes doctests in testing

              add doctests to some modules

Author: Carl

src/humanize/filesize.py

@@ -15,7 +15,20 @@ def naturalsize(value, binary=False, gnu=False, format="%.1f"):
     By default, decimal suffixes (kB, MB) are used.
 
     Non-GNU modes are compatible with jinja2's `filesizeformat` filter.
+    Examples:
+        ```pycon
+        >>> naturalsize(3000000)
+        '3.0 MB'
+        >>> naturalsize(300, False, True)
+        '300B'
+        >>> naturalsize(3000, False, True)
+        '2.9K'
+        >>> naturalsize(3000, False, True, "%.3f")
+        '2.930K'
+        >>> naturalsize(3000, True)
+        '2.9 KiB'
 
+        ```
     Args:
         value (int, float, str): Integer to convert.
         binary (bool): If `True`, uses binary suffixes (KiB, MiB) with base

src/humanize/number.py

@@ -17,6 +17,28 @@ def ordinal(value):
     anything `int()` will turn into an integer. Anything other value will have nothing
     done to it.
 
+    Examples:
+        ```pycon
+        >>> ordinal(1)
+        '1st'
+        >>> ordinal(1002)
+        '1002nd'
+        >>> ordinal(103)
+        '103rd'
+        >>> ordinal(4)
+        '4th'
+        >>> ordinal(12)
+        '12th'
+        >>> ordinal(101)
+        '101st'
+        >>> ordinal(111)
+        '111th'
+        >>> ordinal('something else')
+        'something else'
+        >>> ordinal(None) is None
+        True
+
+        ```
     Args:
         value (int, str, float): Integer to convert.
 
@@ -49,7 +71,24 @@ def intcomma(value, ndigits=None):
 
     For example, 3000 becomes "3,000" and 45000 becomes "45,000". To maintain some
     compatibility with Django's `intcomma`, this function also accepts floats.
+    Examples:
+        ``pycon
+        >>> intcomma(100)
+        '100'
+        >>> intcomma("1000")
+        '1,000'
+        >>> intcomma(1_000_000)
+        '1,000,000'
+        >>> intcomma(1_234_567.25)
+        '1,234,567.25'
+        >>> intcomma(1234.5454545, 2)
+        '1,234.55'
+        >>> intcomma(14308.40, 1)
+        '14,308.4'
+        >>> intcomma(None) is None
+        True
 
+        ```
     Args:
         value (int, float, str): Integer or float to convert.
         ndigits (int, None): Digits of precision for rounding after the decimal point.
@@ -99,7 +138,22 @@ def intword(value, format="%.1f"):
     Works best for numbers over 1 million. For example, 1_000_000 becomes "1.0 million",
     1200000 becomes "1.2 million" and "1_200_000_000" becomes "1.2 billion". Supports up
     to decillion (33 digits) and googol (100 digits).
+    Examples:
+        ```pycon
+        >>> intword("100")
+        '100'
+        >>> intword("1000000")
+        '1.0 million'
+        >>> intword(1_200_000_000)
+        '1.2 billion'
+        >>> intword(8100000000000000000000000000000000)
+        '8.1 decillion'
+        >>> intword(None) is None
+        True
+        >>> intword("1234000", "%0.3f")
+        '1.234 million'
 
+        ```
     Args:
         value (int, float, str): Integer to convert.
         format (str): To change the number of decimal or general format of the number
@@ -132,7 +186,22 @@ def apnumber(value):
 
     Args:
         value (int, float, str): Integer to convert.
+      Examples:
+        ```pycon
+        >>> apnumber(0)
+        'zero'
+        >>> apnumber(5)
+        'five'
+        >>> apnumber(10)
+        '10'
+        >>> apnumber("7")
+        'seven'
+        >>> apnumber("foo")
+        'foo'
+        >>> apnumber(None) is None
+        True
 
+        ```
     Returns:
         str: For numbers 0-9, the number spelled out. Otherwise, the number. This always
         returns a string unless the value was not `int`-able, unlike the Django filter.
@@ -174,6 +243,7 @@ def fractional(value):
 
     Examples:
         ```pycon
+
         >>> fractional(0.3)
         '3/10'
         >>> fractional(1.3)
@@ -182,6 +252,11 @@ def fractional(value):
         '1/3'
         >>> fractional(1)
         '1'
+        >>> fractional("ten")
+        'ten'
+        >>> fractional(None) is None
+        True
+
         ```
     Args:
         value (int, float, str): Integer to convert.
@@ -216,6 +291,19 @@ def scientific(value, precision=2):
         '3.00 x 10⁻¹'
         >>> scientific(int(500))
         '5.00 x 10²'
+        >>> scientific(-1000)
+        '1.00 x 10⁻³'
+        >>> scientific(1000, 1)
+        '1.0 x 10³'
+        >>> scientific(1000, 3)
+        '1.000 x 10³'
+        >>> scientific("99")
+        '9.90 x 10¹'
+        >>> scientific("foo")
+        'foo'
+        >>> scientific(None) is None
+        True
+
         ```
 
     Args:

src/humanize/time.py

@@ -213,6 +213,10 @@ def naturalday(value, format="%b %d"):
     For date values that are tomorrow, today or yesterday compared to
     present day return representing string. Otherwise, return a string
     formatted according to `format`.
+
+    Examples:
+
+
     """
     try:
         value = dt.date(value.year, value.month, value.day)
@@ -368,6 +372,7 @@ def precisedelta(value, minimum_unit="seconds", suppress=(), format="%0.2f"):
     >>> delta = dt.timedelta(seconds=3633, days=2, microseconds=123000)
     >>> precisedelta(delta)
     '2 days, 1 hour and 33.12 seconds'
+
     ```
 
     A custom `format` can be specified to control how the fractional part
@@ -376,6 +381,7 @@ def precisedelta(value, minimum_unit="seconds", suppress=(), format="%0.2f"):
     ```pycon
     >>> precisedelta(delta, format="%0.4f")
     '2 days, 1 hour and 33.1230 seconds'
+
     ```
 
     Instead, the `minimum_unit` can be changed to have a better resolution;
@@ -387,6 +393,7 @@ def precisedelta(value, minimum_unit="seconds", suppress=(), format="%0.2f"):
     ```pycon
     >>> precisedelta(delta, minimum_unit="microseconds")
     '2 days, 1 hour, 33 seconds and 123 milliseconds'
+
     ```
 
     If desired, some units can be suppressed: you will not see them represented and the
@@ -395,6 +402,7 @@ def precisedelta(value, minimum_unit="seconds", suppress=(), format="%0.2f"):
     ```pycon
     >>> precisedelta(delta, suppress=['days'])
     '49 hours and 33.12 seconds'
+
     ```
 
     Note that microseconds precision is lost if the seconds and all
@@ -404,6 +412,7 @@ def precisedelta(value, minimum_unit="seconds", suppress=(), format="%0.2f"):
     >>> delta = dt.timedelta(seconds=90, microseconds=100)
     >>> precisedelta(delta, suppress=['seconds', 'milliseconds', 'microseconds'])
     '1.50 minutes'
+
     ```
     """
     date, delta = date_and_delta(value)

tox.ini

@@ -17,3 +17,6 @@ deps = pre-commit
 commands = pre-commit run --all-files --show-diff-on-failure
 skip_install = true
 passenv = PRE_COMMIT_COLOR
+
+[pytest]
+addopts = --doctest-modules