You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api.html
+78-39Lines changed: 78 additions & 39 deletions
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,9 @@
13
13
<main>
14
14
<h2>API</h2>
15
15
<p></p>
16
-
<h3>Usage</h3>
16
+
<h3>Principles </h3>
17
+
<p></p>
18
+
<h4>Pure functions</h4>
17
19
<p>Most functions are pure and are exposed both as basic functions and as instance methods of a Doc object: in the function signatures found in the following sections, a <code>doc</code> first argument can read as <code>self</code>. For example both samples are equivalent:</p>
18
20
<pre>>>> #Function pattern
19
21
>>> from pdfsyntax import readfile, metadata
<p>Every time a function is applied to a Doc object, the function returns a new object built as a shallow copy of the input.</p>
32
+
<h4>Incremental updates</h4>
33
+
<p>PDFSyntax tracks document incremental updates made possible by appending new or updated objects at the end of an original PDF file (and the matching XREF section). A revision, if greater than 0, indicates that incremental updates have been appended.By default, a newly opened document by PDFSyntax is ready to write modifications in the next revision.The <code>rewind</code> function rolls back to the previous revision. The <code>commit</code> function closes the current revision and open the next one.</p>
34
+
<p>For example this file contains 2 revisions (0 and 1) and PDFSyntax has initialized the doc object to open revision 2:</p>
<PDF Doc in revision 2 with 0 modified object(s)>
39
+
</pre>
40
+
<p>The <code>rewind</code> function rolls back to the previous revision. Let's rewind to revision 0:</p>
41
+
<pre>>>> doc = pdf.rewind(doc) # to revision 1
42
+
>>> doc = pdf.rewind(doc) # to revision 0
43
+
>>> doc
44
+
<PDF Doc in revision 0 with 7 modified object(s)>
45
+
</pre>
46
+
<p>After one or several modifications, the <code>commit</code> function closes the current revision and opens the next one:</p>
47
+
<pre>>>> doc = pdf.rotate(doc)
48
+
>>> doc = pdf.commit(doc)
49
+
>>> doc
50
+
<PDF Doc in revision 1 with 0 modified object(s)>
51
+
</pre>
52
+
<p></p>
53
+
<h4>Squashing</h4>
54
+
<p>By default incremental updates stack up but it is possible to <code>squash</code> a document in order to combine all revisions into a single one. in this example the last document is equivalent to the first one (same appearance), but it is only made of one revision. As this revision is like a document started from scratch, its revision is 0 and all its 7 internal objects look like new ones:</p>
55
+
<pre>>>> doc90 = pdf.rotate(doc)
56
+
>>> doc90
57
+
<PDF Doc in revision 1 with 1 modified object(s)>
58
+
>>> docs = pdf.squash(doc90)
59
+
>>> docs
60
+
<PDF Doc in revision 0 with 7 modified object(s)>
61
+
</pre>
62
+
<p></p>
63
+
<h4>File I/O</h4>
64
+
<p>The <code>writefile</code> function dumps the document with all the incremental updates appended at the end of the original data. </p>
65
+
<pre>>>> from pdfsyntax import readfile, writefile
<p><code>rotate</code> turns pages relatively to their current position by multiples of 90 degrees clockwise. NB: It takes into account the inherited attributes from the page hierarchy.</p>
84
+
<pre>>>> #Default rotation applies 90 degrees to all pages
85
+
>>> doc90 = rotate(doc)
86
+
87
+
>>> #Apply 180 degrees to first two page
88
+
>>> doc180 = doc.rotate(180, [0, 1])
89
+
</pre>
90
+
<p><em>WARNING</em>: To REMOVE something means it still exists but it is hidden.</p>
91
+
<p><code>remove_pages</code> cuts a set of pages from the document as incremental update: they are not permanently deleted because it is still possible to revert to the previous revision.</p>
92
+
<pre>>>> #Remove first 3 pages of a 6-page doc
<p>Page index is a tree structure where attributes can be inherited from parent nodes. For convenience <code>flat_page_tree</code> returns an ordered list of document pages and specifies inherited attributes that should apply to each page.</p>
61
136
<pre>>>> #Each item of the list is a tuple with the page object reference and its inherited attributes
<p>PDFSyntax tracks document incremental updates made possible by appending new or updated objects at the end of an original PDF file (and the matching XREF section). The <code>Revisions</code> entry of the <code>structure</code> function result, if greater than 1, indicates that incremental updates have been appended.By default, a newly opened document by PDFSyntax is ready to write modifications in the next revision.The <code>rewind</code> function rolls back to the previous revision. The <code>commit</code> function closes the current revision and open the next one.</p>
<p><code>rotate</code> turns pages relatively to their current position by multiples of 90 degrees clockwise. NB: It takes into account the inherited attributes from the page hierarchy.</p>
106
-
<pre>>>> #Default rotation applies 90 degrees to all pages
Most functions are pure and are exposed both as basic functions and as instance methods of a Doc object: in the function signatures found in the following sections, a `doc` first argument can read as `self`. For example both samples are equivalent:
6
8
@@ -18,6 +20,66 @@ Most functions are pure and are exposed both as basic functions and as instance
18
20
>>> m = doc.metadata()
19
21
```
20
22
23
+
Every time a function is applied to a Doc object, the function returns a new object built as a shallow copy of the input.
24
+
25
+
#### Incremental updates
26
+
27
+
PDFSyntax tracks document incremental updates made possible by appending new or updated objects at the end of an original PDF file (and the matching XREF section). A revision, if greater than 0, indicates that incremental updates have been appended.
28
+
By default, a newly opened document by PDFSyntax is ready to write modifications in the next revision.
29
+
The `rewind` function rolls back to the previous revision. The `commit` function closes the current revision and open the next one.
30
+
31
+
32
+
For example this file contains 2 revisions (0 and 1) and PDFSyntax has initialized the doc object to open revision 2:
The `rewind` function rolls back to the previous revision. Let's rewind to revision 0:
42
+
43
+
```Python
44
+
>>> doc = pdf.rewind(doc) # to revision 1
45
+
>>> doc = pdf.rewind(doc) # to revision 0
46
+
>>> doc
47
+
<PDF Doc in revision 0with7 modified object(s)>
48
+
```
49
+
50
+
After one or several modifications, the `commit` function closes the current revision and opens the next one:
51
+
52
+
```Python
53
+
>>> doc = pdf.rotate(doc)
54
+
>>> doc = pdf.commit(doc)
55
+
>>> doc
56
+
<PDF Doc in revision 1with0 modified object(s)>
57
+
```
58
+
59
+
#### Squashing
60
+
61
+
By default incremental updates stack up but it is possible to `squash` a document in order to combine all revisions into a single one. in this example the last document is equivalent to the first one (same appearance), but it is only made of one revision. As this revision is like a document started from scratch, its revision is 0 and all its 7 internal objects look like new ones:
62
+
63
+
```Python
64
+
>>> doc90 = pdf.rotate(doc)
65
+
>>> doc90
66
+
<PDF Doc in revision 1with1 modified object(s)>
67
+
>>> docs = pdf.squash(doc90)
68
+
>>> docs
69
+
<PDF Doc in revision 0with7 modified object(s)>
70
+
```
71
+
72
+
#### File I/O
73
+
74
+
The `writefile` function dumps the document with all the incremental updates appended at the end of the original data.
`rotate` turns pages relatively to their current position by multiples of 90 degrees clockwise. NB: It takes into account the inherited attributes from the page hierarchy.
100
+
101
+
```Python
102
+
>>>#Default rotation applies 90 degrees to all pages
103
+
>>> doc90 = rotate(doc)
104
+
105
+
>>>#Apply 180 degrees to first two page
106
+
>>> doc180 = doc.rotate(180, [0, 1])
107
+
```
108
+
109
+
_WARNING_: To REMOVE something means it still exists but it is hidden.
110
+
111
+
`remove_pages` cuts a set of pages from the document as incremental update: they are not permanently deleted because it is still possible to revert to the previous revision.
Page index is a tree structure where attributes can be inherited from parent nodes. For convenience `flat_page_tree` returns an ordered list of document pages and specifies inherited attributes that should apply to each page.
64
179
@@ -82,52 +197,6 @@ The `page` function goes further by merging inherited attributes with local attr
82
197
'/Type': '/Page'}]
83
198
```
84
199
85
-
### Incremental updates
86
-
87
-
PDFSyntax tracks document incremental updates made possible by appending new or updated objects at the end of an original PDF file (and the matching XREF section). The `Revisions` entry of the `structure` function result, if greater than 1, indicates that incremental updates have been appended.
88
-
By default, a newly opened document by PDFSyntax is ready to write modifications in the next revision.
89
-
The `rewind` function rolls back to the previous revision. The `commit` function closes the current revision and open the next one.
`rotate` turns pages relatively to their current position by multiples of 90 degrees clockwise. NB: It takes into account the inherited attributes from the page hierarchy.
123
-
124
-
```Python
125
-
>>>#Default rotation applies 90 degrees to all pages
0 commit comments