1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
Support models
**************
Support models are abstracts over "raw" objects within a Pdf. For example, a page
in a PDF is a Dictionary with set to ``/Type`` of ``/Page``. The Dictionary in
that case is the "raw" object. Upon establishing what type of object it is, we
can wrap it with a support model that adds features to ensure consistency with
the PDF specification.
In version 2.x, did not apply support models to "raw" objects automatically.
Version 3.x automatically applies support models to ``/Page`` objects.
.. autoclass:: pikepdf.ObjectHelper
:members:
.. autoclass:: pikepdf.Page
:members:
Support model wrapper around a page dictionary object.
.. autoclass:: pikepdf.PdfMatrix
:members:
.. attribute:: a
.. attribute:: b
.. attribute:: c
.. attribute:: d
.. attribute:: e
.. attribute:: f
Return one of the six "active values" of the affine matrix. ``e`` and ``f``
correspond to x- and y-axis translation respectively. The other four
letters are a 2×2 matrix that can express rotation, scaling and skewing;
``a=1 b=0 c=0 d=1`` is the identity matrix.
.. autoclass:: pikepdf.PdfImage
:inherited-members:
.. autoclass:: pikepdf.PdfInlineImage
.. autoclass:: pikepdf.models.PdfMetadata
:members:
.. autoclass:: pikepdf.models.Encryption
:members:
.. autoclass:: pikepdf.models.Outline
:members:
.. autoclass:: pikepdf.models.OutlineItem
:members:
.. autoclass:: pikepdf.Permissions
:members:
.. class:: pikepdf.models.EncryptionMethod
Describes which encryption method was used on a particular part of a
PDF. These values are returned by :class:`pikepdf.EncryptionInfo` but
are not currently used to specify how encryption is requested.
.. attribute:: none
Data was not encrypted.
.. attribute:: unknown
An unknown algorithm was used.
.. attribute:: rc4
The RC4 encryption algorithm was used (obsolete).
.. attribute:: aes
The AES-based algorithm was used as described in the |pdfrm|.
.. attribute:: aesv3
An improved version of the AES-based algorithm was used as described in the
:doc:`Adobe Supplement to the ISO 32000 </references/resources>`, requiring
PDF 1.7 extension level 3. This algorithm still uses AES, but allows both
AES-128 and AES-256, and improves how the key is derived from the password.
.. autoclass:: pikepdf.models.EncryptionInfo
:members:
.. autoclass:: pikepdf.Annotation
:members:
Describes an annotation in a PDF, such as a comment, underline, copy editing marks,
interactive widgets, redactions, 3D objects, sound and video clips.
See the |pdfrm| section 12.5.6 for the full list of annotation types
and definition of terminology.
.. versionadded:: 2.12
.. autoclass:: pikepdf._qpdf.Attachments
:members:
This interface provides access to any files that are attached to this PDF,
exposed as a Python :class:`collections.abc.MutableMapping` interface.
The keys (virtual filenames) are always ``str``, and values are always
:class:`pikepdf.AttachedFileSpec`.
Use this interface through :attr:`pikepdf.Pdf.attachments`.
.. versionadded:: 3.0
.. autoclass:: pikepdf.AttachedFileSpec
:members:
:special-members: __init__
In a PDF, a file specification provides name and metadata for a target file.
Most file specifications are *simple* file specifications, and contain only
one attached file. Call :meth:`get_file` to get the attached file:
.. code-block:: python
pdf = Pdf.open(...)
fs = pdf.attachments['example.txt']
stream = fs.get_file()
To attach a new file to a PDF, you may construct a ``AttachedFileSpec``.
.. code-block:: python
pdf = Pdf.open(...)
fs = AttachedFileSpec.from_filepath(pdf, Path('somewhere/spreadsheet.xlsx'))
pdf.attachments['spreadsheet.xlsx'] = fs
PDF supports the concept of having multiple, platform-specialized versions of the
attached file (similar to resource forks on some operating systems). In theory,
this attachment ought to be the same file, but
encoded in different ways. For example, perhaps a PDF includes a text file encoded
with Windows line endings (``\r\n``) and a different one with POSIX line endings
(``\n``). Similarly, PDF allows for the possibility that you need to encode
platform-specific filenames. pikepdf cannot directly create these, because they
are arguably obsolete; it can provide access to them, however.
If you have to deal with platform-specialized versions,
use :meth:`get_all_filenames` to enumerate those available.
Described in the |pdfrm| section 7.11.3.
.. versionadded:: 3.0
.. autoclass:: pikepdf._qpdf.AttachedFile
:members:
An object that contains an actual attached file. These objects do not need
to be created manually; they are normally part of an AttachedFileSpec.
.. versionadded:: 3.0
.. autoclass:: pikepdf.NameTree
:members:
An object for managing *name tree* data structures in PDFs.
A name tree is a key-value data structure. The keys are any binary strings
(that is, Python ``bytes``). If ``str`` selected is provided as a key,
the UTF-8 encoding of that string is tested. Name trees are (confusingly)
not indexed by PDF name objects.
The keys are ordered; pikepdf will ensure that the order is preserved.
The value may be any PDF object. Typically it will be a dictionary or array.
If the name tree is invalid in any way, pikepdf will automatically repair it
if it is able to. There should not be any reason to access the internal nodes
of a name tree; use this interface instead. Likewise, pikepdf will automatically
rebalance the tree as appropriate (all thanks to libqpdf).
NameTrees are used to store certain objects like file attachments in a PDF.
Where a more specific interface exists, use that instead, and it will
manipulate the name tree in a semantic correct manner for you.
Do not modify the internal structure of a name tree while you have a
``NameTree`` referencing it. Access it only through the ``NameTree`` object.
Names trees are described in the |pdfrm| section 7.9.6. See section 7.7.4
for a list of PDF objects that are stored in name trees.
.. versionadded:: 3.0
|
