clinspector 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- clinspector/__init__.py +5 -0
- clinspector/introspect/__init__.py +51 -0
- clinspector/introspect/introspect_argparse.py +62 -0
- clinspector/introspect/introspect_cappa.py +84 -0
- clinspector/introspect/introspect_cleo.py +120 -0
- clinspector/introspect/introspect_click.py +70 -0
- clinspector/introspect/introspect_typer.py +39 -0
- clinspector/models/__init__.py +0 -0
- clinspector/models/commandinfo.py +38 -0
- clinspector/models/param.py +64 -0
- clinspector/py.typed +0 -0
- clinspector-0.1.0.dist-info/METADATA +179 -0
- clinspector-0.1.0.dist-info/RECORD +16 -0
- clinspector-0.1.0.dist-info/WHEEL +4 -0
- clinspector-0.1.0.dist-info/entry_points.txt +4 -0
- clinspector-0.1.0.dist-info/licenses/LICENSE +22 -0
clinspector/__init__.py
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
import importlib.util
|
|
5
|
+
from typing import Any, TYPE_CHECKING
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
if TYPE_CHECKING:
|
|
9
|
+
from clinspector.models import commandinfo
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def get_cmd_info(instance: Any) -> commandinfo.CommandInfo | None:
|
|
13
|
+
"""Return a `CommmandInfo` object for command of given instance.
|
|
14
|
+
|
|
15
|
+
Instance can be a `Typer`, **click** `Group` or `ArgumentParser` instance.
|
|
16
|
+
|
|
17
|
+
Args:
|
|
18
|
+
instance: A `Typer`, **click** `Group` or `ArgumentParser` instance
|
|
19
|
+
"""
|
|
20
|
+
if importlib.util.find_spec("typer"):
|
|
21
|
+
from clinspector.introspect.introspect_typer import get_info as typer_info
|
|
22
|
+
import typer
|
|
23
|
+
|
|
24
|
+
if isinstance(instance, typer.Typer):
|
|
25
|
+
return typer_info(instance)
|
|
26
|
+
|
|
27
|
+
if importlib.util.find_spec("click"):
|
|
28
|
+
from clinspector.introspect.introspect_click import get_info as click_info
|
|
29
|
+
import click
|
|
30
|
+
|
|
31
|
+
if isinstance(instance, click.Group):
|
|
32
|
+
return click_info(instance)
|
|
33
|
+
|
|
34
|
+
if importlib.util.find_spec("cleo"):
|
|
35
|
+
from clinspector.introspect.introspect_cleo import get_info as cleo_info
|
|
36
|
+
from cleo.application import Application
|
|
37
|
+
|
|
38
|
+
if isinstance(instance, Application):
|
|
39
|
+
return cleo_info(instance)
|
|
40
|
+
|
|
41
|
+
if importlib.util.find_spec("cappa"):
|
|
42
|
+
from clinspector.introspect.introspect_cappa import get_info as cappa_info
|
|
43
|
+
|
|
44
|
+
if hasattr(instance, "__cappa__"):
|
|
45
|
+
return cappa_info(instance)
|
|
46
|
+
|
|
47
|
+
if isinstance(instance, argparse.ArgumentParser):
|
|
48
|
+
from clinspector.introspect.introspect_argparse import get_info as argparse_info
|
|
49
|
+
|
|
50
|
+
return argparse_info(instance)
|
|
51
|
+
return None
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
|
|
5
|
+
from clinspector.models import commandinfo, param
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def parse(parser: argparse.ArgumentParser):
|
|
9
|
+
"""Recursively parse an ArgumentParser instance and return a `CommandInfo` object."""
|
|
10
|
+
try:
|
|
11
|
+
subparse_action = next(
|
|
12
|
+
i for i in parser._actions if isinstance(i, argparse._SubParsersAction)
|
|
13
|
+
)
|
|
14
|
+
subcommands = {i: parse(j) for i, j in subparse_action.choices.items()}
|
|
15
|
+
except StopIteration:
|
|
16
|
+
subcommands = {}
|
|
17
|
+
params = [
|
|
18
|
+
param.Param(
|
|
19
|
+
metavar=" ".join(i.metavar) if isinstance(i.metavar, tuple) else i.metavar,
|
|
20
|
+
help=i.help,
|
|
21
|
+
default=i.default if i.default != argparse.SUPPRESS else None,
|
|
22
|
+
opts=list(i.option_strings),
|
|
23
|
+
nargs=i.nargs,
|
|
24
|
+
required=i.required,
|
|
25
|
+
# dest: str
|
|
26
|
+
# const: Any
|
|
27
|
+
# choices: Iterable[Any] | None
|
|
28
|
+
)
|
|
29
|
+
for i in parser._actions
|
|
30
|
+
]
|
|
31
|
+
return commandinfo.CommandInfo(
|
|
32
|
+
name=parser.prog,
|
|
33
|
+
description=parser.description or "",
|
|
34
|
+
usage=parser.format_usage(),
|
|
35
|
+
params=params,
|
|
36
|
+
subcommands=subcommands,
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def get_info(
|
|
41
|
+
instance: argparse.ArgumentParser,
|
|
42
|
+
command: str | None = None,
|
|
43
|
+
) -> commandinfo.CommandInfo:
|
|
44
|
+
"""Return a `CommmandInfo` object for command of given instance.
|
|
45
|
+
|
|
46
|
+
Args:
|
|
47
|
+
instance: A `ArgumentParser` instance
|
|
48
|
+
command: The command to get info for. (also accepts dot notation for subcommands)
|
|
49
|
+
"""
|
|
50
|
+
info = parse(instance)
|
|
51
|
+
if command:
|
|
52
|
+
for cmd in command.split("."):
|
|
53
|
+
info = info[cmd]
|
|
54
|
+
return info
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
if __name__ == "__main__":
|
|
58
|
+
from _griffe import cli
|
|
59
|
+
|
|
60
|
+
parser = cli.get_parser()
|
|
61
|
+
info = get_info(parser, "check")
|
|
62
|
+
print(info)
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
"""Introspection module for cappa CLI applications."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import dataclasses
|
|
6
|
+
from typing import Any, get_type_hints
|
|
7
|
+
|
|
8
|
+
import cappa
|
|
9
|
+
|
|
10
|
+
from clinspector.models import commandinfo, param
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _get_param_from_arg(name: str, arg: cappa.Arg[Any]) -> param.Param:
|
|
14
|
+
"""Convert a cappa.Arg to a Param object.
|
|
15
|
+
|
|
16
|
+
Args:
|
|
17
|
+
name: Parameter name
|
|
18
|
+
arg: Cappa argument object
|
|
19
|
+
"""
|
|
20
|
+
opts = []
|
|
21
|
+
if arg.short:
|
|
22
|
+
opts.append(f"-{arg.short}")
|
|
23
|
+
if arg.long:
|
|
24
|
+
opts.append(f"--{arg.long}")
|
|
25
|
+
|
|
26
|
+
return param.Param(
|
|
27
|
+
name=name,
|
|
28
|
+
help=arg.help,
|
|
29
|
+
default=arg.default,
|
|
30
|
+
required=arg.required or False,
|
|
31
|
+
opts=opts,
|
|
32
|
+
# multiple=arg.multiple,
|
|
33
|
+
# is_flag=isinstance(arg.type, bool),
|
|
34
|
+
# metavar=arg.metavar,
|
|
35
|
+
# envvar=arg.env,
|
|
36
|
+
hidden=arg.hidden,
|
|
37
|
+
param_type_name="option" if opts else "argument",
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def get_info(cls: type[Any]) -> commandinfo.CommandInfo:
|
|
42
|
+
"""Extract CLI information from a cappa dataclass.
|
|
43
|
+
|
|
44
|
+
Args:
|
|
45
|
+
cls: Dataclass to analyze
|
|
46
|
+
|
|
47
|
+
Raises:
|
|
48
|
+
TypeError: If cls is not a dataclass
|
|
49
|
+
"""
|
|
50
|
+
if not dataclasses.is_dataclass(cls):
|
|
51
|
+
msg = f"Expected a dataclass, got {type(cls)}"
|
|
52
|
+
raise TypeError(msg)
|
|
53
|
+
|
|
54
|
+
params: list[param.Param] = []
|
|
55
|
+
hints = get_type_hints(cls, include_extras=True)
|
|
56
|
+
params = [
|
|
57
|
+
_get_param_from_arg(field.name, meta)
|
|
58
|
+
for field in dataclasses.fields(cls)
|
|
59
|
+
if (hint := hints.get(field.name)) and hasattr(hint, "__metadata__")
|
|
60
|
+
for meta in hint.__metadata__
|
|
61
|
+
if isinstance(meta, cappa.Arg)
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
return commandinfo.CommandInfo(
|
|
65
|
+
name=cls.__name__.lower(),
|
|
66
|
+
description=cls.__doc__ or "",
|
|
67
|
+
params=params,
|
|
68
|
+
usage=cls.__name__.lower(),
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
if __name__ == "__main__":
|
|
73
|
+
import typing
|
|
74
|
+
|
|
75
|
+
@cappa.command(invoke=print)
|
|
76
|
+
class Test:
|
|
77
|
+
"""Test command that demonstrates cappa usage."""
|
|
78
|
+
|
|
79
|
+
name: typing.Annotated[str, cappa.Arg(help="Name to greet")]
|
|
80
|
+
count: typing.Annotated[int, cappa.Arg("-c", help="Times to greet")] = 1
|
|
81
|
+
excited: typing.Annotated[bool, cappa.Arg("--excited", "-e")] = False
|
|
82
|
+
|
|
83
|
+
info = get_info(Test)
|
|
84
|
+
print(info)
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""Module for inspecting Cleo CLI applications."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from cleo.application import Application
|
|
6
|
+
from cleo.commands.command import Command
|
|
7
|
+
|
|
8
|
+
from clinspector.models import commandinfo, param
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def _parse_command(command: Command) -> commandinfo.CommandInfo:
|
|
12
|
+
"""Parse a Cleo Command into a CommandInfo object."""
|
|
13
|
+
# Get definition object which contains argument/option configurations
|
|
14
|
+
definition = command.definition
|
|
15
|
+
# Parse arguments
|
|
16
|
+
params = [
|
|
17
|
+
param.Param(
|
|
18
|
+
name=argument.name,
|
|
19
|
+
help=argument.description,
|
|
20
|
+
default=argument.default,
|
|
21
|
+
required=argument._required,
|
|
22
|
+
param_type_name="argument",
|
|
23
|
+
multiple=argument._is_list,
|
|
24
|
+
)
|
|
25
|
+
for argument in definition.arguments
|
|
26
|
+
] + [
|
|
27
|
+
param.Param(
|
|
28
|
+
name=option.name,
|
|
29
|
+
help=option.description,
|
|
30
|
+
default=option.default,
|
|
31
|
+
opts=[f"--{option.name}"]
|
|
32
|
+
+ ([f"-{option.shortcut}"] if option.shortcut else []),
|
|
33
|
+
# required=option.required,
|
|
34
|
+
is_flag=option._flag,
|
|
35
|
+
multiple=option._is_list,
|
|
36
|
+
param_type_name="option",
|
|
37
|
+
)
|
|
38
|
+
for option in definition.options
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
return commandinfo.CommandInfo(
|
|
42
|
+
name=command.name or "",
|
|
43
|
+
description=command.description,
|
|
44
|
+
# usage=command._synopsis,
|
|
45
|
+
params=params,
|
|
46
|
+
hidden=command.hidden,
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def parse(app: Application) -> commandinfo.CommandInfo:
|
|
51
|
+
"""Parse a Cleo Application into a CommandInfo object."""
|
|
52
|
+
# Get the default command (usually "list")
|
|
53
|
+
default_cmd_name = app._default_command
|
|
54
|
+
default_cmd = app._commands[default_cmd_name] # Get actual command object
|
|
55
|
+
|
|
56
|
+
# Build subcommands dict
|
|
57
|
+
subcommands = {
|
|
58
|
+
name: _parse_command(cmd)
|
|
59
|
+
for name, cmd in app._commands.items()
|
|
60
|
+
if name != default_cmd_name
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
return commandinfo.CommandInfo(
|
|
64
|
+
name=app.name or "",
|
|
65
|
+
description=app.long_version or "",
|
|
66
|
+
# usage=app.definition, # TODO
|
|
67
|
+
subcommands=subcommands,
|
|
68
|
+
params=_parse_command(default_cmd).params,
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def get_info(
|
|
73
|
+
instance: Application,
|
|
74
|
+
command: str | None = None,
|
|
75
|
+
) -> commandinfo.CommandInfo:
|
|
76
|
+
"""Return a CommandInfo object for command of given Cleo Application.
|
|
77
|
+
|
|
78
|
+
Args:
|
|
79
|
+
instance: A Cleo Application instance
|
|
80
|
+
command: The command to get info for
|
|
81
|
+
"""
|
|
82
|
+
info = parse(instance)
|
|
83
|
+
if command:
|
|
84
|
+
return info.subcommands.get(command, info)
|
|
85
|
+
return info
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
if __name__ == "__main__":
|
|
89
|
+
import typing
|
|
90
|
+
|
|
91
|
+
from cleo.helpers import argument, option
|
|
92
|
+
|
|
93
|
+
# Example usage with a simple Cleo application
|
|
94
|
+
class GreetCommand(Command):
|
|
95
|
+
name = "greet"
|
|
96
|
+
description = "Greets someone"
|
|
97
|
+
arguments: typing.ClassVar = [
|
|
98
|
+
argument("name", description="Who do you want to greet?", optional=True)
|
|
99
|
+
]
|
|
100
|
+
options: typing.ClassVar = [
|
|
101
|
+
option(
|
|
102
|
+
"yell",
|
|
103
|
+
"y",
|
|
104
|
+
description="If set, the task will yell in uppercase letters",
|
|
105
|
+
flag=True,
|
|
106
|
+
)
|
|
107
|
+
]
|
|
108
|
+
|
|
109
|
+
def handle(self):
|
|
110
|
+
name = self.argument("name")
|
|
111
|
+
text = f"Hello {name}" if name else "Hello"
|
|
112
|
+
if self.option("yell"):
|
|
113
|
+
text = text.upper()
|
|
114
|
+
self.line(text)
|
|
115
|
+
|
|
116
|
+
app = Application()
|
|
117
|
+
app.add(GreetCommand())
|
|
118
|
+
|
|
119
|
+
info = get_info(app)
|
|
120
|
+
print(info)
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import click
|
|
4
|
+
|
|
5
|
+
from clinspector.models import commandinfo, param
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def parse(
|
|
9
|
+
command: click.Command,
|
|
10
|
+
parent: click.Context | None = None,
|
|
11
|
+
) -> commandinfo.CommandInfo:
|
|
12
|
+
"""Get a `CommandInfo` dataclass for given click `Command`.
|
|
13
|
+
|
|
14
|
+
Args:
|
|
15
|
+
command: The **click** `Command` to get info for.
|
|
16
|
+
parent: The optional parent context
|
|
17
|
+
"""
|
|
18
|
+
import click
|
|
19
|
+
|
|
20
|
+
ctx = click.Context(command, parent=parent)
|
|
21
|
+
subcommands = getattr(command, "commands", {})
|
|
22
|
+
dct = ctx.command.to_info_dict(ctx)
|
|
23
|
+
formatter = ctx.make_formatter()
|
|
24
|
+
pieces = ctx.command.collect_usage_pieces(ctx)
|
|
25
|
+
formatter.write_usage(ctx.command_path, " ".join(pieces), prefix="")
|
|
26
|
+
usage = formatter.getvalue().rstrip("\n")
|
|
27
|
+
# Generate the full usage string based on parents if any, i.e. `root sub1 sub2 ...`.
|
|
28
|
+
full_path = []
|
|
29
|
+
current: click.Context | None = ctx
|
|
30
|
+
while current is not None:
|
|
31
|
+
name = current.command.name.lower() if current.command.name else ""
|
|
32
|
+
full_path.append(name)
|
|
33
|
+
current = current.parent
|
|
34
|
+
full_path.reverse()
|
|
35
|
+
return commandinfo.CommandInfo(
|
|
36
|
+
name=ctx.command.name or "",
|
|
37
|
+
description=ctx.command.help or ctx.command.short_help or "",
|
|
38
|
+
usage=" ".join(full_path) + usage,
|
|
39
|
+
params=[param.Param(**i) for i in dct["params"]],
|
|
40
|
+
subcommands={k: parse(v, parent=ctx) for k, v in subcommands.items()},
|
|
41
|
+
deprecated=dct["deprecated"],
|
|
42
|
+
epilog=dct["epilog"],
|
|
43
|
+
hidden=dct["hidden"],
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def get_info(
|
|
48
|
+
instance: click.Group,
|
|
49
|
+
command: str | None = None,
|
|
50
|
+
) -> commandinfo.CommandInfo:
|
|
51
|
+
"""Return a `CommmandInfo` object for command of given click Group.
|
|
52
|
+
|
|
53
|
+
Args:
|
|
54
|
+
instance: A `Typer`, **click** `Group` or `ArgumentParser` instance
|
|
55
|
+
command: The command to get info for.
|
|
56
|
+
"""
|
|
57
|
+
info = parse(instance)
|
|
58
|
+
if command:
|
|
59
|
+
ctx = click.Context(instance)
|
|
60
|
+
subcommands = getattr(instance, "commands", {})
|
|
61
|
+
cmds = {k: parse(v, parent=ctx) for k, v in subcommands.items()}
|
|
62
|
+
return cmds.get(command, info)
|
|
63
|
+
return info
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
if __name__ == "__main__":
|
|
67
|
+
import mkdocs.__main__
|
|
68
|
+
|
|
69
|
+
info = get_info(mkdocs.__main__.cli, command="mkdocs")
|
|
70
|
+
print(info)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import TYPE_CHECKING
|
|
4
|
+
|
|
5
|
+
import typer
|
|
6
|
+
from typer.main import get_command
|
|
7
|
+
|
|
8
|
+
from clinspector.introspect import introspect_click
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
if TYPE_CHECKING:
|
|
12
|
+
from clinspector.models import commandinfo
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def get_info(
|
|
16
|
+
instance: typer.Typer,
|
|
17
|
+
command: str | None = None,
|
|
18
|
+
) -> commandinfo.CommandInfo:
|
|
19
|
+
"""Return a `CommmandInfo` object for command of given Typer object.
|
|
20
|
+
|
|
21
|
+
Args:
|
|
22
|
+
instance: A `Typer`, **click** `Group` or `ArgumentParser` instance
|
|
23
|
+
command: The command to get info for.
|
|
24
|
+
"""
|
|
25
|
+
cmd = get_command(instance)
|
|
26
|
+
info = introspect_click.parse(cmd)
|
|
27
|
+
if command:
|
|
28
|
+
ctx = typer.Context(cmd)
|
|
29
|
+
subcommands = getattr(cmd, "commands", {})
|
|
30
|
+
cmds = {k: introspect_click.parse(v, parent=ctx) for k, v in subcommands.items()}
|
|
31
|
+
return cmds.get(command, info)
|
|
32
|
+
return info
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
if __name__ == "__main__":
|
|
36
|
+
from mkdocs_mknodes import cli
|
|
37
|
+
|
|
38
|
+
info = get_info(cli.cli, command="mkdocs")
|
|
39
|
+
print(info)
|
|
File without changes
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import dataclasses
|
|
4
|
+
from typing import TYPE_CHECKING
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
if TYPE_CHECKING:
|
|
8
|
+
from clinspector.models import param
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@dataclasses.dataclass(frozen=True)
|
|
12
|
+
class CommandInfo:
|
|
13
|
+
name: str
|
|
14
|
+
"""The name of the command."""
|
|
15
|
+
description: str = ""
|
|
16
|
+
"""A description for this command."""
|
|
17
|
+
usage: str = ""
|
|
18
|
+
"""A formatted string containing a formatted "usage string" (placeholder example)"""
|
|
19
|
+
subcommands: dict[str, CommandInfo] = dataclasses.field(default_factory=dict)
|
|
20
|
+
"""A command-name->CommandInfo mapping containing all subcommands."""
|
|
21
|
+
deprecated: bool = False
|
|
22
|
+
"""Whether this command is deprecated."""
|
|
23
|
+
epilog: str | None = None
|
|
24
|
+
"""Epilog for this command."""
|
|
25
|
+
hidden: bool = False
|
|
26
|
+
"""Whether this command is hidden."""
|
|
27
|
+
params: list[param.Param] = dataclasses.field(default_factory=list)
|
|
28
|
+
"""A list of Params for this command."""
|
|
29
|
+
|
|
30
|
+
def __getitem__(self, name: str) -> CommandInfo:
|
|
31
|
+
return self.subcommands[name]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
if __name__ == "__main__":
|
|
35
|
+
from pprint import pprint
|
|
36
|
+
|
|
37
|
+
info = CommandInfo("A", "B", "C")
|
|
38
|
+
pprint(info)
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import dataclasses
|
|
4
|
+
from typing import TYPE_CHECKING, Any, Literal
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
if TYPE_CHECKING:
|
|
8
|
+
from collections.abc import Callable
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@dataclasses.dataclass(frozen=True)
|
|
12
|
+
class Param:
|
|
13
|
+
count: bool = False
|
|
14
|
+
"""Whether the parameter increments an integer."""
|
|
15
|
+
default: Any = None
|
|
16
|
+
"""The default value of the parameter."""
|
|
17
|
+
envvar: str | None = None
|
|
18
|
+
""" the environment variable name for this parameter."""
|
|
19
|
+
flag_value: bool = False
|
|
20
|
+
""" Value used for this flag if enabled."""
|
|
21
|
+
help: str | None = None
|
|
22
|
+
"""A formatted help text for this parameter."""
|
|
23
|
+
hidden: bool = False
|
|
24
|
+
"""Whether this parameter is hidden."""
|
|
25
|
+
is_flag: bool = False
|
|
26
|
+
"""Whether the parameter is a flag."""
|
|
27
|
+
multiple: bool = False
|
|
28
|
+
"""Whether the parameter is accepted multiple times and recorded."""
|
|
29
|
+
name: str = ""
|
|
30
|
+
"""The name of this parameter."""
|
|
31
|
+
nargs: int | str | None = 1
|
|
32
|
+
"""The number of arguments this parameter matches. (Argparse may return * / ?)"""
|
|
33
|
+
opts: list[str] = dataclasses.field(default_factory=list)
|
|
34
|
+
"""Options for this parameter."""
|
|
35
|
+
param_type_name: Literal["option", "parameter", "argument"] = "option"
|
|
36
|
+
"""The type of the parameter."""
|
|
37
|
+
prompt: Any = None
|
|
38
|
+
"""Whether user is prompted for this parameter."""
|
|
39
|
+
required: bool = False
|
|
40
|
+
"""Whether the parameter is required."""
|
|
41
|
+
secondary_opts: list[str] = dataclasses.field(default_factory=list)
|
|
42
|
+
"""Secondary options for this parameter."""
|
|
43
|
+
type: dict[str, str] | None = None
|
|
44
|
+
"""The type object of the parameter."""
|
|
45
|
+
callback: Callable[[Any], Any] | None = None
|
|
46
|
+
"""A method to further process the value after type conversion."""
|
|
47
|
+
expose_value: str = ""
|
|
48
|
+
"""Whether value is passed onwards to the command callback and stored in context."""
|
|
49
|
+
is_eager: bool = False
|
|
50
|
+
"""Whether the param is eager."""
|
|
51
|
+
metavar: str | None = None
|
|
52
|
+
"""How value is represented in the help page."""
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def opt_str(self) -> str:
|
|
56
|
+
"""A formatted and sorted string containing the the options."""
|
|
57
|
+
return ", ".join(f"`{i}`" for i in reversed(self.opts))
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
if __name__ == "__main__":
|
|
61
|
+
from pprint import pprint
|
|
62
|
+
|
|
63
|
+
info = Param(name="test")
|
|
64
|
+
pprint(info)
|
clinspector/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: clinspector
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A library to parse CLI output into structured data.
|
|
5
|
+
Project-URL: Documentation, https://phil65.github.io/clinspector/
|
|
6
|
+
Project-URL: Source, https://github.com/phil65/clinspector
|
|
7
|
+
Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2024, Philipp Temminghoff
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
|
|
30
|
+
Classifier: Development Status :: 4 - Beta
|
|
31
|
+
Classifier: Intended Audience :: Developers
|
|
32
|
+
Classifier: Operating System :: OS Independent
|
|
33
|
+
Classifier: Programming Language :: Python :: 3
|
|
34
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
35
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
38
|
+
Classifier: Topic :: Documentation
|
|
39
|
+
Classifier: Topic :: Software Development
|
|
40
|
+
Classifier: Topic :: Utilities
|
|
41
|
+
Classifier: Typing :: Typed
|
|
42
|
+
Requires-Python: >=3.12
|
|
43
|
+
Requires-Dist: pyparsing
|
|
44
|
+
Provides-Extra: all
|
|
45
|
+
Requires-Dist: cappa; extra == 'all'
|
|
46
|
+
Requires-Dist: cleo; extra == 'all'
|
|
47
|
+
Requires-Dist: click; extra == 'all'
|
|
48
|
+
Requires-Dist: typer; extra == 'all'
|
|
49
|
+
Provides-Extra: cappa
|
|
50
|
+
Requires-Dist: cappa; extra == 'cappa'
|
|
51
|
+
Provides-Extra: cleo
|
|
52
|
+
Requires-Dist: cleo; extra == 'cleo'
|
|
53
|
+
Provides-Extra: click
|
|
54
|
+
Requires-Dist: click; extra == 'click'
|
|
55
|
+
Provides-Extra: typer
|
|
56
|
+
Requires-Dist: typer; extra == 'typer'
|
|
57
|
+
Description-Content-Type: text/markdown
|
|
58
|
+
|
|
59
|
+
# CLInspector
|
|
60
|
+
|
|
61
|
+
[](https://pypi.org/project/clinspector/)
|
|
62
|
+
[](https://pypi.org/project/clinspector/)
|
|
63
|
+
[](https://pypi.org/project/clinspector/)
|
|
64
|
+
[](https://pypi.org/project/clinspector/)
|
|
65
|
+
[](https://pypi.org/project/clinspector/)
|
|
66
|
+
[](https://pypi.org/project/clinspector/)
|
|
67
|
+
[](https://pypi.org/project/clinspector/)
|
|
68
|
+
[](https://pypi.org/project/clinspector/)
|
|
69
|
+
[](https://pypi.org/project/clinspector/)
|
|
70
|
+
[](https://github.com/phil65/clinspector/releases)
|
|
71
|
+
[](https://github.com/phil65/clinspector/graphs/contributors)
|
|
72
|
+
[](https://github.com/phil65/clinspector/discussions)
|
|
73
|
+
[](https://github.com/phil65/clinspector/forks)
|
|
74
|
+
[](https://github.com/phil65/clinspector/issues)
|
|
75
|
+
[](https://github.com/phil65/clinspector/pulls)
|
|
76
|
+
[](https://github.com/phil65/clinspector/watchers)
|
|
77
|
+
[](https://github.com/phil65/clinspector/stars)
|
|
78
|
+
[](https://github.com/phil65/clinspector)
|
|
79
|
+
[](https://github.com/phil65/clinspector/commits)
|
|
80
|
+
[](https://github.com/phil65/clinspector/releases)
|
|
81
|
+
[](https://github.com/phil65/clinspector)
|
|
82
|
+
[](https://github.com/phil65/clinspector)
|
|
83
|
+
[](https://github.com/phil65/clinspector)
|
|
84
|
+
[](https://github.com/phil65/clinspector)
|
|
85
|
+
[](https://codecov.io/gh/phil65/clinspector/)
|
|
86
|
+
[](https://github.com/psf/black)
|
|
87
|
+
[](https://pyup.io/repos/github/phil65/clinspector/)
|
|
88
|
+
|
|
89
|
+
[Read the documentation!](https://phil65.github.io/clinspector/)
|
|
90
|
+
|
|
91
|
+
# CLInspector Documentation
|
|
92
|
+
|
|
93
|
+
CLInspector is a library to introspect Python CLI applications and extract their command structure and parameters programmatically.
|
|
94
|
+
|
|
95
|
+
## Usage
|
|
96
|
+
|
|
97
|
+
The main entry point is the `get_cmd_info()` function which analyzes a CLI application instance and returns a structured `CommandInfo` object:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
from clinspector import get_cmd_info
|
|
101
|
+
|
|
102
|
+
command_info = get_cmd_info(cli_instance)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The function accepts CLI application instances from the following frameworks:
|
|
106
|
+
|
|
107
|
+
- [Typer](https://typer.tiangolo.com/) - `typer.Typer` instances
|
|
108
|
+
- [Click](https://click.palletsprojects.com/) - `click.Group` instances
|
|
109
|
+
- [Cleo](https://cleo.readthedocs.io/) - `cleo.Application` instances
|
|
110
|
+
- [Cappa](https://github.com/DynamicArray/Cappa) - Classes decorated with `@cappa.command`
|
|
111
|
+
- [argparse](https://docs.python.org/3/library/argparse.html) - `ArgumentParser` instances
|
|
112
|
+
|
|
113
|
+
The extracted information is returned as a `CommandInfo` object containing:
|
|
114
|
+
|
|
115
|
+
### CommandInfo Fields
|
|
116
|
+
|
|
117
|
+
- `name: str` - Name of the command
|
|
118
|
+
- `description: str` - Description/help text
|
|
119
|
+
- `usage: str` - Formatted usage string
|
|
120
|
+
- `subcommands: dict[str, CommandInfo]` - Nested subcommands
|
|
121
|
+
- `deprecated: bool` - Whether command is marked as deprecated
|
|
122
|
+
- `epilog: str | None` - Optional epilog text
|
|
123
|
+
- `hidden: bool` - Whether command is hidden
|
|
124
|
+
- `params: list[Param]` - List of command parameters
|
|
125
|
+
|
|
126
|
+
### Param Fields
|
|
127
|
+
|
|
128
|
+
- `name: str` - Parameter name
|
|
129
|
+
- `help: str | None` - Help text
|
|
130
|
+
- `default: Any` - Default value
|
|
131
|
+
- `opts: list[str]` - Parameter options (e.g. `["-f", "--flag"]`)
|
|
132
|
+
- `required: bool` - Whether parameter is required
|
|
133
|
+
- `is_flag: bool` - Whether parameter is a flag
|
|
134
|
+
- `multiple: bool` - Whether parameter accepts multiple values
|
|
135
|
+
- `nargs: int | str | None` - Number of arguments accepted
|
|
136
|
+
- `envvar: str | None` - Environment variable name
|
|
137
|
+
- `hidden: bool` - Whether parameter is hidden
|
|
138
|
+
- `param_type_name: Literal["option", "parameter", "argument"]` - Parameter type
|
|
139
|
+
- `type: dict[str, str] | None` - Parameter type information
|
|
140
|
+
- `metavar: str | None` - Display name in help text
|
|
141
|
+
|
|
142
|
+
You can access subcommands using dictionary syntax:
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
# Get info for "build" subcommand
|
|
146
|
+
build_info = command_info["build"]
|
|
147
|
+
|
|
148
|
+
# Access nested subcommand
|
|
149
|
+
nested_info = command_info["group"]["subcommand"]
|
|
150
|
+
```
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The extracted information allows you to:
|
|
154
|
+
|
|
155
|
+
- Generate documentation automatically
|
|
156
|
+
- Build command completion
|
|
157
|
+
- Create wrappers and adapters
|
|
158
|
+
- Perform static analysis of CLI interfaces
|
|
159
|
+
- And more!
|
|
160
|
+
|
|
161
|
+
Example output for a click command:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
CommandInfo(
|
|
165
|
+
name="cli",
|
|
166
|
+
description="Example CLI tool",
|
|
167
|
+
usage="cli [OPTIONS] COMMAND [ARGS]...",
|
|
168
|
+
params=[
|
|
169
|
+
Param(name="verbose", help="Enable verbose output", opts=["-v", "--verbose"])
|
|
170
|
+
],
|
|
171
|
+
subcommands={
|
|
172
|
+
"build": CommandInfo(
|
|
173
|
+
name="build",
|
|
174
|
+
description="Build the project",
|
|
175
|
+
params=[...]
|
|
176
|
+
)
|
|
177
|
+
}
|
|
178
|
+
)
|
|
179
|
+
```
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
clinspector/__init__.py,sha256=DWOPoo0z8WiNcr8i4St1_equGS-q3YzGRVVl7tNwj1s,104
|
|
2
|
+
clinspector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
+
clinspector/introspect/__init__.py,sha256=lvn-RvYRBf59RFMG0dxfkS5brRHw2wcBj-TQf-60UJg,1678
|
|
4
|
+
clinspector/introspect/introspect_argparse.py,sha256=fAAPuVVaU_aQJGcbxs3gomGjNgvmgH3jCUTnNIASed4,1850
|
|
5
|
+
clinspector/introspect/introspect_cappa.py,sha256=Yk__74AqNF37D-MXQWd0ils0eQaj_wRwcjAKVsvbbdQ,2316
|
|
6
|
+
clinspector/introspect/introspect_cleo.py,sha256=uD0Uxa7TNveKBtUI65-MgljieAY1fbksWurWcrFG0ok,3601
|
|
7
|
+
clinspector/introspect/introspect_click.py,sha256=bAOZLBD9TflacyQp89YefQNF9iyPzw1LtLv_69v1TYc,2316
|
|
8
|
+
clinspector/introspect/introspect_typer.py,sha256=4X0-FUrq9uJBtCxzOcfsDv2vyCd0FMorZpE2jQhRVb4,1040
|
|
9
|
+
clinspector/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
10
|
+
clinspector/models/commandinfo.py,sha256=_dxxMD0DGOjcOAA7c6CnqsuO6kEjsy0sUgNkO6eMSlc,1157
|
|
11
|
+
clinspector/models/param.py,sha256=8o6CmQYx4A3Qi-w2FR5DRSIJOny5gStryj-JTisxQQc,2326
|
|
12
|
+
clinspector-0.1.0.dist-info/METADATA,sha256=zTCPK-izX7wvMCFda28Yf4Dlp8OBykCFXUCNU51mVsM,8923
|
|
13
|
+
clinspector-0.1.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
|
|
14
|
+
clinspector-0.1.0.dist-info/entry_points.txt,sha256=WEe4bt7kPJ0DtI6z7icepxCcBMeo-LPGIEjlqacHgx8,180
|
|
15
|
+
clinspector-0.1.0.dist-info/licenses/LICENSE,sha256=AteGCH9r177TxxrOFEiOARrastASsf7yW6MQxlAHdwA,1078
|
|
16
|
+
clinspector-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024, Philipp Temminghoff
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|