python-pdffiller 1.0.0__py3-none-any.whl

pdffiller/__init__.py

@@ -0,0 +1,4 @@
+from pdffiller import cli, const, typing
+from pdffiller._version import __author__, __copyright__, __version__
+
+__all__ = ["__version__", "__copyright__", "__author__", "cli", "typing", "const"]

pdffiller/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from pdffiller.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli.main(sys.argv[1:]))

pdffiller/_version.py

@@ -0,0 +1,6 @@
+__author__ = "Jacques Raphanel"
+__copyright__ = "Copyright 2025 SISMIC"
+__email__ = "jraphanel@sismic.fr"
+__license__ = "MIT"
+__title__ = "pdffiller"
+__version__ = "1.0.0"

pdffiller/cli/args.py

@@ -0,0 +1,28 @@
+import argparse
+
+from pdffiller.cli.command import BaseCommand
+from pdffiller.typing import Any, Optional, Union
+
+
+def add_global_arguments(
+    parser: Union[argparse.ArgumentParser, Any],
+    add_help: bool = True,
+    main_parser: Optional[argparse.ArgumentParser] = None,
+) -> None:
+    """Add global parsers command-line options."""
+    BaseCommand.init_log_file(parser)
+    BaseCommand.init_log_levels(parser)
+
+    if hasattr(parser, "_command"):
+        getattr(parser, "_command").init_formatters(parser)
+    elif main_parser and hasattr(main_parser, "_command"):
+        getattr(main_parser, "_command").init_formatters(parser)
+    if add_help:
+        parser.add_argument(
+            "-h",
+            "--help",
+            dest="help",
+            action="store_true",
+            default=False,
+            help="show this help message and exit",
+        )

pdffiller/cli/boolean_action.py

@@ -0,0 +1,35 @@
+import argparse
+
+from pdffiller.typing import Any, List, Optional, Sequence, Union
+
+
+class BooleanAction(argparse.Action):
+    """Handle --no-xxx --xxx command-line options"""
+
+    def __init__(self, option_strings: Sequence[str], dest: str, **kwargs: Any) -> None:
+        _option_strings: List[str] = []
+        for option_string in option_strings:
+            _option_strings.append(option_string)
+
+            if option_string.startswith("--"):
+                option_string = "--no-" + option_string[2:]
+                _option_strings.append(option_string)
+
+        if kwargs.get("help") is not None and kwargs.get("default") is not None:
+            kwargs["help"] += f" (default: {kwargs['default']})"
+
+        super().__init__(option_strings=_option_strings, dest=dest, nargs=0, **kwargs)
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: Optional[Union[str, Sequence[str]]] = None,
+        option_string: Optional[str] = None,
+    ) -> None:
+        if option_string and option_string in self.option_strings:
+            setattr(namespace, self.dest, not option_string.startswith("--no-"))
+
+    def format_usage(self) -> str:
+        """Get usage message"""
+        return " | ".join(self.option_strings)

pdffiller/cli/cli.py

