edq.clilib.model

  1"""
  2This will look for objects that "look like" CLI tools.
  3A package looks like a CLI package if it has __main__.py and __init__.py files.
  4A module looks like a CLI tool if it has the following functions:
  5 - `def _get_parser() -> argparse.ArgumentParser:`
  6 - `def run_cli(args: argparse.Namespace) -> int:`
  7
  8CLI packages should always have a __main__.py file,
  9even if they only contain other packages.
 10"""
 11
 12import abc
 13import argparse
 14import io
 15import os
 16import typing
 17
 18import edq.util.dirent
 19import edq.util.pyimport
 20
 21class CLIDirent(abc.ABC):
 22    """ A dirent that looks like it is related to a CLI. """
 23
 24    def __init__(self,
 25            path: str,
 26            qualified_name: str,
 27            pymodule: typing.Any,
 28            ) -> None:
 29        self.path: str = path
 30        """
 31        The path for the given dirent.
 32        For a package, this will point to `__init__.py`.
 33        """
 34
 35        self.qualified_name: str = qualified_name
 36        """ The Python qualified path to this object. """
 37
 38        self.pymodule: typing.Any = pymodule
 39        """ The loaded module for the given path. """
 40
 41    def base_name(self) -> str:
 42        """ Get the base (unqualified) name for this dirent. """
 43
 44        return self.qualified_name.split('.')[-1]
 45
 46    @abc.abstractmethod
 47    def get_description(self) -> str:
 48        """ Get the description of this dirent. """
 49
 50    @staticmethod
 51    def from_path(path: str, qualified_name: str = '.') -> typing.Union['CLIDirent', None]:
 52        """ Load a representation of the CLI path (or None if the path is not a CLI dirent). """
 53
 54        path = os.path.abspath(path)
 55
 56        if (not os.path.exists(path)):
 57            return None
 58
 59        base_name = os.path.basename(path)
 60        if (base_name.startswith('__')):
 61            return None
 62
 63        if (os.path.isfile(path)):
 64            return CLIModule.from_path(path, qualified_name = qualified_name)
 65
 66        return CLIPackage.from_path(path, qualified_name = qualified_name)
 67
 68class CLIPackage(CLIDirent):
 69    """
 70    A CLI package.
 71    Must have a `__main__.py` file.
 72    """
 73
 74    def __init__(self,
 75            path: str,
 76            qualified_name: str,
 77            pymodule: typing.Any,
 78            dirents: typing.Union[typing.List[CLIDirent], None] = None,
 79            ) -> None:
 80        super().__init__(path, qualified_name, pymodule)
 81
 82        if (dirents is None):
 83            dirents = []
 84
 85        self.dirents: typing.List[CLIDirent] = dirents
 86        """ Entries within this package. """
 87
 88    def get_description(self) -> str:
 89        if (self.pymodule.__doc__ is None):
 90            return ''
 91
 92        return self.pymodule.__doc__.strip()
 93
 94    @staticmethod
 95    def from_path(path: str, qualified_name: str = '.') -> typing.Union['CLIPackage', None]:
 96        """ Load a representation of the CLI package (or None if the path is not a CLI dirent). """
 97
 98        path = os.path.abspath(path)
 99
100        if (not os.path.isdir(path)):
101            raise ValueError(f"CLI package path does not point to a dir: '{path}'.")
102
103        main_path = os.path.join(path, '__main__.py')
104        if (not os.path.exists(main_path)):
105            return None
106
107        init_path = os.path.join(path, '__init__.py')
108        if (not os.path.exists(init_path)):
109            return None
110
111        try:
112            init_module = edq.util.pyimport.import_path(init_path)
113        except Exception as ex:
114            raise ValueError(f"Failed to import module __init__.py file: '{init_path}'.") from ex
115
116        package = CLIPackage(path, qualified_name, init_module)
117
118        for dirent in sorted(os.listdir(path)):
119            dirent_path = os.path.join(path, dirent)
120
121            dirent_qualified_name = os.path.splitext(dirent)[0]
122            if (qualified_name != '.'):
123                dirent_qualified_name = qualified_name + '.' + dirent_qualified_name
124
125            cli_dirent = CLIDirent.from_path(dirent_path, dirent_qualified_name)
126            if (cli_dirent is not None):
127                package.dirents.append(cli_dirent)
128
129        return package
130
131class CLIModule(CLIDirent):
132    """
133    A CLI module.
134    Must have the following functions:
135     - `def _get_parser() -> argparse.ArgumentParser:`
136     - `def run_cli(args: argparse.Namespace) -> int:`
137    """
138
139    def __init__(self,
140            path: str,
141            qualified_name: str,
142            pymodule: typing.Any,
143            parser: argparse.ArgumentParser,
144            ) -> None:
145        super().__init__(path, qualified_name, pymodule)
146
147        self.parser: argparse.ArgumentParser = parser
148        """ The argument parser for this CLI module. """
149
150    def get_description(self) -> str:
151        if (self.parser.description is None):
152            return ''
153
154        return self.parser.description
155
156    def get_help_text(self) -> str:
157        """ Get the help text from the parser. """
158
159        buffer = io.StringIO()
160        self.parser.print_help(file = buffer)
161        text = buffer.getvalue()
162        buffer.close()
163
164        return text
165
166    def get_usage_text(self) -> str:
167        """ Get the help text from the parser. """
168
169        buffer = io.StringIO()
170        self.parser.print_usage(file = buffer)
171        text = buffer.getvalue()
172        buffer.close()
173
174        return text
175
176    @staticmethod
177    def from_path(path: str, qualified_name: str = '.') -> typing.Union['CLIModule', None]:
178        """ Load a representation of the CLI module (or None if the path is not a CLI dirent). """
179
180        path = os.path.abspath(path)
181
182        if (not path.endswith('.py')):
183            return None
184
185        if (not os.path.isfile(path)):
186            raise ValueError(f"CLI module path does not point to a file: '{path}'.")
187
188        try:
189            module = edq.util.pyimport.import_path(path)
190        except Exception as ex:
191            raise ValueError(f"Failed to import module: '{path}'.") from ex
192
193        # Check if this looks like a CLI module.
194        if ('_get_parser' not in dir(module)):
195            return None
196
197        parser = module._get_parser()
198        parser.prog = 'python3 -m ' + qualified_name
199
200        return CLIModule(path, qualified_name, module, parser)