omdev 0.0.0.dev312__tar.gz → 0.0.0.dev314__tar.gz

{omdev-0.0.0.dev312/omdev.egg-info → omdev-0.0.0.dev314}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omdev
-Version: 0.0.0.dev312
+Version: 0.0.0.dev314
 Summary: omdev
 Author: wrmsr
 License: BSD-3-Clause
@@ -12,7 +12,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Operating System :: POSIX
 Requires-Python: >=3.12
 License-File: LICENSE
-Requires-Dist: omlish==0.0.0.dev312
+Requires-Dist: omlish==0.0.0.dev314
 Provides-Extra: all
 Requires-Dist: black~=25.1; extra == "all"
 Requires-Dist: pycparser~=2.22; extra == "all"

{omdev-0.0.0.dev312 → omdev-0.0.0.dev314}/README.md

@@ -11,16 +11,20 @@ Development utilities and support code.
 - **[amalg](amalg)** - The [amalgamator](#amalgamation).
 
 - **[pyproject](pyproject)** ([amalg](scripts/pyproject.py)) - python project management tool. wrangles but does not
-  replace tools like venv, pip, setuptools, and uv. this should grow to eat more and more of the Makefile. as it is
-  amalgamated it requires no installation and can just be dropped into other projects / repos.
-
-- **[ci](ci)** ([amalg](scripts/ci.py)) - ci runner. given a [compose.yml](https://github.com/wrmsr/omlish/blob/master/docker/compose.yml)
-  and requirements.txt files, takes care of building and caching of containers and venvs and execution of required ci
-  commands. detects and [natively uses](ci/github/api/v2) github-action's caching system. unifies ci execution between
-  local dev and github runners.
-
-- **[tools.json](tools/json)** (cli: `om j`) - a tool for json-like data, obviously in the vein of [jq](https://github.com/jqlang/jq)
-  but using the internal [jmespath](https://github.com/wrmsr/omlish/tree/master/omlish/specs/jmespath) engine. supports
+  replace tools like venv, pip, setuptools, and uv. does things like sets up venvs, generates
+  [`.pkg`](https://github.com/wrmsr/omlish/blob/master/.pkg) directories and their `pyproject.toml`'s (from their
+  `__about__.py`'s), and packages them. this should grow to eat more and more of the Makefile. as it is amalgamated it
+  requires no installation and can just be dropped into other projects / repos.
+
+- **[ci](ci)** ([amalg](scripts/ci.py)) - ci runner. given a
+  [`compose.yml`](https://github.com/wrmsr/omlish/blob/master/docker/compose.yml) and requirements.txt files, takes care
+  of building and caching of containers and venvs and execution of required ci commands. detects and
+  [natively uses](ci/github/api/v2) github-action's caching system. unifies ci execution between local dev and github
+  runners.
+
+- **[tools.json](tools/json)** (cli: `om j`) - a tool for json-like data, obviously in the vein of
+  [jq](https://github.com/jqlang/jq) but using the internal
+  [jmespath](https://github.com/wrmsr/omlish/tree/master/omlish/specs/jmespath) engine. supports
   [true streaming](https://github.com/wrmsr/omlish/blob/master/omlish/formats/json/stream) json input and output, as
   well as [various other](tools/json/formats.py) non-streaming input formats.
 

{omdev-0.0.0.dev312 → omdev-0.0.0.dev314}/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-0.0.0.dev312 → omdev-0.0.0.dev314}/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-0.0.0.dev314/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-0.0.0.dev314/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-0.0.0.dev314/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-0.0.0.dev314/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)]