singlestoredb 1.16.1__py3-none-any.whl

singlestoredb/docstring/tests/test_parse_from_object.py

@@ -0,0 +1,109 @@
+"""Tests for parse_from_object function and attribute docstrings."""
+from unittest.mock import patch
+
+from singlestoredb.docstring import parse_from_object
+
+# module_attr: int = 1
+# """Description for module_attr"""
+
+
+# def test_from_module_attribute_docstrings() -> None:
+#     """Test the parse of attribute docstrings from a module."""
+#     from . import test_parse_from_object  # pylint: disable=C0415,W0406
+#
+#     docstring = parse_from_object(test_parse_from_object)
+#
+#     assert 'parse_from_object' in docstring.short_description
+#     assert len(docstring.params) == 1
+#     assert docstring.params[0].arg_name == 'module_attr'
+#     assert docstring.params[0].type_name == 'int'
+#     assert docstring.params[0].description == 'Description for module_attr'
+
+
+def test_from_class_attribute_docstrings() -> None:
+    """Test the parse of attribute docstrings from a class."""
+
+    class StandardCase:
+        """Short description
+        Long description
+        """
+
+        attr_one: str
+        """Description for attr_one"""
+        attr_two: bool = False
+        """Description for attr_two"""
+
+    docstring = parse_from_object(StandardCase)
+
+    assert docstring.short_description == 'Short description'
+    assert docstring.long_description == 'Long description'
+    assert docstring.description == 'Short description\nLong description'
+    assert len(docstring.params) == 2
+    assert docstring.params[0].arg_name == 'attr_one'
+    assert docstring.params[0].type_name == 'str'
+    assert docstring.params[0].description == 'Description for attr_one'
+    assert docstring.params[1].arg_name == 'attr_two'
+    assert docstring.params[1].type_name == 'bool'
+    assert docstring.params[1].description == 'Description for attr_two'
+
+
+def test_from_class_attribute_docstrings_without_type() -> None:
+    """Test the parse of untyped attribute docstrings."""
+
+    class WithoutType:  # pylint: disable=missing-class-docstring
+        attr_one = 'value'
+        """Description for attr_one"""
+
+    docstring = parse_from_object(WithoutType)
+
+    assert docstring.short_description is None
+    assert docstring.long_description is None
+    assert docstring.description is None
+    assert len(docstring.params) == 1
+    assert docstring.params[0].arg_name == 'attr_one'
+    assert docstring.params[0].type_name is None
+    assert docstring.params[0].description == 'Description for attr_one'
+
+
+def test_from_class_without_source() -> None:
+    """Test the parse of class when source is unavailable."""
+
+    class WithoutSource:
+        """Short description"""
+
+        attr_one: str
+        """Description for attr_one"""
+
+    with patch(
+        'inspect.getsource', side_effect=OSError('could not get source code'),
+    ):
+        docstring = parse_from_object(WithoutSource)
+
+    assert docstring.short_description == 'Short description'
+    assert docstring.long_description is None
+    assert docstring.description == 'Short description'
+    assert len(docstring.params) == 0
+
+
+def test_from_function() -> None:
+    """Test the parse of a function docstring."""
+
+    def a_function(param1: str, param2: int = 2) -> str:
+        """Short description
+        Args:
+            param1: Description for param1
+            param2: Description for param2
+        """
+        return f'{param1} {param2}'
+
+    docstring = parse_from_object(a_function)
+
+    assert docstring.short_description == 'Short description'
+    assert docstring.description == 'Short description'
+    assert len(docstring.params) == 2
+    assert docstring.params[0].arg_name == 'param1'
+    assert docstring.params[0].type_name is None
+    assert docstring.params[0].description == 'Description for param1'
+    assert docstring.params[1].arg_name == 'param2'
+    assert docstring.params[1].type_name is None
+    assert docstring.params[1].description == 'Description for param2'

singlestoredb/docstring/tests/test_parser.py

