pyhanko.sign.diff_analysis.form_rules_api module
Module defining API types for use by form analysis rules.
In principle, these aren’t relevant to the high-level validation API.
- class pyhanko.sign.diff_analysis.form_rules_api.FormUpdatingRule(field_rules: List[FieldMDPRule], ignored_acroform_keys=None)
Bases:
object
Special whitelisting rule that validates changes to the form attached to the input document.
This rule is special in two ways:
it outputs
FormUpdate
objects instead of references;it delegates most of the hard work to sub-rules (instances of
FieldMDPRule
).
A
DiffPolicy
can have at most oneFormUpdatingRule
, but there is no limit on the number ofFieldMDPRule
objects attached to it.FormUpdate
objects contain a reference plus metadata about the form field it belongs to.- Parameters
field_rules – A list of
FieldMDPRule
objects to validate the individual form fields.ignored_acroform_keys – Keys in the
/AcroForm
dictionary that may be changed. Changes are potentially subject to validation by other rules.
- apply(old: HistoricalResolver, new: HistoricalResolver) Iterable[Tuple[ModificationLevel, FormUpdate]]
Evaluate changes in the document’s form between two revisions.
- Parameters
old – The older, base revision.
new – The newer revision to be vetted.
- class pyhanko.sign.diff_analysis.form_rules_api.FormUpdate(updated_ref: Reference, paths_checked: Optional[Union[RawPdfPath, Iterable[RawPdfPath]]] = None, blanket_approve: bool = False, field_name: Optional[str] = None, valid_when_locked: bool = False, valid_when_certifying: bool = True)
Bases:
ReferenceUpdate
Container for a reference together with (optional) metadata.
Currently, this metadata consists of the relevant field’s (fully qualified) name, and whether the update should be approved or not if said field is locked by the FieldMDP policy currently in force.
- field_name: Optional[str] = None
The relevant field’s fully qualified name, or
None
if there’s either no obvious associated field, or if there are multiple reasonable candidates.
- valid_when_locked: bool = False
Flag indicating whether the update is valid even when the field is locked. This is only relevant if
field_name
is notNone
.
- valid_when_certifying: bool = True
Flag indicating whether the update is valid when checking against an explicit DocMDP policy. Default is
True
. IfFalse
, the change will only be accepted if we are evaluating changes to a document after an approval signature.
- class pyhanko.sign.diff_analysis.form_rules_api.FieldMDPRule
Bases:
object
Sub-rules attached to a
FormUpdatingRule
.- apply(context: FieldComparisonContext) Iterable[Tuple[ModificationLevel, FormUpdate]]
Apply the rule to the given
FieldComparisonContext
.- Parameters
context – The context of this form revision evaluation, given as an instance of
FieldComparisonContext
.
- class pyhanko.sign.diff_analysis.form_rules_api.FieldComparisonSpec(field_type: str, old_field_ref: Optional[Reference], new_field_ref: Optional[Reference], old_canonical_path: Optional[RawPdfPath])
Bases:
object
Helper object that specifies a form field name together with references to its old and new versions.
- field_type: str
The (fully qualified) form field name.
- old_field_ref: Optional[Reference]
A reference to the field’s dictionary in the old revision, if present.
- new_field_ref: Optional[Reference]
A reference to the field’s dictionary in the new revision, if present.
- old_canonical_path: Optional[RawPdfPath]
Path from the trailer through the AcroForm structure to this field (in the older revision). If the field is new, set to
None
.
- property old_field: Optional[DictionaryObject]
- Returns
The field’s dictionary in the old revision, if present, otherwise
None
.
- property new_field: Optional[DictionaryObject]
- Returns
The field’s dictionary in the new revision, if present, otherwise
None
.
- expected_paths()
- class pyhanko.sign.diff_analysis.form_rules_api.FieldComparisonContext(field_specs: Dict[str, FieldComparisonSpec], old: HistoricalResolver, new: HistoricalResolver)
Bases:
object
Context for a form diffing operation.
- field_specs: Dict[str, FieldComparisonSpec]
Dictionary mapping field names to
FieldComparisonSpec
objects.
- old: HistoricalResolver
The older, base revision.
- new: HistoricalResolver
The newer revision.