singlestoredb 1.14.2__cp38-abi3-win_amd64.whl → 1.15.1__cp38-abi3-win_amd64.whl

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)

singlestoredb/docstring/google.py

@@ -0,0 +1,412 @@
+"""Google-style docstring parsing."""
+import inspect
+import re
+import typing as T
+from collections import namedtuple
+from collections import OrderedDict
+from enum import IntEnum
+
+from .common import Docstring
+from .common import DocstringExample
+from .common import DocstringMeta
+from .common import DocstringParam
+from .common import DocstringRaises
+from .common import DocstringReturns
+from .common import DocstringStyle
+from .common import EXAMPLES_KEYWORDS
+from .common import PARAM_KEYWORDS
+from .common import ParseError
+from .common import RAISES_KEYWORDS
+from .common import RenderingStyle
+from .common import RETURNS_KEYWORDS
+from .common import YIELDS_KEYWORDS
+
+
+class SectionType(IntEnum):
+    """Types of sections."""
+
+    SINGULAR = 0
+    """For sections like examples."""
+
+    MULTIPLE = 1
+    """For sections like params."""
+
+    SINGULAR_OR_MULTIPLE = 2
+    """For sections like returns or yields."""
+
+
+class Section(namedtuple('SectionBase', 'title key type')):
+    """A docstring section."""
+
+
+GOOGLE_TYPED_ARG_REGEX = re.compile(r'\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)')
+GOOGLE_ARG_DESC_REGEX = re.compile(r'.*\. Defaults to (.+)\.')
+MULTIPLE_PATTERN = re.compile(r'(\s*[^:\s]+:)|([^:]*\]:.*)')
+
+DEFAULT_SECTIONS = [
+    Section('Arguments', 'param', SectionType.MULTIPLE),
+    Section('Args', 'param', SectionType.MULTIPLE),
+    Section('Parameters', 'param', SectionType.MULTIPLE),
+    Section('Params', 'param', SectionType.MULTIPLE),
+    Section('Raises', 'raises', SectionType.MULTIPLE),
+    Section('Exceptions', 'raises', SectionType.MULTIPLE),
+    Section('Except', 'raises', SectionType.MULTIPLE),
+    Section('Attributes', 'attribute', SectionType.MULTIPLE),
+    Section('Example', 'examples', SectionType.SINGULAR),
+    Section('Examples', 'examples', SectionType.SINGULAR),
+    Section('Returns', 'returns', SectionType.SINGULAR_OR_MULTIPLE),
+    Section('Yields', 'yields', SectionType.SINGULAR_OR_MULTIPLE),
+]
+
+
+class GoogleParser:
+    """Parser for Google-style docstrings."""
+
+    def __init__(
+        self, sections: T.Optional[T.List[Section]] = None, title_colon: bool = True,
+    ):
+        """Setup sections.
+
+        :param sections: Recognized sections or None to defaults.
+        :param title_colon: require colon after section title.
+        """
+        if not sections:
+            sections = DEFAULT_SECTIONS
+        self.sections = {s.title: s for s in sections}
+        self.title_colon = title_colon
+        self._setup()
+
+    def _setup(self) -> None:
+        if self.title_colon:
+            colon = ':'
+        else:
+            colon = ''
+        self.titles_re = re.compile(
+            '^('
+            + '|'.join(f'({t})' for t in self.sections)
+            + ')'
+            + colon
+            + '[ \t\r\f\v]*$',
+            flags=re.M,
+        )
+
+    def _build_meta(self, text: str, title: str) -> DocstringMeta:
+        """Build docstring element.
+
+        :param text: docstring element text
+        :param title: title of section containing element
+        :return:
+        """
+
+        section = self.sections[title]
+
+        if (
+            section.type == SectionType.SINGULAR_OR_MULTIPLE
+            and not MULTIPLE_PATTERN.match(text)
+        ) or section.type == SectionType.SINGULAR:
+            return self._build_single_meta(section, text)
+
+        if ':' not in text:
+            raise ParseError(f'Expected a colon in {text!r}.')
+
+        # Split spec and description
+        before, desc = text.split(':', 1)
+
+        if before and '\n' in before:
+            # If there is a newline in the first line, clean it up
+            first_line, rest = before.split('\n', 1)
+            before = first_line + inspect.cleandoc(rest)
+
+        if desc:
+            desc = desc[1:] if desc[0] == ' ' else desc
+            if '\n' in desc:
+                first_line, rest = desc.split('\n', 1)
+                desc = first_line + '\n' + inspect.cleandoc(rest)
+            desc = desc.strip('\n')
+
+        return self._build_multi_meta(section, before, desc)
+
+    @staticmethod
+    def _build_single_meta(section: Section, desc: str) -> DocstringMeta:
+        if section.key in RETURNS_KEYWORDS | YIELDS_KEYWORDS:
+            return DocstringReturns(
+                args=[section.key],
+                description=desc,
+                type_name=None,
+                is_generator=section.key in YIELDS_KEYWORDS,
+            )
+        if section.key in RAISES_KEYWORDS:
+            return DocstringRaises(
+                args=[section.key], description=desc, type_name=None,
+            )
+        if section.key in EXAMPLES_KEYWORDS:
+            return DocstringExample(
+                args=[section.key], snippet=None, description=desc,
+            )
+        if section.key in PARAM_KEYWORDS:
+            raise ParseError('Expected paramenter name.')
+        return DocstringMeta(args=[section.key], description=desc)
+
+    @staticmethod
+    def _build_multi_meta(
+        section: Section, before: str, desc: str,
+    ) -> DocstringMeta:
+        if section.key in PARAM_KEYWORDS:
+            match = GOOGLE_TYPED_ARG_REGEX.match(before)
+            if match:
+                arg_name, type_name = match.group(1, 2)
+                if type_name.endswith(', optional'):
+                    is_optional = True
+                    type_name = type_name[:-10]
+                elif type_name.endswith('?'):
+                    is_optional = True
+                    type_name = type_name[:-1]
+                else:
+                    is_optional = False
+            else:
+                arg_name, type_name = before, None
+                is_optional = None
+
+            match = GOOGLE_ARG_DESC_REGEX.match(desc)
+            default = match.group(1) if match else None
+
+            return DocstringParam(
+                args=[section.key, before],
+                description=desc,
+                arg_name=arg_name,
+                type_name=type_name,
+                is_optional=is_optional,
+                default=default,
+            )
+        if section.key in RETURNS_KEYWORDS | YIELDS_KEYWORDS:
+            return DocstringReturns(
+                args=[section.key, before],
+                description=desc,
+                type_name=before,
+                is_generator=section.key in YIELDS_KEYWORDS,
+            )
+        if section.key in RAISES_KEYWORDS:
+            return DocstringRaises(
+                args=[section.key, before], description=desc, type_name=before,
+            )
+        return DocstringMeta(args=[section.key, before], description=desc)
+
+    def add_section(self, section: Section) -> None:
+        """Add or replace a section.
+
+        :param section: The new section.
+        """
+
+        self.sections[section.title] = section
+        self._setup()
+
+    def parse(self, text: T.Optional[str]) -> Docstring:
+        """Parse the Google-style docstring into its components.
+
+        :returns: parsed docstring
+        """
+        ret = Docstring(style=DocstringStyle.GOOGLE)
+        if not text:
+            return ret
+
+        # Clean according to PEP-0257
+        text = inspect.cleandoc(text)
+
+        # Find first title and split on its position
+        match = self.titles_re.search(text)
+        if match:
+            desc_chunk = text[:match.start()]
+            meta_chunk = text[match.start():]
+        else:
+            desc_chunk = text
+            meta_chunk = ''
+
+        # Break description into short and long parts
+        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
+
+        # Split by sections determined by titles
+        matches = list(self.titles_re.finditer(meta_chunk))
+        if not matches:
+            return ret
+        splits = []
+        for j in range(len(matches) - 1):
+            splits.append((matches[j].end(), matches[j + 1].start()))
+        splits.append((matches[-1].end(), len(meta_chunk)))
+
+        chunks = OrderedDict()  # type: T.MutableMapping[str,str]
+        for j, (start, end) in enumerate(splits):
+            title = matches[j].group(1)
+            if title not in self.sections:
+                continue
+
+            # Clear Any Unknown Meta
+            # Ref: https://github.com/rr-/docstring_parser/issues/29
+            meta_details = meta_chunk[start:end]
+            unknown_meta = re.search(r'\n\S', meta_details)
+            if unknown_meta is not None:
+                meta_details = meta_details[: unknown_meta.start()]
+
+            chunks[title] = meta_details.strip('\n')
+        if not chunks:
+            return ret
+
+        # Add elements from each chunk
+        for title, chunk in chunks.items():
+            # Determine indent
+            indent_match = re.search(r'^\s*', chunk)
+            if not indent_match:
+                raise ParseError(f'Can\'t infer indent from "{chunk}"')
+            indent = indent_match.group()
+
+            # Check for singular elements
+            if self.sections[title].type in [
+                SectionType.SINGULAR,
+                SectionType.SINGULAR_OR_MULTIPLE,
+            ]:
+                part = inspect.cleandoc(chunk)
+                ret.meta.append(self._build_meta(part, title))
+                continue
+
+            # Split based on lines which have exactly that indent
+            _re = '^' + indent + r'(?=\S)'
+            c_matches = list(re.finditer(_re, chunk, flags=re.M))
+            if not c_matches:
+                raise ParseError(f'No specification for "{title}": "{chunk}"')
+            c_splits = []
+            for j in range(len(c_matches) - 1):
+                c_splits.append((c_matches[j].end(), c_matches[j + 1].start()))
+            c_splits.append((c_matches[-1].end(), len(chunk)))
+            for j, (start, end) in enumerate(c_splits):
+                part = chunk[start:end].strip('\n')
+                ret.meta.append(self._build_meta(part, title))
+
+        return ret
+
+
+def parse(text: T.Optional[str]) -> Docstring:
+    """Parse the Google-style docstring into its components.
+
+    :returns: parsed docstring
+    """
+    return GoogleParser().parse(text)
+
+
+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_one(
+        one: T.Union[DocstringParam, DocstringReturns, DocstringRaises],
+    ) -> None:
+        head = ''
+
+        if isinstance(one, DocstringParam):
+            head += one.arg_name or ''
+        elif isinstance(one, DocstringReturns):
+            head += one.return_name or ''
+
+        if isinstance(one, DocstringParam) and one.is_optional:
+            optional = (
+                '?'
+                if rendering_style == RenderingStyle.COMPACT
+                else ', optional'
+            )
+        else:
+            optional = ''
+
+        if one.type_name and head:
+            head += f' ({one.type_name}{optional}):'
+        elif one.type_name:
+            head += f'{one.type_name}{optional}:'
+        else:
+            head += ':'
+        head = indent + head
+
+        if one.description and rendering_style == RenderingStyle.EXPANDED:
+            body = f'\n{indent}{indent}'.join(
+                [head] + one.description.splitlines(),
+            )
+            parts.append(body)
+        elif one.description:
+            (first, *rest) = one.description.splitlines()
+            body = f'\n{indent}{indent}'.join([head + ' ' + first] + rest)
+            parts.append(body)
+        else:
+            parts.append(head)
+
+    def process_sect(name: str, args: T.List[T.Any]) -> None:
+        if args:
+            parts.append(name)
+            for arg in args:
+                process_one(arg)
+            parts.append('')
+
+    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('')
+
+    process_sect(
+        'Args:', [p for p in docstring.params or [] if p.args[0] == 'param'],
+    )
+
+    process_sect(
+        'Attributes:',
+        [p for p in docstring.params or [] if p.args[0] == 'attribute'],
+    )
+
+    process_sect(
+        'Returns:',
+        [p for p in docstring.many_returns or [] if not p.is_generator],
+    )
+
+    process_sect(
+        'Yields:', [p for p in docstring.many_returns or [] if p.is_generator],
+    )
+
+    process_sect('Raises:', docstring.raises or [])
+
+    if docstring.returns and not docstring.many_returns:
+        ret = docstring.returns
+        parts.append('Yields:' if ret else 'Returns:')
+        parts.append('-' * len(parts[-1]))
+        process_one(ret)
+
+    for meta in docstring.meta:
+        if isinstance(
+            meta, (DocstringParam, DocstringReturns, DocstringRaises),
+        ):
+            continue  # Already handled
+        parts.append(meta.args[0].replace('_', '').title() + ':')
+        if meta.description:
+            lines = [indent + m for m in meta.description.splitlines()]
+            parts.append('\n'.join(lines))
+        parts.append('')
+
+    while parts and not parts[-1]:
+        parts.pop()
+
+    return '\n'.join(parts)