singlestoredb 1.16.1__py3-none-any.whl

singlestoredb/docstring/__init__.py

@@ -0,0 +1,33 @@
+"""Parse docstrings as per Sphinx notation."""
+from .common import Docstring
+from .common import DocstringDeprecated
+from .common import DocstringMeta
+from .common import DocstringParam
+from .common import DocstringRaises
+from .common import DocstringReturns
+from .common import DocstringStyle
+from .common import ParseError
+from .common import RenderingStyle
+from .parser import compose
+from .parser import parse
+from .parser import parse_from_object
+from .util import combine_docstrings
+
+Style = DocstringStyle  # backwards compatibility
+
+__all__ = [
+    'parse',
+    'parse_from_object',
+    'combine_docstrings',
+    'compose',
+    'ParseError',
+    'Docstring',
+    'DocstringMeta',
+    'DocstringParam',
+    'DocstringRaises',
+    'DocstringReturns',
+    'DocstringDeprecated',
+    'DocstringStyle',
+    'RenderingStyle',
+    'Style',
+]

singlestoredb/docstring/attrdoc.py

@@ -0,0 +1,126 @@
+"""Attribute docstrings parsing.
+
+.. seealso:: https://peps.python.org/pep-0257/#what-is-a-docstring
+"""
+import ast
+import inspect
+import textwrap
+import typing as T
+from types import ModuleType
+
+from .common import Docstring
+from .common import DocstringParam
+
+
+def ast_get_constant_value(node: ast.AST) -> T.Any:
+    """Return the constant's value if the given node is a constant."""
+    return getattr(node, 'value')
+
+
+def ast_unparse(node: ast.AST) -> T.Optional[str]:
+    """Convert the AST node to source code as a string."""
+    if hasattr(ast, 'unparse'):
+        return ast.unparse(node)
+    # Support simple cases in Python < 3.9
+    if isinstance(node, ast.Constant):
+        return str(ast_get_constant_value(node))
+    if isinstance(node, ast.Name):
+        return node.id
+    return None
+
+
+def ast_is_literal_str(node: ast.AST) -> bool:
+    """Return True if the given node is a literal string."""
+    return (
+        isinstance(node, ast.Expr)
+        and isinstance(node.value, ast.Constant)
+        and isinstance(ast_get_constant_value(node.value), str)
+    )
+
+
+def ast_get_attribute(
+    node: ast.AST,
+) -> T.Optional[T.Tuple[str, T.Optional[str], T.Optional[str]]]:
+    """Return name, type and default if the given node is an attribute."""
+    if isinstance(node, (ast.Assign, ast.AnnAssign)):
+        target = (
+            node.targets[0] if isinstance(node, ast.Assign) else node.target
+        )
+        if isinstance(target, ast.Name):
+            type_str = None
+            if isinstance(node, ast.AnnAssign):
+                type_str = ast_unparse(node.annotation)
+            default = None
+            if node.value:
+                default = ast_unparse(node.value)
+            return target.id, type_str, default
+    return None
+
+
+class AttributeDocstrings(ast.NodeVisitor):
+    """An ast.NodeVisitor that collects attribute docstrings."""
+
+    attr_docs: T.Dict[str, T.Tuple[str, T.Optional[str], T.Optional[str]]] = {}
+    prev_attr = None
+
+    def visit(self, node: T.Any) -> None:
+        if self.prev_attr and ast_is_literal_str(node):
+            attr_name, attr_type, attr_default = self.prev_attr
+            self.attr_docs[attr_name] = (
+                ast_get_constant_value(node.value),
+                attr_type,
+                attr_default,
+            )
+        self.prev_attr = ast_get_attribute(node)
+        if isinstance(node, (ast.ClassDef, ast.Module)):
+            self.generic_visit(node)
+
+    def get_attr_docs(
+        self, component: T.Any,
+    ) -> T.Dict[str, T.Tuple[str, T.Optional[str], T.Optional[str]]]:
+        """Get attribute docstrings from the given component.
+
+        :param component: component to process (class or module)
+        :returns: for each attribute docstring, a tuple with (description,
+            type, default)
+        """
+        self.attr_docs = {}
+        self.prev_attr = None
+        try:
+            source = textwrap.dedent(inspect.getsource(component))
+        except OSError:
+            pass
+        else:
+            tree = ast.parse(source)
+            if inspect.ismodule(component):
+                self.visit(tree)
+            elif isinstance(tree, ast.Module) and isinstance(
+                tree.body[0], ast.ClassDef,
+            ):
+                self.visit(tree.body[0])
+        return self.attr_docs
+
+
+def add_attribute_docstrings(
+    obj: T.Union[type, ModuleType], docstring: Docstring,
+) -> None:
+    """Add attribute docstrings found in the object's source code.
+
+    :param obj: object from which to parse attribute docstrings
+    :param docstring: Docstring object where found attributes are added
+    :returns: list with names of added attributes
+    """
+    params = set(p.arg_name for p in docstring.params)
+    for arg_name, (description, type_name, default) in (
+        AttributeDocstrings().get_attr_docs(obj).items()
+    ):
+        if arg_name not in params:
+            param = DocstringParam(
+                args=['attribute', arg_name],
+                description=description,
+                arg_name=arg_name,
+                type_name=type_name,
+                is_optional=default is not None,
+                default=default,
+            )
+            docstring.meta.append(param)

