mandos.entry.tools.docs.Documenter._desc() - Code Metrics - Inspection of "fix: various" - dmyersturnbull/mandos - Measure and Improve Code Quality continuously with Scrutinizer

Passed

Push — main ( 65730f...fad324 )

by Douglas

created 2021-10-28 02:08 UTC

mandos.entry.tools.docs.Documenter._desc() A

↳ Parent: mandos.entry.tools.docs

Complexity

Conditions

Size

Total Lines	10
Code Lines	10

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	4
eloc	10
nop	2
dl	0
loc	10
rs	9.9
c	0
b	0
f	0

"""
Documents Mandos commands.
"""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from textwrap import wrap
from typing import Mapping, Optional, Sequence

import pandas as pd

from pocketutils.core.exceptions import ContradictoryRequestError

from pocketutils.misc.typer_utils import TyperUtils

from typeddfs import FileFormat, TypedDfs

from typeddfs.utils import Utils as TdfUtils

from typer.models import CommandInfo


CommandDocDf = (
    TypedDfs.typed("CommandDocDf")
    .require("command", dtype=str)
    .reserve("description", "parameters", dtype=str)
    .strict()
    .secure()
).build()


@dataclass(frozen=True, repr=True)

class Doc:
    command: str
    description: Optional[str]
    params: Optional[Mapping[str, str]]

    def as_lines(self) -> Sequence[str]:

        lines = [self.command]
        if self.description is not None:
            lines.append(self.description)
        if self.params is not None:
            lines.extend(self.description)
        return lines

    def as_dict(self) -> Mapping[str, str]:

        dct = dict(command=self.command)
        if self.description is not None:
            dct["description"] = self.description
        if self.params is not None:
            dct["params"] = "\n".join(self.params.values())
        return dct


@dataclass(frozen=True, repr=True)

class Documenter:
    level: int
    main: bool
    search: bool
    hidden: bool
    common: bool
    width: Optional[int]

    def document(self, commands: Sequence[CommandInfo], to: Path, style: str) -> None:

        fmt = FileFormat.from_path_or_none(to)
        if fmt is not None and not fmt.is_text and style != "table":
            raise ContradictoryRequestError(f"Cannot write binary {fmt} with style {style}")
        if style == "docs":
            content = self.get_long_text(commands)
            TdfUtils.write(to, content, encoding="utf8")
            return
        table = self.get_table(commands)
        if style == "table":
            table.write_file(to)
        else:
            content = table.pretty_print(style)
            TdfUtils.write(to, content, encoding="utf8")

    def get_table(self, commands: Sequence[CommandInfo]) -> CommandDocDf:

        docs = self.get_docs(commands)
        return CommandDocDf.of([pd.Series(d.as_dict()) for d in docs])

    def get_long_text(self, commands: Sequence[CommandInfo]) -> str:

        if self.search and self.main:
            title = "Main and search commands"
        elif self.search:
            title = "Search commands"
        else:
            title = "Main commands"
        docs = self.get_long(commands)
        width = max([len(title), *[len(s) for s in docs.keys()]])

        txt = title + "\n" + "=" * width + "\n\n"
        for k, v in docs.items():

            txt += "\n\n" + k + "\n" + "#" * width + "\n" + v + "\n"
        return txt

    def get_long(self, commands: Sequence[CommandInfo]) -> Mapping[str, str]:

        docs = self.get_docs(commands)
        results = {}
        for doc in docs:
            zz = []

            for line in doc.as_lines():
                zz += line

            results[doc.command] = "\n".join(zz)
        return results

    def get_docs(self, commands: Sequence[CommandInfo]) -> Sequence[Doc]:

        commands = self._commands(commands)
        return [self._doc(cmd) for cmd in commands]

    def _commands(self, commands: Sequence[CommandInfo]):
        cmds = [
            c
            for c in commands
            if (self.hidden or not c.hidden)
            and (c.name.startswith(":") and self.main or not c.name.startswith(":") and self.search)
        ]
        return sorted(cmds, key=lambda c: c.name)

    def _doc(self, cmd: CommandInfo) -> Doc:
        desc = self._wrap(self._desc(cmd))
        params = TyperUtils.get_help(cmd, hidden=self.hidden)
        params = {
            k: self._wrap(self._param(a))
            for k, a in params.items()
            if self._include_arg(cmd.name, k)
        }
        return Doc(command=self._wrap(cmd.name), description=desc, params=params)

    def _desc(self, cmd: CommandInfo) -> Optional[str]:
        cb = cmd.callback.__doc__

        desc_lines = self._split(cb)
        if self.level >= 3:

            return cb
        elif self.level >= 2:
            return "\n".join(desc_lines[:2])
        elif self.level >= 1:
            return desc_lines[0]
        return None

    def _param(self, param: str) -> Optional[str]:
        lines = self._split(param)
        if self.level >= 3:
            return param
        if self.level >= 2:

            return lines[0] + "\n" + lines[1]
        elif self.level >= 1:
            return lines[0]
        return None

    def _include_arg(self, command: str, arg: str) -> bool:
        if self.common:
            return True
        _common = ["path", "--key", "--to", "--as-of", "--replace", "--proceed", "--check"]
        return arg not in ["--stderr", "--log"] and (command.startswith(":") or arg not in _common)

    def _split(self, txt: str) -> Sequence[str]:
        zs = []

        for s in txt.splitlines():

            s = self._clean(s)

            if len(s) > 0:
                zs.append(s)
        return zs

    def _clean(self, txt: str) -> str:
