pyhanko-cli 0.1.0__py3-none-any.whl

pyhanko/cli/plugin_api.py

@@ -0,0 +1,118 @@
+import abc
+from typing import ClassVar, ContextManager, List, Optional
+
+import click
+from pyhanko.cli._ctx import CLIContext
+from pyhanko.sign import Signer
+
+__all__ = [
+    'SigningCommandPlugin',
+    'register_signing_plugin',
+    'CLIContext',
+    'SIGNING_PLUGIN_REGISTRY',
+    'SIGNING_PLUGIN_ENTRY_POINT_GROUP',
+]
+
+
+class SigningCommandPlugin(abc.ABC):
+    """
+
+    .. versionadded:: 0.18.0
+
+    Interface for integrating custom, user-supplied
+    signers into the pyHanko CLI as subcommands of ``addsig``.
+
+    Implementations are discovered through the ``pyhanko.cli_plugin.signing``
+    package entry point. Such entry points can be registered in
+    ``pyproject.toml`` as follows:
+
+    .. code-block:: toml
+
+       [project.entry-points."pyhanko.cli_plugin.signing"]
+       your_plugin = "some_package.path.to.module:SomePluginClass"
+
+    Subclasses exposed as entry points are required to have a no-arguments
+    ``__init__`` method.
+
+    .. warning::
+        This is an incubating feature. API adjustments are still possible.
+
+    .. warning::
+        Plugin support requires Python 3.8 or later.
+    """
+
+    subcommand_name: ClassVar[str]
+    """
+    The name of the subcommand for the plugin.
+    """
+
+    help_summary: ClassVar[str]
+    """
+    A short description of the plugin for use in the ``--help`` output.
+    """
+
+    unavailable_message: ClassVar[Optional[str]] = None
+    """
+    Message to display if the plugin is unavailable.
+    """
+
+    def click_options(self) -> List[click.Option]:
+        """
+        The list of ``click`` options for your custom command.
+        """
+        raise NotImplementedError
+
+    def click_extra_arguments(self) -> List[click.Argument]:
+        """
+        The list of ``click`` arguments for your custom command.
+        """
+        return []
+
+    def is_available(self) -> bool:
+        """
+        A hook to determine whether your plugin is available
+        or not (e.g. based on the availability of certain dependencies).
+        This should not depend on the pyHanko configuration, but may query
+        system information in other ways as appropriate.
+
+        The default is to always report the plugin as available.
+
+        :return:
+            return ``True`` if the plugin is available, else ``False``
+        """
+        return True
+
+    def create_signer(
+        self, context: CLIContext, **kwargs
+    ) -> ContextManager[Signer]:
+        """
+        Instantiate a context manager that creates and potentially
+        also implements a deallocator for a :class:`.Signer` object.
+
+        :param context:
+            The active :class:`.CLIContext`.
+        :param kwargs:
+            All keyword arguments processed by ``click`` through the CLI,
+            resulting from :meth:`click_options` and
+            :meth:`click_extra_arguments`.
+        :return:
+            A context manager that manages the lifecycle for a :class:`.Signer`.
+        """
+        raise NotImplementedError
+
+
+SIGNING_PLUGIN_REGISTRY: List[SigningCommandPlugin] = []
+SIGNING_PLUGIN_ENTRY_POINT_GROUP = 'pyhanko.cli_plugin.signing'
+
+
+def register_signing_plugin(cls):
+    """
+    Manually put a plugin into the signing plugin registry.
+
+    :param cls:
+        A plugin class.
+    :return:
+        The same class.
+    """
+    SIGNING_PLUGIN_REGISTRY.append(cls())
+    return cls

pyhanko/cli/runtime.py

@@ -0,0 +1,80 @@
+import logging
+import sys
+from contextlib import contextmanager
+
+import click
+from pyhanko.cli.utils import logger
+from pyhanko.config.logging import LogConfig, StdLogOutput
+from pyhanko.pdf_utils import misc
+from pyhanko.pdf_utils.layout import LayoutError
+from pyhanko.sign.general import SigningError
+
+
+class NoStackTraceFormatter(logging.Formatter):
+    def formatException(self, ei) -> str:
+        return ""  # pragma: nocover
+
+
+LOG_FORMAT_STRING = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+
+
+def logging_setup(log_configs, verbose: bool):
+    log_config: LogConfig
+    for module, log_config in log_configs.items():
+        cur_logger = logging.getLogger(module)
+        cur_logger.setLevel(log_config.level)
+        handler: logging.StreamHandler
+        if isinstance(log_config.output, StdLogOutput):
+            if StdLogOutput == StdLogOutput.STDOUT:
+                handler = logging.StreamHandler(sys.stdout)
+            else:
+                handler = logging.StreamHandler()
+            # when logging to the console, don't output stack traces
+            # unless in verbose mode
+            if verbose:
+                formatter = logging.Formatter(LOG_FORMAT_STRING)
+            else:
+                formatter = NoStackTraceFormatter(LOG_FORMAT_STRING)
+        else:
+            handler = logging.FileHandler(log_config.output)
+            formatter = logging.Formatter(LOG_FORMAT_STRING)
+        handler.setFormatter(formatter)
+        cur_logger.addHandler(handler)
+
+
+@contextmanager
+def pyhanko_exception_manager():
+    msg = exception = None
+    try:
+        yield
+    except click.ClickException:
+        raise
+    except misc.PdfStrictReadError as e:
+        exception = e
+        msg = (
+            "Failed to read PDF file in strict mode; rerun with "
+            "--no-strict-syntax to try again.\n"
+            f"Error message: {e.msg}"
+        )
+    except misc.PdfReadError as e:
+        exception = e
+        msg = f"Failed to read PDF file: {e.msg}"
+    except misc.PdfWriteError as e:
+        exception = e
+        msg = f"Failed to write PDF file: {e.msg}"
+    except SigningError as e:
+        exception = e
+        msg = f"Error raised while producing signed file: {e.msg}"
+    except LayoutError as e:
+        exception = e
+        msg = f"Error raised while producing signature layout: {e.msg}"
+    except Exception as e:
+        exception = e
+        msg = "Generic processing error."
+
+    if exception is not None:
+        logger.error(msg, exc_info=exception)
+        raise click.ClickException(msg)
+
+
+DEFAULT_CONFIG_FILE = 'pyhanko.yml'