singlestoredb/docstring/common.py

@@ -0,0 +1,230 @@
+"""Common methods for parsing."""
+import enum
+import typing as T
+
+PARAM_KEYWORDS = {
+    'param',
+    'parameter',
+    'arg',
+    'argument',
+    'attribute',
+    'key',
+    'keyword',
+}
+RAISES_KEYWORDS = {'raises', 'raise', 'except', 'exception'}
+DEPRECATION_KEYWORDS = {'deprecation', 'deprecated'}
+RETURNS_KEYWORDS = {'return', 'returns'}
+YIELDS_KEYWORDS = {'yield', 'yields'}
+EXAMPLES_KEYWORDS = {'example', 'examples'}
+
+
+class ParseError(RuntimeError):
+    """Base class for all parsing related errors."""
+
+
+class DocstringStyle(enum.Enum):
+    """Docstring style."""
+
+    REST = 1
+    GOOGLE = 2
+    NUMPYDOC = 3
+    EPYDOC = 4
+    AUTO = 255
+
+
+class RenderingStyle(enum.Enum):
+    """Rendering style when unparsing parsed docstrings."""
+
+    COMPACT = 1
+    CLEAN = 2
+    EXPANDED = 3
+
+
+class DocstringMeta:
+    """Docstring meta information.
+
+    Symbolizes lines in form of
+
+        :param arg: description
+        :raises ValueError: if something happens
+    """
+
+    def __init__(
+        self, args: T.List[str], description: T.Optional[str],
+    ) -> None:
+        """Initialize self.
+
+        :param args: list of arguments. The exact content of this variable is
+            dependent on the kind of docstring; it's used to distinguish
+            between custom docstring meta information items.
+        :param description: associated docstring description.
+        """
+        self.args = args
+        self.description = description
+
+
+class DocstringParam(DocstringMeta):
+    """DocstringMeta symbolizing :param metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        description: T.Optional[str],
+        arg_name: str,
+        type_name: T.Optional[str],
+        is_optional: T.Optional[bool],
+        default: T.Optional[str],
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.arg_name = arg_name
+        self.type_name = type_name
+        self.is_optional = is_optional
+        self.default = default
+
+
+class DocstringReturns(DocstringMeta):
+    """DocstringMeta symbolizing :returns or :yields metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        description: T.Optional[str],
+        type_name: T.Optional[str],
+        is_generator: bool,
+        return_name: T.Optional[str] = None,
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.type_name = type_name
+        self.is_generator = is_generator
+        self.return_name = return_name
+
+
+class DocstringRaises(DocstringMeta):
+    """DocstringMeta symbolizing :raises metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        description: T.Optional[str],
+        type_name: T.Optional[str],
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.type_name = type_name
+        self.description = description
+
+
+class DocstringDeprecated(DocstringMeta):
+    """DocstringMeta symbolizing deprecation metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        description: T.Optional[str],
+        version: T.Optional[str],
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.version = version
+        self.description = description
+
+
+class DocstringExample(DocstringMeta):
+    """DocstringMeta symbolizing example metadata."""
+
+    def __init__(
+        self,
+        args: T.List[str],
+        snippet: T.Optional[str],
+        description: T.Optional[str],
+        post_snippet: T.Optional[str] = None,
+    ) -> None:
+        """Initialize self."""
+        super().__init__(args, description)
+        self.snippet = snippet
+        self.description = description
+        self.post_snippet = post_snippet
+
+
+class Docstring:
+    """Docstring object representation."""
+
+    def __init__(
+        self,
+        style=None,  # type: T.Optional[DocstringStyle]
+    ) -> None:
+        """Initialize self."""
+        self.short_description = None  # type: T.Optional[str]
+        self.long_description = None  # type: T.Optional[str]
+        self.blank_after_short_description = False
+        self.blank_after_long_description = False
+        self.meta = []  # type: T.List[DocstringMeta]
+        self.style = style  # type: T.Optional[DocstringStyle]
+
+    @property
+    def description(self) -> T.Optional[str]:
+        """Return the full description of the function
+
+        Returns None if the docstring did not include any description
+        """
+        ret = []
+        if self.short_description:
+            ret.append(self.short_description)
+            if self.blank_after_short_description:
+                ret.append('')
+        if self.long_description:
+            ret.append(self.long_description)
+
+        if not ret:
+            return None
+
+        return '\n'.join(ret)
+
+    @property
+    def params(self) -> T.List[DocstringParam]:
+        """Return a list of information on function params."""
+        return [item for item in self.meta if isinstance(item, DocstringParam)]
+
+    @property
+    def raises(self) -> T.List[DocstringRaises]:
+        """Return a list of information on the exceptions that the function
+        may raise.
+        """
+        return [
+            item for item in self.meta if isinstance(item, DocstringRaises)
+        ]
+
+    @property
+    def returns(self) -> T.Optional[DocstringReturns]:
+        """Return a single information on function return.
+
+        Takes the first return information.
+        """
+        for item in self.meta:
+            if isinstance(item, DocstringReturns):
+                return item
+        return None
+
+    @property
+    def many_returns(self) -> T.List[DocstringReturns]:
+        """Return a list of information on function return."""
+        return [
+            item for item in self.meta if isinstance(item, DocstringReturns)
+        ]
+
+    @property
+    def deprecation(self) -> T.Optional[DocstringDeprecated]:
+        """Return a single information on function deprecation notes."""
+        for item in self.meta:
+            if isinstance(item, DocstringDeprecated):
+                return item
+        return None
+
+    @property
+    def examples(self) -> T.List[DocstringExample]:
+        """Return a list of information on function examples."""
+        return [
+            item for item in self.meta if isinstance(item, DocstringExample)
+        ]

