pyhanko.cli package

Submodules

pyhanko.cli.config module

class pyhanko.cli.config.Identity(plugin: str, parameters: Dict[str, str])

Bases: ConfigurableMixin

Utility abstraction for storing plugin arguments in config.

plugin: str: Plugin name.

parameters: Dict[str, str]: Plugin parameters.

classmethod from_config(config_dict)

Attempt to instantiate an object of the class on which it is called, by means of the configuration settings passed in.

First, we check that the keys supplied in the dictionary correspond to data fields on the current class. Then, the dictionary is processed using the process_entries() method. The resulting dictionary is passed to the initialiser of the current class as a kwargs dict.

Parameters:: config_dict – A dictionary containing configuration values.
Returns:: An instance of the class on which it is called.
Raises:: ConfigurationError – when an unexpected configuration key is encountered or left unfilled, or when there is a problem processing one of the config values.

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 | None, retroactive_revinfo: bool, cache_dir: str | None, identities: Dict[str, Identity], 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 | None: Time drift tolerance (global default).

retroactive_revinfo: bool: Whether to consider revocation information retroactively valid (global default).

cache_dir: str | None: Location to store cached data. Derived from the platform’s user cache dir by default.

identities: Dict[str, Identity]: List of identities (i.e. plugin parameters stored in config).

raw_config: dict: The raw config data parsed into a Python dictionary.

get_validation_settings_raw(name=None)

get_signer_key_usages(name: str | None = None) → KeyUsageConstraints

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

Parameters:: name – The name of the validation context. If not supplied, the value of default_validation_context will be used.
Returns:: A KeyUsageConstraints object.

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

Retrieve a stamp style by name.

Parameters:: name – The name of the style. If not supplied, the value of default_stamp_style will be used.
Returns:: 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.

Note

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.parse_cli_config_from_dict(config_dict) → CLIRootConfig

pyhanko.cli.config.process_root_config_settings(config_dict: dict) → dict

pyhanko.cli.config.parse_time_tolerance(config_dict: dict) → timedelta | None

pyhanko.cli.config.process_config_dict(config_dict: dict) → dict

pyhanko.cli.plugin_api module

class pyhanko.cli.plugin_api.CLIContext(sig_settings: PdfSignatureMetadata | None = None, config: CLIConfig | None = None, existing_fields_only: bool = False, timestamp_url: str | None = None, stamp_style: BaseStampStyle | None = None, stamp_url: str | None = None, new_field_spec: SigFieldSpec | None = None, prefer_pss: bool = False, detach_pem: bool = False, lenient: bool = False, ux: 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.

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:

[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[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.

Returns:: return True if the plugin is available, else False

create_signer(context: CLIContext, **kwargs) → ContextManager[Signer, bool | None]

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

Parameters:

context – The active CLIContext.
kwargs – All keyword arguments processed by click through the CLI, resulting from click_options() and click_extra_arguments().

Returns:

A context manager that manages the lifecycle for a Signer object.

pyhanko.cli.plugin_api.register_signing_plugin(cls)

Manually put a plugin into the signing plugin registry.

Parameters:: cls – A plugin class.
Returns:: The same class.

pyhanko.cli.plugin_api.prompt_for_password(prompt: str) → str

Prompt for a password using the prompter active in the current context.

Parameters:: prompt – The prompt string to display to the user.
Returns: