From 94258b5014e72e7a21bd85c154416930d846bbc7 Mon Sep 17 00:00:00 2001 From: John Whitington Date: Wed, 17 Apr 2024 07:59:48 +0800 Subject: [PATCH] v2.7 pysplits tranche 1 --- docsplits/pysplits/c01.tex | 36 +++++++++++++++++++------ docsplits/pysplits/c02.tex | 54 ++++++++++++++++++++------------------ docsplits/pysplits/c03.tex | 10 +++---- docsplits/pysplits/c04.tex | 18 ++++++++----- docsplits/pysplits/c06.tex | 3 ++- docsplits/pysplits/c07.tex | 8 +++--- docsplits/pysplits/c09.tex | 8 +++--- docsplits/pysplits/c10.tex | 36 ++++++++++++++++--------- 8 files changed, 108 insertions(+), 65 deletions(-) diff --git a/docsplits/pysplits/c01.tex b/docsplits/pysplits/c01.tex index fb3f372..e49db56 100644 --- a/docsplits/pysplits/c01.tex +++ b/docsplits/pysplits/c01.tex @@ -1,3 +1,4 @@ +""" Loading the libpypcdf and libcpdf DLLs -------------------------------------- @@ -13,8 +14,8 @@ to tell ``libpycpdf.so`` where to find ``libcpdf.so``. Conventions ----------- -Any function may raise the exception ``CPDFError``, carrying a string describing -the error. +Any function may raise the exception ``CPDFError``, carrying a string +describing the error. A 'range' is a list of integers specifying page numbers. Page numbers start at 1. Range arguments are called `r`. @@ -79,8 +80,18 @@ useNone useOutlines useThumbs useOC useAttachments Page label styles: decimalArabic uppercaseRoman lowercaseRoman uppercaseLetters lowercaseLetters + +Line cap types: + +capButt capRound capSquare + +Line join types: + +joinMiter joinRound joinBevel """ +# CHAPTER 0. Preliminaries + class Pdf: """The type of PDF documents.""" @@ -109,19 +120,28 @@ def version(): """Return the version number of the pycpdflib library.""" def setFast(): - """ Set fast mode. Some operations have a fast mode. The default is 'slow' + """Set fast mode. Some operations have a fast mode. The default is 'slow' mode, which works even on old-fashioned files. For more details, see - section 1.13 of the CPDF manual. This function sets the mode globally. """ + section 1.13 of the CPDF manual. This function sets the mode globally.""" def setSlow(): - """ Set slow mode. Some operations have a fast mode. The default is 'slow' + """Set slow mode. Some operations have a fast mode. The default is 'slow' mode, which works even on old-fashioned files. For more details, see - section 1.13 of the CPDF manual. This function sets the mode globally. """ + section 1.13 of the CPDF manual. This function sets the mode globally.""" + +def embedStd14(embed): + """Calling this function with a true argument sets embedding for the + Standard 14 fonts. You must also set the directory to load them from with + the embedStd14Dir function. Default value: False.""" + +def embedStd14Dir(d): + """Set the directory to load Standard 14 fonts for embedding.""" + libc.pycpdf_embedStd14Dir(str.encode(d)) def clearError(): - """ Clear the current error state. """ + """Clear the current error state.""" def onExit(): - """ A debug function which prints some information about + """A debug function which prints some information about resource usage. This can be used to detect if PDFs or ranges are being deallocated properly.""" diff --git a/docsplits/pysplits/c02.tex b/docsplits/pysplits/c02.tex index 49c75a5..31beb01 100644 --- a/docsplits/pysplits/c02.tex +++ b/docsplits/pysplits/c02.tex @@ -1,23 +1,22 @@ # CHAPTER 1. Basics def fromFile(filename, userpw): - """ Load a PDF file from a given file. - Supply a user password (possibly blank) in case the file is encypted. It - won't be decrypted, but sometimes the password is needed just to load the - file.""" + """Load a PDF file from a given file. Supply a user password (possibly + blank) in case the file is encrypted. It won't be decrypted, but sometimes + the password is needed just to load the file.""" def fromFileLazy(filename, userpw): - """ Loads a PDF from a file, doing only - minimal parsing. The objects will be read and parsed when they are actually - needed. Use this when the whole file won't be required. Also supply a user - password (possibly blank) in case the file is encypted. It won't be - decrypted, but sometimes the password is needed just to load the file.""" + """Load a PDF from a file, doing only minimal parsing. The objects will be + read and parsed when they are actually needed. Use this when the whole + file won't be required. Also supply a user password (possibly blank) in + case the file is encrypted. It won't be decrypted, but sometimes the + password is needed just to load the file.""" def fromMemory(data, userpw): - """ Load a file from a byte array and the user password (blank if none).""" + """Load a file from a byte array and the user password (blank if none).""" def fromMemoryLazy(data, userpw): - """ Load a file from from a byte array and the user password (blank if + """Load a file from from a byte array and the user password (blank if none), but lazily like fromFileLazy.""" def ptOfCm(i): @@ -48,27 +47,24 @@ def validatePagespec(pagespec): possible in the absence of the actual document.""" def stringOfPagespec(pdf, r): - """Build a page specification from a page - range. For example, the range containing 1,2,3,6,7,8 in a document of 8 - pages might yield "1-3,6-end" """ + """Build a page specification from a page range. For example, the range + containing 1,2,3,6,7,8 in a document of 8 pages might yield "1-3,6-end".""" def blankRange(): """Create a range with no pages in.""" def pageRange(f, t): - """ Nuild a range from one page to another inclusive. - For example, pageRange(3,7) gives the range 3,4,5,6,7. """ + """Build a range from one page to another inclusive. For example, + pageRange(3,7) gives the range 3,4,5,6,7.""" def all(pdf): """The range containing all the pages in a given document.""" def even(r): - """A range which contains just the even pages of another - range.""" + """A range which contains just the even pages of another range.""" def odd(r): - """A range which contains just the odd pages of another - range.""" + """A range which contains just the odd pages of another range.""" def rangeUnion(a, b): """The union of two ranges giving a range containing @@ -99,14 +95,15 @@ def pages(pdf): """Return the number of pages in a PDF.""" def pagesFast(userpw, filename): - """Return the number of pages in a given - PDF, with given user password. It tries to do this as fast as - possible, without loading the whole file.""" + """Return the number of pages in a given PDF, with given user password. It + tries to do this as fast as possible, without loading the whole file.""" def toFile(pdf, filename, linearize, make_id): """Write the file to a given filename. If linearize is True, it will be linearized, if supported by libcpdf. If make_id is True, it will be given a - new ID.""" + new ID. NB: Unlike with the command line tool, cpdf, streams decompressed + during processing will not automatically be compressed when writing. Call + compress() first.""" def toFileExt(pdf, filename, linearize, make_id, preserve_objstm, generate_objstm, compress_objstm): @@ -120,7 +117,9 @@ def toFileExt(pdf, filename, linearize, make_id, preserve_objstm, def toMemory(pdf, linearize, make_id): """Write a file to memory, returning the buffer as a byte array of type - bytes.""" + bytes. NB: Unlike with the command line tool, cpdf, streams decompressed + during processing will not automatically be compressed when writing. Call + compress() first.""" def isEncrypted(pdf): """Returns True if a documented is encrypted, False otherwise.""" @@ -157,3 +156,8 @@ def hasPermission(pdf, perm): def encryptionKind(pdf): """Return the encryption method currently in use on a document.""" + +def loadFont(name, filename): + """Loads a TrueType font from the given file name, and names it. It may + then be used when adding text or drawing, using the name in place of a + standard font name. """ diff --git a/docsplits/pysplits/c03.tex b/docsplits/pysplits/c03.tex index f09ac0c..8f58651 100644 --- a/docsplits/pysplits/c03.tex +++ b/docsplits/pysplits/c03.tex @@ -11,10 +11,10 @@ def merge(pdfs, retain_numbering, remove_duplicate_fonts): same source.""" def mergeSame(pdfs, retain_numbering, remove_duplicate_fonts, ranges): - """The same as merge, except that it has an additional argument - - a list of page ranges. This is used to select the pages to pick from - each PDF. This avoids duplication of information when multiple discrete - parts of a single source PDF are included.""" + """The same as merge, except that it has an additional argument (a list of + page ranges). This is used to select the pages to pick from each PDF. This + avoids duplication of information when multiple discrete parts of a single + source PDF are included.""" def selectPages(pdf, r): - """ Returns a new document which just those pages in the page range.""" + """Returns a new document which just those pages in the page range.""" diff --git a/docsplits/pysplits/c04.tex b/docsplits/pysplits/c04.tex index cc6ef0d..bc974cc 100644 --- a/docsplits/pysplits/c04.tex +++ b/docsplits/pysplits/c04.tex @@ -12,7 +12,7 @@ def scaleToFit(pdf, r, w, h, scale_to_fit_scale): def scaleToFitPaper(pdf, r, papersize, scale_to_fit_scale): """Scales the given pages to fit the given page size, possibly multiplied - by scale_to_fit_scale (typically 1.0)""" + by scale_to_fit_scale (typically 1.0).""" def scaleContents(pdf, r, pos, scale): """Scales the contents of the pages in the range about the point given by @@ -20,18 +20,22 @@ def scaleContents(pdf, r, pos, scale): def shiftContents(pdf, r, dx, dy): """Shift the content of the pages in the range by (dx, dy).""" + r = range_of_list(r) + +def shiftBoxes(pdf, r, dx, dy): + """Shift the pages boxes in the range by (dx, dy).""" def rotate(pdf, r, rotation): - """Change the viewing rotation of the pages in the range to an - absolute value. Appropriate rotations are 0, 90, 180, 270.""" + """Change the viewing rotation of the pages in the range to an absolute + value. Appropriate rotations are 0, 90, 180, 270.""" def rotateBy(pdf, r, rotation): - """Change the viewing rotation of the pages in the range by a - given number of degrees. Appropriate values are 90, 180, 270.""" + """Change the viewing rotation of the pages in the range by a given number + of degrees. Appropriate values are 90, 180, 270.""" def rotateContents(pdf, r, rotation): - """Rotate the content about the centre - of the page by the given number of degrees, in a clockwise direction.""" + """Rotate the content about the centre of the page by the given number of + degrees, in a clockwise direction.""" def upright(pdf, r): """Change the viewing rotation of the pages in the range, counter-rotating diff --git a/docsplits/pysplits/c06.tex b/docsplits/pysplits/c06.tex index 9e93d36..f3321c8 100644 --- a/docsplits/pysplits/c06.tex +++ b/docsplits/pysplits/c06.tex @@ -10,4 +10,5 @@ def decompress(pdf): def squeezeInMemory(pdf): """squeezeToMemory(pdf) squeezes a pdf in memory. Squeezing is a lossless - compression method which works be rearrangement of a PDFs internal + compression method which works by rearrangement of a PDFs internal + structure.""" diff --git a/docsplits/pysplits/c07.tex b/docsplits/pysplits/c07.tex index 6c662eb..fad68b6 100644 --- a/docsplits/pysplits/c07.tex +++ b/docsplits/pysplits/c07.tex @@ -12,9 +12,9 @@ def getBookmarksJSON(pdf): """Get the bookmarks in JSON format.""" def setBookmarksJSON(pdf, data): - """setBookmarksJSON(pdf, data) sets the bookmarks from JSON bookmark data.""" + """Sets the bookmarks from JSON bookmark data.""" def tableOfContents(pdf, font, fontsize, title, bookmark): - """tableOfContents(pdf, font, fontsize, title, bookmark) typesets a table - of contents from existing bookmarks and prepends it to the document. If - bookmark is set, the table of contents gets its own bookmark.""" + """Typesets a table of contents from existing bookmarks and prepends it to + the document. If bookmark is set, the table of contents gets its own + bookmark.""" diff --git a/docsplits/pysplits/c09.tex b/docsplits/pysplits/c09.tex index 82c44a0..e119ef7 100644 --- a/docsplits/pysplits/c09.tex +++ b/docsplits/pysplits/c09.tex @@ -15,7 +15,8 @@ def stampExtended(pdf, pdf2, r, isover, scale_stamp_to_fit, pos, - isover True, pdf goes over pdf2, isover False, pdf goes under pdf2 - scale_stamp_to_fit scales the stamp to fit the page - pos gives the position to put the stamp - - relative_to_cropbox: if True, pos is relative to crop box not media box""" + - relative_to_cropbox: if True, pos is relative to crop box not media box + """ def combinePages(pdf, pdf2): """Combines the PDFs page-by-page, putting each page of pdf2 over each page @@ -82,14 +83,15 @@ def addText(metrics, pdf, r, text, p, line_spacing, bates, font, size, red, * %% The % character""" def addTextSimple(pdf, r, text, p, font, size): - """like addText, but with most parameters default + """Like addText, but with most parameters default * pdf = the document * r = the range * text = the text * p = the position * font = the font - * size = the font size""" + * size = the font size + NB: %filename cannot be used here. """ def removeText(pdf, r): """Remove any text added by libcpdf from the given pages.""" diff --git a/docsplits/pysplits/c10.tex b/docsplits/pysplits/c10.tex index 48ddcaa..654edf1 100644 --- a/docsplits/pysplits/c10.tex +++ b/docsplits/pysplits/c10.tex @@ -1,20 +1,32 @@ # CHAPTER 9. Multipage facilities def twoUp(pdf): - """Impose a document two up by retaining the existing page - size, scaling pages down.""" + """Impose a document two up by retaining the existing page size, scaling + pages down.""" def twoUpStack(pdf): - """Impose a document two up by doubling the page size, - to fit two pages on one.""" + """Impose a document two up by doubling the page size, to fit two pages on + one.""" def impose(pdf, x, y, fit, columns, rtl, btt, center, margin, spacing, linewidth): - """impose(pdf, x, y, fit, columns, rtl, btt, center, margin, spacing, - linewidth) imposes a PDF. There are two modes: imposing x * y, or imposing - to fit a page of size x * y. This is controlled by fit. Columns imposes by - columns rather than rows. rtl is right-to-left, btt bottom-to-top. Center - is unused for now. Margin is the margin around the output, spacing the - spacing between imposed inputs.""" + """Impose a PDF. There are two modes: imposing x * y, or imposing to fit a + page of size x * y. This is controlled by fit. Columns imposes by columns + rather than rows. rtl is right-to-left, btt bottom-to-top. Center is unused + for now. Margin is the margin around the output, spacing the spacing + between imposed inputs.""" + +def chop(pdf, r, x, y, columns, rtl, btt): + """Chop each page in the range into x * y pieces. If columns is set, the + pieces go by columns instead of rows. If rtl is set, the pieces are taken + right-to-left. If btt is set, the pieces are taken from bottom to top. """ + +def chopH(pdf, r, columns, y): + """Chop each page in the range horizontally at position y. If columns is + set, the pieces are arranged in reverse order. """ + +def chopV(pdf, r, columns, x): + """Chop each page in the range vertically at position x. If columns is + set, the pieces are arranged in reverse order. """ def padBefore(pdf, r): """Adds a blank page before each page in the given range.""" @@ -30,5 +42,5 @@ def padMultiple(pdf, n): length.""" def padMultipleBefore(pdf, n): - """Adds pages at the beginning to pad the file to a - multiple of n pages in length.""" + """Adds pages at the beginning to pad the file to a multiple of n pages in + length."""