singlestoredb/docstring/epydoc.py

@@ -0,0 +1,267 @@
+"""Epyoc-style docstring parsing.
+
+.. seealso:: http://epydoc.sourceforge.net/manual-fields.html
+"""
+import inspect
+import re
+import typing as T
+
+from .common import Docstring
+from .common import DocstringMeta
+from .common import DocstringParam
+from .common import DocstringRaises
+from .common import DocstringReturns
+from .common import DocstringStyle
+from .common import ParseError
+from .common import RenderingStyle
+
+
+def _clean_str(string: str) -> T.Optional[str]:
+    string = string.strip()
+    if len(string) > 0:
+        return string
+    return None
+
+
+def parse(text: T.Optional[str]) -> Docstring:
+    """Parse the epydoc-style docstring into its components.
+
+    :returns: parsed docstring
+    """
+    ret = Docstring(style=DocstringStyle.EPYDOC)
+    if not text:
+        return ret
+
+    text = inspect.cleandoc(text)
+    match = re.search('^@', text, flags=re.M)
+    if match:
+        desc_chunk = text[:match.start()]
+        meta_chunk = text[match.start():]
+    else:
+        desc_chunk = text
+        meta_chunk = ''
+
+    parts = desc_chunk.split('\n', 1)
+    ret.short_description = parts[0] or None
+    if len(parts) > 1:
+        long_desc_chunk = parts[1] or ''
+        ret.blank_after_short_description = long_desc_chunk.startswith('\n')
+        ret.blank_after_long_description = long_desc_chunk.endswith('\n\n')
+        ret.long_description = long_desc_chunk.strip() or None
+
+    param_pattern = re.compile(
+        r'(param|keyword|type)(\s+[_A-z][_A-z0-9]*\??):',
+    )
+    raise_pattern = re.compile(r'(raise)(\s+[_A-z][_A-z0-9]*\??)?:')
+    return_pattern = re.compile(r'(return|rtype|yield|ytype):')
+    meta_pattern = re.compile(
+        r'([_A-z][_A-z0-9]+)((\s+[_A-z][_A-z0-9]*\??)*):',
+    )
+
+    # tokenize
+    stream: T.List[T.Tuple[str, str, T.List[str], str]] = []
+    for match in re.finditer(
+        r'(^@.*?)(?=^@|\Z)', meta_chunk, flags=re.S | re.M,
+    ):
+        chunk = match.group(0)
+        if not chunk:
+            continue
+
+        param_match = re.search(param_pattern, chunk)
+        raise_match = re.search(raise_pattern, chunk)
+        return_match = re.search(return_pattern, chunk)
+        meta_match = re.search(meta_pattern, chunk)
+
+        match = param_match or raise_match or return_match or meta_match
+        if not match:
+            raise ParseError(f'Error parsing meta information near "{chunk}".')
+
+        desc_chunk = chunk[match.end():]
+        if param_match:
+            base = 'param'
+            key = match.group(1)
+            args = [match.group(2).strip()]
+        elif raise_match:
+            base = 'raise'
+            key = match.group(1)
+            args = [] if match.group(2) is None else [match.group(2).strip()]
+        elif return_match:
+            base = 'return'
+            key = match.group(1)
+            args = []
+        else:
+            base = 'meta'
+            key = match.group(1)
+            token = _clean_str(match.group(2).strip())
+            args = [] if token is None else re.split(r'\s+', token)
+
+            # Make sure we didn't match some existing keyword in an incorrect
+            # way here:
+            if key in [
+                'param',
+                'keyword',
+                'type',
+                'return',
+                'rtype',
+                'yield',
+                'ytype',
+            ]:
+                raise ParseError(
+                    f'Error parsing meta information near "{chunk}".',
+                )
+
+        desc = desc_chunk.strip()
+        if '\n' in desc:
+            first_line, rest = desc.split('\n', 1)
+            desc = first_line + '\n' + inspect.cleandoc(rest)
+        stream.append((base, key, args, desc))
+
+    # Combine type_name, arg_name, and description information
+    params: T.Dict[str, T.Dict[str, T.Any]] = {}
+    for base, key, args, desc in stream:
+        if base not in ['param', 'return']:
+            continue  # nothing to do
+
+        (arg_name,) = args or ('return',)
+        info = params.setdefault(arg_name, {})
+        info_key = 'type_name' if 'type' in key else 'description'
+        info[info_key] = desc
+
+        if base == 'return':
+            is_generator = key in {'ytype', 'yield'}
+            if info.setdefault('is_generator', is_generator) != is_generator:
+                raise ParseError(
+                    f'Error parsing meta information for "{arg_name}".',
+                )
+
+    meta_item: T.Union[DocstringParam, DocstringReturns, DocstringRaises, DocstringMeta]
+    is_done: T.Dict[str, bool] = {}
+    for base, key, args, desc in stream:
+        if base == 'param' and not is_done.get(args[0], False):
+            (arg_name,) = args
+            info = params[arg_name]
+            type_name = info.get('type_name')
+
+            if type_name and type_name.endswith('?'):
+                is_optional = True
+                type_name = type_name[:-1]
+            else:
+                is_optional = False
+
+            match = re.match(r'.*defaults to (.+)', desc, flags=re.DOTALL)
+            default = match.group(1).rstrip('.') if match else None
+
+            meta_item = DocstringParam(
+                args=[key, arg_name],
+                description=info.get('description'),
+                arg_name=arg_name,
+                type_name=type_name,
+                is_optional=is_optional,
+                default=default,
+            )
+            is_done[arg_name] = True
+        elif base == 'return' and not is_done.get('return', False):
+            info = params['return']
+            meta_item = DocstringReturns(
+                args=[key],
+                description=info.get('description'),
+                type_name=info.get('type_name'),
+                is_generator=info.get('is_generator', False),
+            )
+            is_done['return'] = True
+        elif base == 'raise':
+            (type_name,) = args or (None,)
+            meta_item = DocstringRaises(
+                args=[key] + args,
+                description=desc,
+                type_name=type_name,
+            )
+        elif base == 'meta':
+            meta_item = DocstringMeta(
+                args=[key] + args,
+                description=desc,
+            )
+        else:
+            (key, *_) = args or ('return',)
+            assert is_done.get(key, False)
+            continue  # don't append
+
+        ret.meta.append(meta_item)
+
+    return ret
+
+
+def compose(
+    docstring: Docstring,
+    rendering_style: RenderingStyle = RenderingStyle.COMPACT,
+    indent: str = '    ',
+) -> str:
+    """Render a parsed docstring into docstring text.
+
+    :param docstring: parsed docstring representation
+    :param rendering_style: the style to render docstrings
+    :param indent: the characters used as indentation in the docstring string
+    :returns: docstring text
+    """
+
+    def process_desc(desc: T.Optional[str], is_type: bool) -> str:
+        if not desc:
+            return ''
+
+        if rendering_style == RenderingStyle.EXPANDED or (
+            rendering_style == RenderingStyle.CLEAN and not is_type
+        ):
+            (first, *rest) = desc.splitlines()
+            return '\n'.join(
+                ['\n' + indent + first] + [indent + line for line in rest],
+            )
+
+        (first, *rest) = desc.splitlines()
+        return '\n'.join([' ' + first] + [indent + line for line in rest])
+
+    parts: T.List[str] = []
+    if docstring.short_description:
+        parts.append(docstring.short_description)
+    if docstring.blank_after_short_description:
+        parts.append('')
+    if docstring.long_description:
+        parts.append(docstring.long_description)
+    if docstring.blank_after_long_description:
+        parts.append('')
+
+    for meta in docstring.meta:
+        if isinstance(meta, DocstringParam):
+            if meta.type_name:
+                type_name = (
+                    f'{meta.type_name}?'
+                    if meta.is_optional
+                    else meta.type_name
+                )
+                text = f'@type {meta.arg_name}:'
+                text += process_desc(type_name, True)
+                parts.append(text)
+            text = f'@param {meta.arg_name}:' + process_desc(
+                meta.description, False,
+            )
+            parts.append(text)
+        elif isinstance(meta, DocstringReturns):
+            (arg_key, type_key) = (
+                ('yield', 'ytype')
+                if meta.is_generator
+                else ('return', 'rtype')
+            )
+            if meta.type_name:
+                text = f'@{type_key}:' + process_desc(meta.type_name, True)
+                parts.append(text)
+            if meta.description:
+                text = f'@{arg_key}:' + process_desc(meta.description, False)
+                parts.append(text)
+        elif isinstance(meta, DocstringRaises):
+            text = f'@raise {meta.type_name}:' if meta.type_name else '@raise:'
+            text += process_desc(meta.description, False)
+            parts.append(text)
+        else:
+            text = f'@{" ".join(meta.args)}:'
+            text += process_desc(meta.description, False)
+            parts.append(text)
+    return '\n'.join(parts)