@@ -0,0 +1,260 @@
+import importlib
+import os
+import pkgutil
+import signal
+import sys
+import textwrap
+import traceback
+from collections import defaultdict
+from difflib import get_close_matches
+from inspect import getmembers
+
+from pdffiller import __version__ as pdffiller_version
+from pdffiller.cli.command import PdfFillerSubCommand
+from pdffiller.cli.exit_codes import (
+    ERROR_COMMAND_NAME,
+    ERROR_ENCOUNTERED,
+    ERROR_GENERAL,
+    ERROR_SIGTERM,
+    ERROR_SUBCOMMAND_NAME,
+    ERROR_UNEXPECTED,
+    SUCCESS,
+    USER_CTRL_BREAK,
+    USER_CTRL_C,
+)
+from pdffiller.exceptions import (
+    AbortExecution,
+    CommandLineError,
+    InvalidCommandNameException,
+    InvalidSubCommandNameException,
+    PdfFillerException,
+)
+from pdffiller.io.colors import init_colorama
+from pdffiller.io.output import cli_out_write, Color, LEVEL_TRACE, PdfFillerOutput
+from pdffiller.typing import Any, Dict, ExitCode, List, Optional
+
+
+class Cli:
+    """A single command of the PdfFiller application, with all the first level commands.
+    Manages the parsing of parameters and delegates functionality to the appropriate
+    command. It can also show the help of the tool.
+    """
+
+    def __init__(self) -> None:
+        self._groups: Dict[str, List[str]] = defaultdict(list)
+        self._commands: Dict[str, Any] = {}
+        init_colorama(sys.stderr)
+
+    def _add_commands(self) -> None:
+        pdffiller_commands_path = os.path.join(
+            os.path.dirname(os.path.abspath(__file__)), "commands"
+        )
+        for module in pkgutil.iter_modules([pdffiller_commands_path]):
+            module_name = module[1]
+            self._add_command(f"pdffiller.cli.commands.{module_name}", module_name)
+
+    def _add_command(
+        self, import_path: str, method_name: str, package: Optional[str] = None
+    ) -> None:
+        try:
+            imported_module = importlib.import_module(import_path)
+            cmd_mapping = getattr(imported_module, "__MAPPING__", {})
+            cb_name = cmd_mapping.get(method_name, method_name)
+            command_wrapper = getattr(imported_module, cb_name)
+            if command_wrapper.doc:
+                name = f"{package}:{method_name}" if package else method_name
+                self._commands[name] = command_wrapper
+                self._groups[command_wrapper.group].append(name)
+            for name, value in getmembers(imported_module):
+                if isinstance(value, PdfFillerSubCommand):
+                    if name.startswith(f"{cb_name}_"):
+                        command_wrapper.add_subcommand(value)
+                    elif name[0] != "_":
+                        raise PdfFillerException(
+                            "The name for the subcommand method should "
+                            "begin with the main command name + '_'. "
+                            f"i.e. {cb_name}_<subcommand_name>"
+                        )
+        except AttributeError as exc:
+            raise PdfFillerException(
+                f"There is no {method_name} method defined in {import_path}"
+            ) from exc
+
+    def _print_similar(self, command: str) -> None:
+        """Looks for similar commands and prints them if found."""
+        output = PdfFillerOutput()
+        matches = get_close_matches(
+            word=command, possibilities=self._commands.keys(), n=5, cutoff=0.75
+        )
+
+        if len(matches) == 0:
+            return
+
+        if len(matches) > 1:
+            output.info("The most similar commands are")
+        else:
+            output.info("The most similar command is")
+
+        for match in matches:
+            output.info(f"    {match}")
+
+        output.writeln("")
+
+    def _output_help_cli(self) -> None:
+        """
+        Prints a summary of all commands.
+        """
+        max_len = max((len(c) for c in self._commands)) + 4
+        line_format = f"{{: <{max_len}}}"
+
+        nb_groups = len(self._groups.items())
+        for group_name, comm_names in sorted(self._groups.items()):
+            if nb_groups != 1 or group_name:
+                cli_out_write("\n" + group_name + " commands", Color.YELLOW)
+            else:
+                cli_out_write("\n")
+            for name in comm_names:
+                # future-proof way to ensure tabular formatting
+                cli_out_write(line_format.format(name), Color.GREEN, endline="")
+
+                # Help will be all the lines up to the first empty one
+                docstring_lines = self._commands[name].doc.split("\n")
+                start = False
+                data: List[str] = []
+                for line in docstring_lines:
+                    line = line.strip()
+                    if not line:
+                        if start:
+                            break
+                        start = True
+                        continue
+                    data.append(line)
+
+                txt = textwrap.fill(" ".join(data), 80, subsequent_indent=" " * (max_len + 2))
+                cli_out_write(txt)
+
+        cli_out_write("")
+        cli_out_write('Type "pdffiller <command> -h" for help', Color.BLUE)
+
+    def run(self, *args: Any) -> ExitCode:
+        """Entry point for executing commands, dispatcher to class
+        methods
+        """
+        output = PdfFillerOutput()
+        self._add_commands()
+        try:
+            command_argument = args[0][0]
+        except IndexError:  # No parameters
+            self._output_help_cli()
+            raise InvalidCommandNameException(None)  # pylint: disable=raise-missing-from
+
+        try:
+            command = self._commands[command_argument]
+        except KeyError:  # No parameters
+            if command_argument in ["--version"]:
+                cli_out_write(
+                    f"pdffiller {pdffiller_version}",
+                    fore=Color.BRIGHT_GREEN,
+                )
+                raise AbortExecution(0)  # pylint: disable=raise-missing-from
+
+            if command_argument in ["-h", "--help"]:
+                self._output_help_cli()
+                raise AbortExecution(0)  # pylint: disable=raise-missing-from
+
+            output.info(
+                f"'{command_argument}' is not a pdffiller command. " "See 'pdffiller --help'."
+            )
+            output.info("")
+            self._print_similar(command_argument)
+            raise InvalidCommandNameException(  # pylint: disable=raise-missing-from
+                command_argument
+            )
+
+        try:
+            command.run(args[0][1:])
+        except Exception as exc:
+            if not isinstance(exc, AbortExecution) and PdfFillerOutput.level_allowed(LEVEL_TRACE):
+                output.trace("\n".join(traceback.format_exception(*sys.exc_info())))
+            raise exc
+        return 0
+
+    @staticmethod
+    def exception_exit_error(exception: Optional[BaseException]) -> ExitCode:
+        """Convert exception into an exit code"""
+        output = PdfFillerOutput()
+        if exception is None:
+            return SUCCESS
+        if isinstance(exception, AbortExecution):
+            return SUCCESS if exception.exitcode == 0 else ERROR_ENCOUNTERED
+        if isinstance(exception, InvalidCommandNameException):
+            return ERROR_COMMAND_NAME
+        if isinstance(exception, InvalidSubCommandNameException):
+            return ERROR_SUBCOMMAND_NAME
+        if isinstance(exception, CommandLineError):
+            output.error(exception.message)
+            return ERROR_UNEXPECTED
+        if isinstance(exception, PdfFillerException):
+            output.error(exception.message)
+            return ERROR_GENERAL
+        if isinstance(exception, SystemExit):
+            if exception.code != 0:
+                output.error(f"Exiting with code: {exception.code}")
+            return ERROR_ENCOUNTERED
+
+        assert isinstance(exception, Exception)
+        output.error(traceback.format_exc())
+        try:
+            msg = str(exception)
+        except Exception:  # pylint: disable=broad-except
+            msg = repr(exception)
+        output.error(msg)
+        return ERROR_UNEXPECTED
+
+
+def main(args: Optional[List[str]] = None) -> ExitCode:
+    """main entry point of the PdfFiller application, using a Command to
+    parse parameters.
+
+    :parameters:
+        :param args: Optional command-line arguments, else `sys.argv` will
+                     be used by default
+
+    :return: One of the following exit code:
+
+    * 0: Success (done)
+    * 1: General PdfFillerException error (done)
+    * 2: Ctrl+C
+    * 3: Ctrl+Break
+    * 4: SIGTERM
+    * 5: Invalid configuration (done)
+    * 6: Unexpected error
+    * 7: Invalid command name
+    * 8: Invalid sub-command name
+    """
+
+    def ctrl_c_handler(_: Any, __: Any) -> None:
+        print("You pressed Ctrl+C!")
+        sys.exit(USER_CTRL_C)
+
+    def sigterm_handler(_: Any, __: Any) -> None:
+        print("Received SIGTERM!")
+        sys.exit(ERROR_SIGTERM)
+
+    def ctrl_break_handler(_: Any, __: Any) -> None:
+        print("You pressed Ctrl+Break!")
+        sys.exit(USER_CTRL_BREAK)
+
+    signal.signal(signal.SIGINT, ctrl_c_handler)
+    signal.signal(signal.SIGTERM, sigterm_handler)
+
+    if sys.platform == "win32":
+        signal.signal(signal.SIGBREAK, ctrl_break_handler)
+
+    cli = Cli()
+    error: ExitCode = SUCCESS
+    try:
+        cli.run(args if args is not None else sys.argv[1:])
+    except BaseException as exc:  # pylint: disable=broad-except
+        error = cli.exception_exit_error(exc)
+    return error