pyhanko/cli/utils.py

@@ -0,0 +1,68 @@
+import logging
+from typing import Optional, Tuple
+
+import click
+from pyhanko.sign import fields
+
+logger = logging.getLogger("cli")
+
+
+def _warn_empty_passphrase():
+    click.echo(
+        click.style(
+            "WARNING: passphrase is empty. If you intended to use an "
+            "unencrypted private key, use --no-pass instead.",
+            bold=True,
+        )
+    )
+
+
+readable_file = click.Path(exists=True, readable=True, dir_okay=False)
+writable_file = click.Path(writable=True, dir_okay=False)
+
+
+def _index_page(page):
+    try:
+        page_ix = int(page)
+        if not page_ix:
+            raise ValueError
+        if page_ix > 0:
+            # subtract 1 from the total, since that's what people expect
+            # when referring to a page index
+            return page_ix - 1
+        else:
+            # keep negative indexes as-is.
+            return page_ix
+    except ValueError:
+        raise click.ClickException(
+            "Sig field parameter PAGE should be a nonzero integer, "
+            "not %s." % page
+        )
+
+
+def parse_field_location_spec(
+    spec: str, require_full_spec: bool = True
+) -> Tuple[str, Optional[fields.SigFieldSpec]]:
+    try:
+        page, box, name = spec.split('/')
+    except ValueError:
+        if require_full_spec:
+            raise click.ClickException(
+                "Sig field spec should be of the form PAGE/X1,Y1,X2,Y2/NAME."
+            )
+        else:
+            # interpret the entire string as a field name
+            return spec, None
+
+    page_ix = _index_page(page)
+
+    try:
+        x1, y1, x2, y2 = map(int, box.split(','))
+    except ValueError:
+        raise click.ClickException(
+            "Sig field parameters X1,Y1,X2,Y2 should be four integers."
+        )
+
+    return name, fields.SigFieldSpec(
+        sig_field_name=name, on_page=page_ix, box=(x1, y1, x2, y2)
+    )

pyhanko/cli/version.py

@@ -0,0 +1,2 @@
+__version__ = '0.1.0'
+__version_info__ = (0, 1, 0)