@@ -0,0 +1,248 @@
+"""Tests for generic docstring routines."""
+import typing as T
+
+import pytest
+
+from singlestoredb.docstring.common import DocstringStyle
+from singlestoredb.docstring.common import ParseError
+from singlestoredb.docstring.parser import parse
+
+
+@pytest.mark.parametrize(
+    'source, expected',
+    [
+        pytest.param(None, None, id='No __doc__'),
+        ('', None),
+        ('\n', None),
+        ('Short description', 'Short description'),
+        ('\nShort description\n', 'Short description'),
+        ('\n   Short description\n', 'Short description'),
+    ],
+)
+def test_short_description(
+    source: T.Optional[str], expected: T.Optional[str],
+) -> None:
+    """Test parsing short description."""
+    docstring = parse(source)
+    assert docstring.short_description == expected
+    assert docstring.description == expected
+    assert docstring.long_description is None
+    assert not docstring.meta
+
+
+def test_rest() -> None:
+    """Test ReST-style parser autodetection."""
+    docstring = parse(
+        """
+        Short description
+
+        Long description
+
+        Causing people to indent:
+
+            A lot sometimes
+
+        :param spam: spam desc
+        :param int bla: bla desc
+        :param str yay:
+        :raises ValueError: exc desc
+        :returns tuple: ret desc
+        """,
+    )
+
+    assert docstring.style == DocstringStyle.REST
+    assert docstring.short_description == 'Short description'
+    assert docstring.long_description == (
+        'Long description\n\n'
+        'Causing people to indent:\n\n'
+        '    A lot sometimes'
+    )
+    assert docstring.description == (
+        'Short description\n\n'
+        'Long description\n\n'
+        'Causing people to indent:\n\n'
+        '    A lot sometimes'
+    )
+    assert len(docstring.params) == 3
+    assert docstring.params[0].arg_name == 'spam'
+    assert docstring.params[0].type_name is None
+    assert docstring.params[0].description == 'spam desc'
+    assert docstring.params[1].arg_name == 'bla'
+    assert docstring.params[1].type_name == 'int'
+    assert docstring.params[1].description == 'bla desc'
+    assert docstring.params[2].arg_name == 'yay'
+    assert docstring.params[2].type_name == 'str'
+    assert docstring.params[2].description == ''
+    assert len(docstring.raises) == 1
+    assert docstring.raises[0].type_name == 'ValueError'
+    assert docstring.raises[0].description == 'exc desc'
+    assert docstring.returns is not None
+    assert docstring.returns.type_name == 'tuple'
+    assert docstring.returns.description == 'ret desc'
+    assert docstring.many_returns is not None
+    assert len(docstring.many_returns) == 1
+    assert docstring.many_returns[0] == docstring.returns
+
+
+def test_google() -> None:
+    """Test Google-style parser autodetection."""
+    docstring = parse(
+        """Short description
+
+        Long description
+
+        Causing people to indent:
+
+            A lot sometimes
+
+        Args:
+            spam: spam desc
+            bla (int): bla desc
+            yay (str):
+
+        Raises:
+            ValueError: exc desc
+
+        Returns:
+            tuple: ret desc
+        """,
+    )
+
+    assert docstring.style == DocstringStyle.GOOGLE
+    assert docstring.short_description == 'Short description'
+    assert docstring.long_description == (
+        'Long description\n\n'
+        'Causing people to indent:\n\n'
+        '    A lot sometimes'
+    )
+    assert docstring.description == (
+        'Short description\n\n'
+        'Long description\n\n'
+        'Causing people to indent:\n\n'
+        '    A lot sometimes'
+    )
+    assert len(docstring.params) == 3
+    assert docstring.params[0].arg_name == 'spam'
+    assert docstring.params[0].type_name is None
+    assert docstring.params[0].description == 'spam desc'
+    assert docstring.params[1].arg_name == 'bla'
+    assert docstring.params[1].type_name == 'int'
+    assert docstring.params[1].description == 'bla desc'
+    assert docstring.params[2].arg_name == 'yay'
+    assert docstring.params[2].type_name == 'str'
+    assert docstring.params[2].description == ''
+    assert len(docstring.raises) == 1
+    assert docstring.raises[0].type_name == 'ValueError'
+    assert docstring.raises[0].description == 'exc desc'
+    assert docstring.returns is not None
+    assert docstring.returns.type_name == 'tuple'
+    assert docstring.returns.description == 'ret desc'
+    assert docstring.many_returns is not None
+    assert len(docstring.many_returns) == 1
+    assert docstring.many_returns[0] == docstring.returns
+
+
+def test_numpydoc() -> None:
+    """Test numpydoc-style parser autodetection."""
+    docstring = parse(
+        """Short description
+
+        Long description
+
+        Causing people to indent:
+
+            A lot sometimes
+
+        Parameters
+        ----------
+        spam
+            spam desc
+        bla : int
+            bla desc
+        yay : str
+
+        Raises
+        ------
+        ValueError
+            exc desc
+
+        Other Parameters
+        ----------------
+        this_guy : int, optional
+            you know him
+
+        Returns
+        -------
+        tuple
+            ret desc
+
+        See Also
+        --------
+        multiple lines...
+        something else?
+
+        Warnings
+        --------
+        multiple lines...
+        none of this is real!
+        """,
+    )
+
+    assert docstring.style == DocstringStyle.NUMPYDOC
+    assert docstring.short_description == 'Short description'
+    assert docstring.long_description == (
+        'Long description\n\n'
+        'Causing people to indent:\n\n'
+        '    A lot sometimes'
+    )
+    assert docstring.description == (
+        'Short description\n\n'
+        'Long description\n\n'
+        'Causing people to indent:\n\n'
+        '    A lot sometimes'
+    )
+    assert len(docstring.params) == 4
+    assert docstring.params[0].arg_name == 'spam'
+    assert docstring.params[0].type_name is None
+    assert docstring.params[0].description == 'spam desc'
+    assert docstring.params[1].arg_name == 'bla'
+    assert docstring.params[1].type_name == 'int'
+    assert docstring.params[1].description == 'bla desc'
+    assert docstring.params[2].arg_name == 'yay'
+    assert docstring.params[2].type_name == 'str'
+    assert docstring.params[2].description is None
+    assert docstring.params[3].arg_name == 'this_guy'
+    assert docstring.params[3].type_name == 'int'
+    assert docstring.params[3].is_optional
+    assert docstring.params[3].description == 'you know him'
+
+    assert len(docstring.raises) == 1
+    assert docstring.raises[0].type_name == 'ValueError'
+    assert docstring.raises[0].description == 'exc desc'
+    assert docstring.returns is not None
+    assert docstring.returns.type_name == 'tuple'
+    assert docstring.returns.description == 'ret desc'
+    assert docstring.many_returns is not None
+    assert len(docstring.many_returns) == 1
+    assert docstring.many_returns[0] == docstring.returns
+
+
+def test_autodetection_error_detection() -> None:
+    """Test autodection for the case where one of the parsers throws an error
+    and another one succeeds.
+    """
+    source = """
+    Does something useless
+
+    :param 3 + 3 a: a param
+    """
+
+    with pytest.raises(ParseError):
+        # assert that one of the parsers does raise
+        parse(source, DocstringStyle.REST)
+
+    # assert that autodetection still works
+    docstring = parse(source)
+
+    assert docstring
+    assert docstring.style == DocstringStyle.GOOGLE