class Foo:
    def some_method(self, x, y):
        return x + y;
        return TdfUtils.strip_control_chars(txt.replace("\n", " ").replace("\t", " ")).strip()

    def _wrap(self, txt: Optional[str]) -> Optional[str]:
        if txt is None:
            return None
        if self.width is None:
            return txt
        return "\n".join(wrap(txt, width=self.width))


__all__ = ["Documenter", "Doc", "CommandDocDf"]


1			"""
2			Documents Mandos commands.
3			"""
4
5			from __future__ import annotations
6
7			from dataclasses import dataclass
8			from pathlib import Path
9			from textwrap import wrap
10			from typing import Mapping, Optional, Sequence
11
12			import pandas as pd
			0 ignored issues – show introduced 2021-10-12 03:37 UTC by Report Bug Copy Issue Report Unable to import 'pandas' Loading history...
13			from pocketutils.core.exceptions import ContradictoryRequestError
			0 ignored issues – show introduced 2021-09-23 03:01 UTC by Report Bug Copy Issue Report Unable to import 'pocketutils.core.exceptions' Loading history...
14			from pocketutils.misc.typer_utils import TyperUtils
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Unable to import 'pocketutils.misc.typer_utils' Loading history...
15			from typeddfs import FileFormat, TypedDfs
			0 ignored issues – show introduced 2021-09-06 00:54 UTC by Report Bug Copy Issue Report Unable to import 'typeddfs' Loading history...
16			from typeddfs.utils import Utils as TdfUtils
			0 ignored issues – show introduced 2021-08-16 03:00 UTC by Report Bug Copy Issue Report Unable to import 'typeddfs.utils' Loading history...
17			from typer.models import CommandInfo
			0 ignored issues – show introduced 2021-08-16 03:00 UTC by Report Bug Copy Issue Report Unable to import 'typer.models' Loading history...
18
19			CommandDocDf = (
20			TypedDfs.typed("CommandDocDf")
21			.require("command", dtype=str)
22			.reserve("description", "parameters", dtype=str)
23			.strict()
24			.secure()
25			).build()
26
27
28			@dataclass(frozen=True, repr=True)
			0 ignored issues – show introduced 2021-03-21 02:08 UTC by Report Bug Copy Issue Report Missing class docstring Loading history...
29			class Doc:
30			command: str
31			description: Optional[str]
32			params: Optional[Mapping[str, str]]
33
34			def as_lines(self) -> Sequence[str]:
			0 ignored issues – show introduced 2021-08-16 03:00 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
35			lines = [self.command]
36			if self.description is not None:
37			lines.append(self.description)
38			if self.params is not None:
39			lines.extend(self.description)
40			return lines
41
42			def as_dict(self) -> Mapping[str, str]:
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
43			dct = dict(command=self.command)
44			if self.description is not None:
45			dct["description"] = self.description
46			if self.params is not None:
47			dct["params"] = "\n".join(self.params.values())
48			return dct
49
50
51			@dataclass(frozen=True, repr=True)
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing class docstring Loading history...
52			class Documenter:
53			level: int
54			main: bool
55			search: bool
56			hidden: bool
57			common: bool
58			width: Optional[int]
59
60			def document(self, commands: Sequence[CommandInfo], to: Path, style: str) -> None:
			0 ignored issues – show Coding Style Naming introduced 2021-08-16 03:00 UTC by Report Bug Copy Issue Report Argument name "to" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history... introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
61			fmt = FileFormat.from_path_or_none(to)
62			if fmt is not None and not fmt.is_text and style != "table":
63			raise ContradictoryRequestError(f"Cannot write binary {fmt} with style {style}")
64			if style == "docs":
65			content = self.get_long_text(commands)
66			TdfUtils.write(to, content, encoding="utf8")
67			return
68			table = self.get_table(commands)
69			if style == "table":
70			table.write_file(to)
71			else:
72			content = table.pretty_print(style)
73			TdfUtils.write(to, content, encoding="utf8")
74
75			def get_table(self, commands: Sequence[CommandInfo]) -> CommandDocDf:
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
76			docs = self.get_docs(commands)
77			return CommandDocDf.of([pd.Series(d.as_dict()) for d in docs])
78
79			def get_long_text(self, commands: Sequence[CommandInfo]) -> str:
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
80			if self.search and self.main:
81			title = "Main and search commands"
82			elif self.search:
83			title = "Search commands"
84			else:
85			title = "Main commands"
86			docs = self.get_long(commands)
87			width = max([len(title), *[len(s) for s in docs.keys()]])
			0 ignored issues – show unused-code introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Consider iterating the dictionary directly instead of calling .keys() Loading history...
