TST, fix for issue pandas-dev#17978.

Incorporate review comments.

Author: sushobhit27

doc/source/contributing.rst

@@ -777,45 +777,12 @@ Tests that we have ``parametrized`` are now accessible via the test name, for ex
 
 Using ``hypothesis``
 ~~~~~~~~~~~~~~~~~~~~
-With the transition to pytest, things have become easier for testing by having reduced boilerplate for test cases and also by utilizing pytest's features like parametizing, skipping and marking test cases.
+With the usage of pytest, things have become easier for testing by having reduced boilerplate for test cases and also by utilizing pytest's features like parametizing, skipping and marking test cases.
 
 However, one has to still come up with input data examples which can be tested against the functionality. There is always a possibility to skip testing an example which could have failed the test case.
 
 Hypothesis is a python package which helps in overcoming this issue by generating the input data based on some set of specifications provided by the user.
-e.g suppose we have to test python's sum function for a list of int.
-
-Here is a sample test case using pytest:
-
-.. code-block:: python
-
-    import pytest
-
-    @pytest.mark.parametrize('seq', [
-        [0, 0, 0],
-        [1, 2, 3, 4],
-        [-3, 5, -8, 23],
-        [12345678, 9876543, 567894321]
-    ])
-    def test_sum_using_pytest(seq):
-        total = 0
-        for item in seq:
-            total += item
-        assert sum(seq) == total
-
-output of test cases:
-
-.. code-block:: shell
-
-    collecting ... collected 4 items
-    pytest_example.py::test_sum_using_pytest[seq0] PASSED                    [ 25%]
-    pytest_example.py::test_sum_using_pytest[seq1] PASSED                    [ 50%]
-    pytest_example.py::test_sum_using_pytest[seq2] PASSED                    [ 75%]
-    pytest_example.py::test_sum_using_pytest[seq3] PASSED                    [100%]
-
-    ========================== 4 passed in 0.06 seconds ===========================
-
-
-Compare it with below example for the same test case using hypothesis.
+e.g consider the test case for testing python's sum function for a list of int using hypothesis.
 
 .. code-block:: python
 
@@ -840,8 +807,7 @@ output of test cases:
 
     ========================== 1 passed in 0.33 seconds ===========================
 
-The main difference in above example is use of a decorator "@given(st.lists(st.integers()))" which if applied to test case function, generates some random list of int, which is then assigned to parameter of test case.
-Above example clearly helps in adding more coverage for our test functions.
+In above example by applying a decorator "@given(st.lists(st.integers()))" to the unit test function, we have directed hypothesis to generate some random list of int as input for the test function, which eventually helps in adding more coverage for our test functions by generating random input data.
 
 For more information about hypothesis or in general about property based testing, check below links:
 

pandas/util/_hypothesis.py

@@ -1,3 +1,11 @@
+"""
+This module houses utility functions to generate hypothesis strategies which
+ can be used to generate random input test data for various test cases.
+It is for internal use by different test case files like pandas/test/test*.py
+ files only and should not be used beyond this purpose.
+For more information on hypothesis, check
+(http://hypothesis.readthedocs.io/en/latest/).
+"""
 import string
 from hypothesis import (given,
                         settings,
@@ -7,6 +15,62 @@
 
 
 def get_elements(elem_type):
+    """
+    Helper function to return hypothesis strategy whose elements depends on
+    the input data-type.
+    Currently only four types are supported namely, bool, int, float and str.
+
+    Parameters
+    ----------
+    elem_type: type
+        type of the elements for the strategy.
+
+    Returns
+    -------
+    hypothesis strategy.
+
+    Examples
+    --------
+    >>> strat = get_elements(str)
+    >>> strat.example()
+    'KWAo'
+
+    >>> strat.example()
+    'OfAlBH'
+
+    >>> strat = get_elements(int)
+    >>> strat.example()
+    31911
+
+    >>> strat.example()
+    25288
+
+    >>> strat = get_elements(float)
+    >>> strat.example()
+    nan
+
+    >>> strat.example()
+    inf
+
+    >>> strat.example()
+    -2.2250738585072014e-308
+
+    >>> strat.example()
+    0.5
+
+    >>> strat.example()
+    1.7976931348623157e+308
+
+    >>> strat = get_elements(bool)
+    >>> strat.example()
+    True
+
+    >>> strat.example()
+    True
+
+    >>> strat.example()
+    False
+    """
     strategy = st.nothing()
     if elem_type == bool:
         strategy = st.booleans()
@@ -49,28 +113,32 @@ def get_seq(draw, types, mixed=False, min_size=None, max_size=None,
 
     Examples
     --------
-    seq_strategy = get_seq((int, str, bool),
-                            mixed=True, min_size=1, max_size=5)
-    seq_strategy.example()
-    Out[12]: ['lkYMSn', -2501, 35, 'J']
-    seq_strategy.example()
-    Out[13]: [True]
-    seq_strategy.example()
-    Out[14]: ['dRWgQYrBrW', True, False, 'gmsujJVDBM', 'Z']
-
-    seq_strategy = get_seq((int, bool),
-                            mixed=False,
-                            min_size=1,
-                            max_size=5,
-                            transform_func=lambda seq: [str(x) for x in seq])
-    seq_strategy.example()
-    Out[19]: ['-1892']
-    seq_strategy.example()
-    Out[20]: ['22', '66', '14785', '-26312', '32']
-    seq_strategy.example()
-    Out[21]: ['22890', '-15537', '96']
+    >>> seq_strategy = get_seq((int, str, bool), mixed=True, min_size=1, max_size=5)
+
+    >>> seq_strategy.example()
+    ['lkYMSn', -2501, 35, 'J']
+
+    >>> seq_strategy.example()
+    [True]
+
+    >>> seq_strategy.example()
+    ['dRWgQYrBrW', True, False, 'gmsujJVDBM', 'Z']
+
+    >>> seq_strategy = get_seq((int, bool),
+...                             mixed=False,
+...                             min_size=1,
+...                             max_size=5,
+...                             transform_func=lambda seq: [str(x) for x in seq])
+
+    >>> seq_strategy.example()
+    ['9552', '124', '-24024']
+
+    >>> seq_strategy.example()
+    ['-1892']
+
+    >>> seq_strategy.example()
+    ['22', '66', '14785', '-26312', '32']
     """
-    strategy = st.nothing()
     if min_size is None:
         min_size = draw(st.integers(min_value=0, max_value=100))
 
@@ -85,7 +153,6 @@ def get_seq(draw, types, mixed=False, min_size=None, max_size=None,
         elem_strategies.append(get_elements(elem_type))
         if not mixed:
             break
-
     if transform_func:
         strategy = draw(st.lists(st.one_of(elem_strategies),
                                  min_size=min_size,