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.
@@ -0,0 +1,5 @@
1
+ __version__ = "0.1.0"
2
+
3
+ from clinspector.introspect import get_cmd_info
4
+
5
+ __all__ = ["get_cmd_info"]
@@ -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
+ [![PyPI License](https://img.shields.io/pypi/l/clinspector.svg)](https://pypi.org/project/clinspector/)
62
+ [![Package status](https://img.shields.io/pypi/status/clinspector.svg)](https://pypi.org/project/clinspector/)
63
+ [![Daily downloads](https://img.shields.io/pypi/dd/clinspector.svg)](https://pypi.org/project/clinspector/)
64
+ [![Weekly downloads](https://img.shields.io/pypi/dw/clinspector.svg)](https://pypi.org/project/clinspector/)
65
+ [![Monthly downloads](https://img.shields.io/pypi/dm/clinspector.svg)](https://pypi.org/project/clinspector/)
66
+ [![Distribution format](https://img.shields.io/pypi/format/clinspector.svg)](https://pypi.org/project/clinspector/)
67
+ [![Wheel availability](https://img.shields.io/pypi/wheel/clinspector.svg)](https://pypi.org/project/clinspector/)
68
+ [![Python version](https://img.shields.io/pypi/pyversions/clinspector.svg)](https://pypi.org/project/clinspector/)
69
+ [![Implementation](https://img.shields.io/pypi/implementation/clinspector.svg)](https://pypi.org/project/clinspector/)
70
+ [![Releases](https://img.shields.io/github/downloads/phil65/clinspector/total.svg)](https://github.com/phil65/clinspector/releases)
71
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/clinspector)](https://github.com/phil65/clinspector/graphs/contributors)
72
+ [![Github Discussions](https://img.shields.io/github/discussions/phil65/clinspector)](https://github.com/phil65/clinspector/discussions)
73
+ [![Github Forks](https://img.shields.io/github/forks/phil65/clinspector)](https://github.com/phil65/clinspector/forks)
74
+ [![Github Issues](https://img.shields.io/github/issues/phil65/clinspector)](https://github.com/phil65/clinspector/issues)
75
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/clinspector)](https://github.com/phil65/clinspector/pulls)
76
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/clinspector)](https://github.com/phil65/clinspector/watchers)
77
+ [![Github Stars](https://img.shields.io/github/stars/phil65/clinspector)](https://github.com/phil65/clinspector/stars)
78
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/clinspector)](https://github.com/phil65/clinspector)
79
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/clinspector)](https://github.com/phil65/clinspector/commits)
80
+ [![Github release date](https://img.shields.io/github/release-date/phil65/clinspector)](https://github.com/phil65/clinspector/releases)
81
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/clinspector)](https://github.com/phil65/clinspector)
82
+ [![Github commits this week](https://img.shields.io/github/commit-activity/w/phil65/clinspector)](https://github.com/phil65/clinspector)
83
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/clinspector)](https://github.com/phil65/clinspector)
84
+ [![Github commits this year](https://img.shields.io/github/commit-activity/y/phil65/clinspector)](https://github.com/phil65/clinspector)
85
+ [![Package status](https://codecov.io/gh/phil65/clinspector/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/clinspector/)
86
+ [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
87
+ [![PyUp](https://pyup.io/repos/github/phil65/clinspector/shield.svg)](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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.26.3
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ clinspector_argparse = clinspector.clis.argparse_cli:main
3
+ clinspector_click = clinspector.clis.click_cli:main
4
+ clinspector_typer = clinspector.clis.typer_cli:main
@@ -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
+