88			txt = title + "\n" + "=" * width + "\n\n"
89			for k, v in docs.items():
			0 ignored issues – show Coding Style Naming introduced 2021-08-16 03:00 UTC by Report Bug Copy Issue Report Variable name "v" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
90			txt += "\n\n" + k + "\n" + "#" * width + "\n" + v + "\n"
91			return txt
92
93			def get_long(self, commands: Sequence[CommandInfo]) -> Mapping[str, str]:
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
94			docs = self.get_docs(commands)
95			results = {}
96			for doc in docs:
97			zz = []
			0 ignored issues – show Coding Style Naming introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Variable name "zz" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
98			for line in doc.as_lines():
99			zz += line
			0 ignored issues – show Coding Style Naming introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Variable name "zz" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
100			results[doc.command] = "\n".join(zz)
101			return results
102
103			def get_docs(self, commands: Sequence[CommandInfo]) -> Sequence[Doc]:
			0 ignored issues – show introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Missing function or method docstring Loading history...
104			commands = self._commands(commands)
105			return [self._doc(cmd) for cmd in commands]
106
107			def _commands(self, commands: Sequence[CommandInfo]):
108			cmds = [
109			c
110			for c in commands
111			if (self.hidden or not c.hidden)
112			and (c.name.startswith(":") and self.main or not c.name.startswith(":") and self.search)
113			]
114			return sorted(cmds, key=lambda c: c.name)
115
116			def _doc(self, cmd: CommandInfo) -> Doc:
117			desc = self._wrap(self._desc(cmd))
118			params = TyperUtils.get_help(cmd, hidden=self.hidden)
119			params = {
120			k: self._wrap(self._param(a))
121			for k, a in params.items()
122			if self._include_arg(cmd.name, k)
123			}
124			return Doc(command=self._wrap(cmd.name), description=desc, params=params)
125
126			def _desc(self, cmd: CommandInfo) -> Optional[str]:
127			cb = cmd.callback.__doc__
			0 ignored issues – show Coding Style Naming introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Variable name "cb" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
128			desc_lines = self._split(cb)
129			if self.level >= 3:
			0 ignored issues – show unused-code introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Unnecessary "elif" after "return" Loading history...
130			return cb
131			elif self.level >= 2:
132			return "\n".join(desc_lines[:2])
133			elif self.level >= 1:
134			return desc_lines[0]
135			return None
136
137			def _param(self, param: str) -> Optional[str]:
138			lines = self._split(param)
139			if self.level >= 3:
140			return param
141			if self.level >= 2:
			0 ignored issues – show unused-code introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Unnecessary "elif" after "return" Loading history...
142			return lines[0] + "\n" + lines[1]
143			elif self.level >= 1:
144			return lines[0]
145			return None
146
147			def _include_arg(self, command: str, arg: str) -> bool:
148			if self.common:
149			return True
150			_common = ["path", "--key", "--to", "--as-of", "--replace", "--proceed", "--check"]
151			return arg not in ["--stderr", "--log"] and (command.startswith(":") or arg not in _common)
152
153			def _split(self, txt: str) -> Sequence[str]:
154			zs = []
			0 ignored issues – show Coding Style Naming introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Variable name "zs" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
155			for s in txt.splitlines():
			0 ignored issues – show Coding Style Naming introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Variable name "s" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
156			s = self._clean(s)
			0 ignored issues – show Coding Style Naming introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report Variable name "s" doesn't conform to snake_case naming style ('([^\\W\\dA-Z][^\\WA-Z]2,\|_[^\\WA-Z]*\|__[^\\WA-Z\\d_][^\\WA-Z]+__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
157			if len(s) > 0:
158			zs.append(s)
159			return zs
160
161			def _clean(self, txt: str) -> str:
			0 ignored issues – show Coding Style introduced 2021-10-28 02:14 UTC by Report Bug Copy Issue Report This method could be written as a function/class method. If a method does not access any attributes of the class, it could also be implemented as a function or static method. This can help improve readability. For example class Foo: def some_method(self, x, y): return x + y; could be written as class Foo: @classmethod def some_method(cls, x, y): return x + y; Loading history...
162			return TdfUtils.strip_control_chars(txt.replace("\n", " ").replace("\t", " ")).strip()
163
164			def _wrap(self, txt: Optional[str]) -> Optional[str]:
165			if txt is None:
166			return None
167			if self.width is None:
168			return txt
169			return "\n".join(wrap(txt, width=self.width))
170
171
172			__all__ = ["Documenter", "Doc", "CommandDocDf"]
173

dmyersturnbull / mandos

Push — main ( 65730f...fad324 )

mandos.entry.tools.docs.Documenter._desc() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like