pdffiller/cli/command.py

@@ -0,0 +1,291 @@
+import argparse
+
+from pdffiller.cli.once_argument import OnceArgument
+from pdffiller.cli.smart_formatter import SmartFormatter
+from pdffiller.exceptions import (
+    AbortExecution,
+    InvalidSubCommandNameException,
+    PdfFillerException,
+)
+from pdffiller.io.output import PdfFillerOutput
+from pdffiller.typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    SubParserType,
+    Union,
+)
+
+
+class PdfFillerArgumentParser(argparse.ArgumentParser):
+    """PdfFiller argument parser to support configuration file"""
+
+    _command: "PdfFillerCommand"
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+    def parse_args(  # type: ignore[override] # pylint: disable=arguments-differ
+        self, args: Optional[Sequence[str]] = None
+    ) -> argparse.Namespace:
+        options = super().parse_args(args)
+
+        PdfFillerOutput.define_log_level(options.verbosity)
+        PdfFillerOutput.define_log_output(options.log_file)
+        output = PdfFillerOutput()
+
+        if "help" in options and options.help:
+            self.print_help(output.stream)
+            raise AbortExecution(0)
+
+        return options
+
+
+CommandCallback = Callable[[PdfFillerArgumentParser, Any], Any]
+"""Command callback function.
+:param PdfFillerArgumentParser: Current parser object
+:param Any: Command-line arguments as a list
+:return: Depend on each command.
+"""
+
+SubCommandCallback = Callable[[PdfFillerArgumentParser, argparse.ArgumentParser, Any], Any]
+"""Sub-command callback function.
+:param PdfFillerArgumentParser: Current parser object
+:param argparse.ArgumentParser: The command sub-parser object
+:param Any: Command-line arguments as a list
+:return: Depend on each command.
+"""
+
+FormatterCallback = Callable[[Any], None]
+"""Formatter callback function.
+    :param Dict: Output format keyword with its callback function function
+"""
+
+
+class BaseCommand:
+    """Base PdfFiller command"""
+
+    def __init__(
+        self,
+        name: str,
+        callback: Union[CommandCallback, SubCommandCallback],
+        formatters: Optional[Dict[str, FormatterCallback]] = None,
+    ) -> None:
+        self.formatters: Dict[str, FormatterCallback] = {"text": lambda x: None}
+        self.callback = callback
+        self.callback_name: str = name
+        if formatters:
+            for kind, action in formatters.items():
+                if callable(action):
+                    self.formatters[kind] = action
+                else:
+                    raise PdfFillerException(
+                        f"Invalid formatter for {kind}. The formatter must be" "a valid function"
+                    )
+        if callback.__doc__:
+            self.callback_doc = callback.__doc__
+        else:
+            raise PdfFillerException(
+                f"No documentation string defined for command: '{self.callback_name}'."
+                " PdfFiller commands should provide a documentation string explaining "
+                "its use briefly."
+            )
+
+    @staticmethod
+    def init_log_levels(parser: argparse.ArgumentParser) -> None:
+        """Add verbosity command-line option"""
+        parser.add_argument(
+            "-V",
+            "--verbosity",
+            default="status",
+            metavar="LEVEL",
+            nargs="?",
+            type=str,
+            help="Level of detail of the output. Valid options from less verbose "
+            "to more verbose: -Vquiet, -Verror, -Vwarning, -Vnotice, -Vstatus, "
+            "-V or -Vverbose, -VV or -Vdebug, -VVV or -vtrace",
+        )
+
+    @staticmethod
+    def init_log_file(parser: argparse.ArgumentParser) -> None:
+        """Add output log file command-line option"""
+        parser.add_argument(
+            "-L",
+            "--log-file",
+            metavar="PATH",
+            type=str,
+            help="Send output to PATH instead of stderr.",
+            action=OnceArgument,
+        )
+
+    @property
+    def _help_formatters(self) -> List[str]:
+        """
+        Formatters that are shown as available in help, 'text' formatter
+        should not appear
+        """
+        return [formatter for formatter in self.formatters if formatter != "text"]
+
+    def init_formatters(self, parser: argparse.ArgumentParser) -> None:
+        """Add formatters command-line options."""
+        formatters = self._help_formatters
+        if formatters:
+            parser.add_argument(
+                "-f",
+                "--format",
+                metavar="NAME",
+                action=OnceArgument,
+                help=f"Select the output format: {', '.join(formatters)}",
+            )
+
+    @property
+    def name(self) -> str:
+        """Get action name"""
+        return self.callback_name
+
+    @property
+    def method(self) -> Union[CommandCallback, SubCommandCallback]:
+        """Get action method"""
+        return self.callback
+
+    @property
+    def doc(self) -> str:
+        """Get action help message"""
+        return self.callback_doc
+
+    def _format(self, parser: argparse.ArgumentParser, info: Dict[str, Any], *args: Any) -> None:
+        parser_args, _ = parser.parse_known_args(*args)
+
+        default_format = "text"
+        try:
+            formatarg = parser_args.format or default_format
+        except AttributeError:
+            formatarg = default_format
+
+        try:
+            formatter = self.formatters[formatarg]
+        except KeyError as exc:
+            raise PdfFillerException(
+                f"{formatarg} is not a known format. Supported formatters are: "
+                f"{', '.join(self._help_formatters)}"
+            ) from exc
+
+        formatter(info)
+
+
+class PdfFillerCommand(BaseCommand):
+    """Main PdfFiller command object"""
+
+    def __init__(
+        self,
+        cb: CommandCallback,
+        group: Optional[str] = None,
+        formatters: Optional[Dict[str, FormatterCallback]] = None,
+        callback_name: Optional[str] = None,
+    ) -> None:
+        if not callback_name:
+            callback_name = cb.__name__.replace("_", "-")
+        super().__init__(callback_name, cb, formatters=formatters)
+        self.subcommands: Dict[str, "PdfFillerSubCommand"] = {}
+        self.group_name = group  # or "Other"
+
+    def add_subcommand(self, subcommand: "PdfFillerSubCommand") -> None:
+        """Register new sub-command"""
+        subcommand.set_name(self.callback_name)
+        self.subcommands[subcommand.callback_name] = subcommand
+
+    def _docs(self) -> PdfFillerArgumentParser:
+        parser = PdfFillerArgumentParser(
+            description=self.callback_doc,
+            prog=f"pdffiller {self.callback_name}",
+            formatter_class=SmartFormatter,
+            add_help=False,
+        )
+        return parser
+
+    def run(self, *args: Any) -> None:
+        """Parse and execute requested command"""
+        parser = PdfFillerArgumentParser(
+            description=self.callback_doc,
+            prog=f"pdffiller {self.callback_name}",
+            formatter_class=SmartFormatter,
+            add_help=False,
+        )
+        # pylint: disable=protected-access
+        parser._command = self
+        info = self.callback(parser, *args)
+
+        if not self.subcommands:
+            self._format(parser, info, *args)
+        else:
+            subcommand_parser: SubParserType = parser.add_subparsers(
+                dest="subcommand",
+            )
+            subcommand_parser.required = True
+            try:
+                sub = self.subcommands[args[0][0]]
+            except (KeyError, IndexError):  # display help
+                for sub in self.subcommands.values():
+                    sub.set_parser(subcommand_parser)
+                parser.print_help()
+                raise InvalidSubCommandNameException(  # pylint: disable=raise-missing-from
+                    args[0][0] if len(args[0]) else ""
+                )
+
+            sub.set_parser(subcommand_parser)
+            sub.run(parser, *args)
+
+    @property
+    def group(self) -> Optional[str]:
+        """Gets group name."""
+        return self.group_name
+
+
+class PdfFillerSubCommand(BaseCommand):
+    """PdfFiller sub-command"""
+
+    parser: argparse.ArgumentParser
+
+    def __init__(
+        self,
+        cb: SubCommandCallback,
+        formatters: Optional[Dict[str, FormatterCallback]] = None,
+    ) -> None:
+        super().__init__("", cb, formatters=formatters)
+        self.subcommand_name = cb.__name__.replace("_", "-")
+
+    def run(self, parent_parser: PdfFillerArgumentParser, *args: object) -> None:
+        """Execute the sub-command"""
+        setattr(self.parser, "_command", self)
+        info = self.callback(parent_parser, self.parser, *args)
+        self._format(parent_parser, info, *args)
+
+    def set_name(self, parent_name: str) -> None:
+        """Set sub-command name"""
+        self.callback_name = self.subcommand_name.replace(f"{parent_name}-", "", 1)
+
+    def set_parser(self, subcommand_parser: SubParserType) -> None:
+        """Set the associated parser"""
+        self.parser = subcommand_parser.add_parser(
+            self.callback_name, help=self.callback_doc, add_help=True
+        )
+        self.parser.description = self.callback_doc
+
+
+def pdffiller_command(
+    group: Optional[str],
+    formatters: Optional[Dict[str, FormatterCallback]] = None,
+    name: Optional[str] = None,
+) -> Callable[[CommandCallback], PdfFillerCommand]:
+    """Register a PdfFiller command"""
+    return lambda f: PdfFillerCommand(f, group, formatters=formatters, callback_name=name)
+
+
+def pdffiller_subcommand(
+    formatters: Optional[Dict[str, FormatterCallback]] = None
+) -> Callable[[SubCommandCallback], PdfFillerSubCommand]:
+    """Register a PdfFiller sub-command"""
+    return lambda f: PdfFillerSubCommand(f, formatters=formatters)