pyhanko.cli package


pyhanko.cli.config module

class pyhanko.cli.config.CLIConfig(validation_contexts: Dict[str, dict], stamp_styles: Dict[str, dict], default_validation_context: str, default_stamp_style: str, time_tolerance: timedelta, retroactive_revinfo: bool, raw_config: dict)

Bases: object

CLI configuration settings.

validation_contexts: Dict[str, dict]

Named validation contexts. The values in this dictionary are themselves dictionaries that support the following keys:

  • trust: path to a root certificate or list of such paths

  • trust-replace: whether the value of the trust setting should replace the system trust, or add to it

  • other-certs: paths to other relevant certificates that are not trusted by fiat.

  • time-tolerance: a time drift tolerance setting in seconds

  • retroactive-revinfo: whether to consider revocation information retroactively valid

  • signer-key-usage-policy: Signer key usage requirements. See KeyUsageConstraints.

There are two settings that are deprecated but still supported for backwards compatibility:

  • signer-key-usage: Supplanted by signer-key-usage-policy

  • signer-extd-key-usage: Supplanted by signer-key-usage-policy

These may eventually be removed.

Callers should not process this information directly, but rely on get_validation_context() instead.

stamp_styles: Dict[str, dict]

Named stamp styles. The type of style is selected by the type key, which can be either qr or text (the default is text). For other settings values, see :class:.`QRStampStyle` and TextStampStyle.

Callers should not process this information directly, but rely on get_stamp_style() instead.

default_validation_context: str

The name of the default validation context. The default value for this setting is default.

default_stamp_style: str

The name of the default stamp style. The default value for this setting is default.

time_tolerance: timedelta

Time drift tolerance (global default).

retroactive_revinfo: bool

Whether to consider revocation information retroactively valid (global default).

raw_config: dict

The raw config data parsed into a Python dictionary.

get_validation_context(name: str | None = None, as_dict: bool = False)

Retrieve a validation context by name.

  • name – The name of the validation context. If not supplied, the value of default_validation_context will be used.

  • as_dict – If True return the settings as a keyword argument dictionary. If False (the default), return a ValidationContext object.

get_signer_key_usages(name: str | None = None) KeyUsageConstraints

Get a set of key usage constraints for a given validation context.


name – The name of the validation context. If not supplied, the value of default_validation_context will be used.


A KeyUsageConstraints object.

get_stamp_style(name: str | None = None) TextStampStyle | QRStampStyle

Retrieve a stamp style by name.


name – The name of the style. If not supplied, the value of default_stamp_style will be used.


A TextStampStyle or QRStampStyle object.

class pyhanko.cli.config.CLIRootConfig(config: CLIConfig, log_config: Dict[str | None, LogConfig], plugin_endpoints: List[str])

Bases: object

Config settings that are only relevant tothe CLI root and are not exposed to subcommands and plugins.

config: CLIConfig

General CLI config.

log_config: Dict[str | None, LogConfig]

Per-module logging configuration. The keys in this dictionary are module names, the LogConfig values define the logging settings.

The None key houses the configuration for the root logger, if any.

plugin_endpoints: List[str]

List of plugin endpoints to load, of the form package.module:PluginClass. See SigningCommandPlugin.

The value of this setting is ignored if --no-plugins is passed.


This is convenient for importing plugin classes that don’t live in installed packages for some reason or another.

Plugins that are part of packages should define their endpoints in the package metadata, which will allow them to be discovered automatically. See the docs for SigningCommandPlugin for more information.

pyhanko.cli.config.parse_cli_config(yaml_str) CLIRootConfig
pyhanko.cli.config.process_root_config_settings(config_dict: dict) dict
pyhanko.cli.config.process_config_dict(config_dict: dict) dict

pyhanko.cli.plugin_api module

class pyhanko.cli.plugin_api.SigningCommandPlugin

Bases: ABC

Added in version 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:

your_plugin = ""

Subclasses exposed as entry points are required to have a no-arguments __init__ method.


This is an incubating feature. API adjustments are still possible.


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[str | None] = None

Message to display if the plugin is unavailable.

click_options() List[Option]

The list of click options for your custom command.

click_extra_arguments() List[Argument]

The list of click arguments for your custom command.

is_available() 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 True if the plugin is available, else False

create_signer(context: CLIContext, **kwargs) ContextManager[Signer]

Instantiate a context manager that creates and potentially also implements a deallocator for a Signer object.


A context manager that manages the lifecycle for a Signer.


Manually put a plugin into the signing plugin registry.


cls – A plugin class.


The same class.

class pyhanko.cli.plugin_api.CLIContext(sig_settings: ~pyhanko.sign.signers.pdf_signer.PdfSignatureMetadata | None = None, config: ~pyhanko.cli.config.CLIConfig | None = None, existing_fields_only: bool = False, timestamp_url: str | None = None, stamp_style: ~pyhanko.stamp.BaseStampStyle | None = None, stamp_url: str | None = None, new_field_spec: ~pyhanko.sign.fields.SigFieldSpec | None = None, prefer_pss: bool = False, detach_pem: bool = False, lenient: bool = False, ux: ~pyhanko.cli._ctx.UXContext = <factory>)

Bases: object

Context object that cobbles together various CLI settings values that were gathered by various subcommands during the lifetime of a CLI invocation, either from configuration or from command line arguments. This object is passed around as a click context object.

Not all settings are applicable to all subcommands, so all values are optional.

sig_settings: PdfSignatureMetadata | None = None

The settings that will be used to produce a new signature.

config: CLIConfig | None = None

Values for CLI configuration settings.

existing_fields_only: bool = False

Whether signing operations should use existing fields only.

timestamp_url: str | None = None

Endpoint URL for the timestamping service to use.

stamp_style: BaseStampStyle | None = None

Stamp style to use for generating visual signature appearances, if applicable.

stamp_url: str | None = None

For QR stamp styles, defines the URL used to generate the QR code.

new_field_spec: SigFieldSpec | None = None

Field spec used to generate new signature fields, if applicable.

prefer_pss: bool = False

When working with RSA keys, prefer RSASSA-PSS signing if available.

detach_pem: bool = False

When producing detached signature payloads (i.e. non-PDF CMS), save the result in a PEM file instead of in a DER file.

lenient: bool = False

Process PDF files in nonstrict mode.

ux: UXContext

UX information.