pyhanko_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: pyhanko-cli
+Version: 0.1.0
+Summary: CLI tools for stamping and signing PDF files
+Author-email: Matthias Valvekens <dev@mvalvekens.be>
+Maintainer-email: Matthias Valvekens <dev@mvalvekens.be>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MatthiasValvekens/pyHanko
+Project-URL: Documentation, https://pyhanko.readthedocs.io/
+Project-URL: Changes, https://pyhanko.readthedocs.io/en/latest/changelog.html
+Project-URL: Source Code, https://github.com/MatthiasValvekens/pyHanko
+Project-URL: Issue Tracker, https://github.com/MatthiasValvekens/pyHanko/issues
+Keywords: signature,pdf,pades,digital-signature,pkcs11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asn1crypto>=1.5.1
+Requires-Dist: tzlocal>=4.3
+Requires-Dist: pyhanko<0.30,>=0.29.0
+Requires-Dist: pyhanko-certvalidator<0.28,>=0.27.0
+Requires-Dist: click<8.2.0,>=8.1.3
+Dynamic: license-file
+
+The lack of open-source CLI tooling to handle digitally signing and stamping PDF files was bothering me, so I went ahead and rolled my own.
+
+### Installing
+
+PyHanko is hosted on [PyPI](https://pypi.org/project/pyHanko/),
+and can be installed using `pip`:
+
+```bash
+pip install pyhanko-cli
+```
+
+### Documentation
+
+The [documentation for pyHanko is hosted on ReadTheDocs](https://pyhanko.readthedocs.io/en/latest/)
+and includes information on CLI usage, library usage, and API reference documentation derived from
+inline docstrings.
+
+
+### Optional features
+
+Optional dependencies are managed at the level of the ``pyhanko`` package.
+
+```bash
+pip install 'pyHanko[pkcs11,image-support,opentype,qr]' pyhanko-cli
+```
+
+Depending on your shell, you might have to leave off the quotes:
+
+```bash
+pip install pyHanko[pkcs11,image-support,opentype,qr] pyhanko-cli
+```
+
+This `pip` invocation includes the optional dependencies required for PKCS#11, image handling,
+OpenType/TrueType support and QR code generation.

pyhanko_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+pyhanko/__main__.py,sha256=r_wpx5NBClHu_Vi6IyBsGeo9HZipV73UzPw3u7vEZos,123
+pyhanko/cli/__init__.py,sha256=W-dXL7Ks_h_f83BydK6DO0Xq1z2vXC7imWns9knvgVA,336
+pyhanko/cli/_ctx.py,sha256=57uPbIEnUdIF8Ev3kTs1925h2kXXjMx-tcrgJS3HGUM,2428
+pyhanko/cli/_root.py,sha256=kMMmFcZ3CyjumtVQQG3FG2OWfzl8dL2mpU8hPaglun8,5424
+pyhanko/cli/_trust.py,sha256=Mb3iuM05AnLvQ7fH1df-TOzTaDk430grHOiSxMR2Cvk,5250
+pyhanko/cli/config.py,sha256=TH604IupVilLrj1mhc59dPfRCcjD-c2jb0tMLWlERxA,10059
+pyhanko/cli/plugin_api.py,sha256=ANFvR4XlhTT7Q8V7zEI2PwfsBnhQv3MYGJW6ssvX2L0,3333
+pyhanko/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyhanko/cli/runtime.py,sha256=YIA9KVGFqtOymrGzgaExmmfTd7nNGBNvsMe5H05QSek,2595
+pyhanko/cli/utils.py,sha256=GPDOibQQ2YqPPz7UG9Z7zsOiihJ22a5oM1CF_q49eNE,1854
+pyhanko/cli/version.py,sha256=Y4LHeOXBqKMcOffQfycAar5j-JEc-ObkXZE04PES0Tw,51
+pyhanko/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyhanko/cli/commands/crypt.py,sha256=wF7qUabC48f1WiPEXNbrewCdWG4_Yjy3XptbCe9CQv8,7433
+pyhanko/cli/commands/fields.py,sha256=__7BfAbqhYw9Om868mM1NKeaOGzBBx8TejaQ-2g5AiY,2118
+pyhanko/cli/commands/stamp.py,sha256=e321axB3qB48vXtIqyEvjRBVFCiG88joK9fbgUfAwuI,2825
+pyhanko/cli/commands/signing/__init__.py,sha256=Qu72Cu9Z3Zxfyqr9D0Vu0YrtPDxwD6aJWLQRX-4XqP8,9083
+pyhanko/cli/commands/signing/pkcs11_cli.py,sha256=2bn9pQXImL_iSiH2lrDulHyL9aY9m2_V09zoWw_-A8w,5509
+pyhanko/cli/commands/signing/plugin.py,sha256=vSNa6cPHIkF9566t_N7908dp1vxtP3c_yjdvQDcXws8,5515
+pyhanko/cli/commands/signing/simple.py,sha256=_vImPQ9Bx83DdPzCBgU0MhErkCn7m16QhEv78K6t_-M,8600
+pyhanko/cli/commands/signing/utils.py,sha256=gTtqVMbTBWiKOuXm_tTpYu3W4bzsDMiQ9ybfi8l29N8,2054
+pyhanko/cli/commands/validation/__init__.py,sha256=b595plA9s5lCNLb9o25MQ-MMdLZGd0ojxJ0GRTQlAlc,43
+pyhanko/cli/commands/validation/ltv.py,sha256=NNGNq-AgO32e4H8sEe914g2gp4AAsL8P0qKV6xEr4sE,3615
+pyhanko/cli/commands/validation/validate.py,sha256=nqAYXAjgY9vFkZliWAriv_i0H8QRzAmKxb_Q_woDgN0,10875
+pyhanko_cli-0.1.0.dist-info/licenses/LICENSE,sha256=ppfnWrKHvGvEiG2mIZiiuZMKYvGtNMGR9Y1VbYYlwGI,1080
+pyhanko_cli-0.1.0.dist-info/METADATA,sha256=VWRqUyVXnSj_gU9DlhuP6l7wLQ6Ga5pmwDzQaLi3_4Y,2504
+pyhanko_cli-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyhanko_cli-0.1.0.dist-info/entry_points.txt,sha256=b0jU5S7K1tkTKcY3pImAO9_bYgha0fr36QZyEb2D8VE,52
+pyhanko_cli-0.1.0.dist-info/top_level.txt,sha256=2Z0D0SOjWu7_9ud976jTS2ZCzzNQlb5QOQ0OVBvZksM,8
+pyhanko_cli-0.1.0.dist-info/RECORD,,

pyhanko_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyhanko_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyhanko = pyhanko.__main__:launch

pyhanko_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2023 Matthias Valvekens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyhanko_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyhanko