omdev 0.0.0.dev313__py3-none-any.whl → 0.0.0.dev314__py3-none-any.whl

omdev/.manifests.json

@@ -342,7 +342,7 @@
     "module": ".tools.docker",
     "attr": "_CLI_MODULE",
     "file": "omdev/tools/docker.py",
-    "line": 251,
+    "line": 256,
     "value": {
       "$.cli.types.CliModule": {
         "cmd_name": "docker",

omdev/magic/styles.py

@@ -20,14 +20,21 @@ class MagicStyle:
 
 PY_MAGIC_STYLE = MagicStyle(
     name='py',
-    exts=frozenset(['py']),
+    exts=frozenset([
+        'py',
+    ]),
     line_prefix='# ',
 )
 
 
 C_MAGIC_STYLE = MagicStyle(
     name='c',
-    exts=frozenset(['c', 'cc', 'cpp', 'cu']),
+    exts=frozenset([
+        'c',
+        'cc',
+        'cpp',
+        'cu',
+    ]),
     line_prefix='// ',
     block_prefix_suffix=('/* ', '*/'),
 )

omdev/py/docstrings/LICENSE

@@ -0,0 +1,16 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Marcin Kurczewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

omdev/py/docstrings/__init__.py

@@ -0,0 +1,19 @@
+"""Parse docstrings as per Sphinx notation."""
+# https://github.com/rr-/docstring_parser/tree/4951137875e79b438d52a18ac971ec0c28ef269c
+
+from .common import (  # noqa
+    Docstring,
+    DocstringDeprecated,
+    DocstringMeta,
+    DocstringParam,
+    DocstringRaises,
+    DocstringReturns,
+    DocstringStyle,
+    ParseError,
+    RenderingStyle,
+)
+
+from .parser import (  # noqa
+    parse,
+    parse_from_object,
+)

omdev/py/docstrings/attrdoc.py

@@ -0,0 +1,151 @@
+"""
+Attribute docstrings parsing.
+
+.. seealso:: https://peps.python.org/pep-0257/#what-is-a-docstring
+"""
+import ast
+import inspect
+import textwrap
+import types
+import typing as ta
+
+from .common import Docstring
+from .common import DocstringParam
+
+
+##
+
+
+_AST_CONSTANT_ATTR: ta.Mapping[type, str] = {
+    ast.Constant: 'value',
+}
+
+
+def ast_get_constant_value(node: ast.AST) -> ta.Any:
+    """Return the constant's value if the given node is a constant."""
+
+    return getattr(node, _AST_CONSTANT_ATTR[type(node)])
+
+
+def ast_unparse(node: ast.AST) -> str | None:
+    """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.Num, ast.NameConstant, 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,
+) -> tuple[str, str | None, str | None] | None:
+    """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: ta.Any = None
+    prev_attr: ta.Any = None
+
+    def visit(self, node: ast.AST) -> 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),  # type: ignore[attr-defined]
+                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: ta.Any,
+    ) -> dict[str, tuple[str, str | None, str | None]]:
+        """
+        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: type | types.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 = {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)

omdev/py/docstrings/common.py

@@ -0,0 +1,285 @@
+"""Common methods for parsing."""
+import enum
+
+
+##
+
+
+PARAM_KEYWORDS = {
+    'arg',
+    'argument',
+    'attribute',
+    'key',
+    'keyword',
+    'param',
+    'parameter',
+}
+
+RAISES_KEYWORDS = {
+    'except',
+    'exception',
+    'raise',
+    'raises',
+}
+
+DEPRECATION_KEYWORDS = {
+    'deprecated',
+    'deprecation',
+}
+
+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: list[str],
+            description: str | None,
+    ) -> 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.
+        """
+
+        super().__init__()
+
+        self.args = args
+        self.description = description
+
+
+class DocstringParam(DocstringMeta):
+    """DocstringMeta symbolizing :param metadata."""
+
+    def __init__(
+            self,
+            args: list[str],
+            description: str | None,
+            arg_name: str,
+            type_name: str | None,
+            is_optional: bool | None,
+            default: str | None,
+    ) -> 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: list[str],
+            description: str | None,
+            type_name: str | None,
+            is_generator: bool,
+            return_name: str | None = 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: list[str],
+            description: str | None,
+            type_name: str | None,
+    ) -> 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: list[str],
+            description: str | None,
+            version: str | None,
+    ) -> None:
+        """Initialize self."""
+
+        super().__init__(args, description)
+
+        self.version = version
+        self.description = description
+
+
+class DocstringExample(DocstringMeta):
+    """DocstringMeta symbolizing example metadata."""
+
+    def __init__(
+            self,
+            args: list[str],
+            snippet: str | None,
+            description: str | None,
+    ) -> None:
+        """Initialize self."""
+
+        super().__init__(args, description)
+
+        self.snippet = snippet
+        self.description = description
+
+
+##
+
+
+class Docstring:
+    """Docstring object representation."""
+
+    def __init__(
+            self,
+            style: DocstringStyle | None = None,
+    ) -> None:
+        """Initialize self."""
+
+        super().__init__()
+
+        self.short_description: str | None = None
+        self.long_description: str | None = None
+        self.blank_after_short_description = False
+        self.blank_after_long_description = False
+        self.meta: list[DocstringMeta] = []
+        self.style: DocstringStyle | None = style
+
+    @property
+    def description(self) -> str | None:
+        """
+        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) -> 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) -> 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) -> DocstringReturns | None:
+        """
+        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) -> 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) -> DocstringDeprecated | None:
+        """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) -> list[DocstringExample]:
+        """Return a list of information on function examples."""
+
+        return [item for item in self.meta if isinstance(item, DocstringExample)]

omdev/py/docstrings/epydoc.py

@@ -0,0 +1,198 @@
+"""
+Epyoc-style docstring parsing.
+
+.. seealso:: http://epydoc.sourceforge.net/manual-fields.html
+"""
+import inspect
+import re
+import typing as ta
+
+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
+
+
+##
+
+
+def _clean_str(string: str) -> str | None:
+    string = string.strip()
+    if len(string) > 0:
+        return string
+    return None
+
+
+_PARAM_PAT = re.compile(r'(param|keyword|type)(\s+[_A-z][_A-z0-9]*\??):')
+_RAISE_PAT = re.compile(r'(raise)(\s+[_A-z][_A-z0-9]*\??)?:')
+_RETURN_PAT = re.compile(r'(return|rtype|yield|ytype):')
+_META_PAT = re.compile(r'([_A-z][_A-z0-9]+)((\s+[_A-z][_A-z0-9]*\??)*):')
+
+
+def parse(text: 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.MULTILINE)
+    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
+
+    # tokenize
+    stream: list[tuple[str, str, list[str], str]] = []
+    for match in re.finditer(r'(^@.*?)(?=^@|\Z)', meta_chunk, flags=re.DOTALL | re.MULTILINE):
+        chunk = match.group(0)
+        if not chunk:
+            continue
+
+        param_match = re.search(_PARAM_PAT, chunk)
+        raise_match = re.search(_RAISE_PAT, chunk)
+        return_match = re.search(_RETURN_PAT, chunk)
+        meta_match = re.search(_META_PAT, 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():]
+
+        key: str
+        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: dict[str, dict[str, ta.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}".',
+                )
+
+    is_done: dict[str, bool] = {}
+    meta_item: DocstringMeta
+    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',)
+            if not is_done.get(key, False):
+                raise ParseError
+            continue  # don't append
+
+        ret.meta.append(meta_item)
+
+    return ret