pyhanko.cli package
Submodules
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 pathstrust-replace
: whether the value of thetrust
setting should replace the system trust, or add to itother-certs
: paths to other relevant certificates that are not trusted by fiat.time-tolerance
: a time drift tolerance setting in secondsretroactive-revinfo
: whether to consider revocation information retroactively validsigner-key-usage-policy
: Signer key usage requirements. SeeKeyUsageConstraints
.
There are two settings that are deprecated but still supported for backwards compatibility:
signer-key-usage
: Supplanted bysigner-key-usage-policy
signer-extd-key-usage
: Supplanted bysigner-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 eitherqr
ortext
(the default istext
). For other settings values, see :class:.`QRStampStyle` andTextStampStyle
.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.
- Parameters:
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. IfFalse
(the default), return aValidationContext
object.
- 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.
- 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
. SeeSigningCommandPlugin
.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.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
New 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 inpyproject.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.
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, elseFalse
- create_signer(context: CLIContext, **kwargs) ContextManager[Signer]
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 fromclick_options()
andclick_extra_arguments()
.
- Returns:
A context manager that manages the lifecycle for a
Signer
.
- 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.
- 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.
- 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.