Functions

The following are miscellaneous functions and attributes on a fairly low-level technical detail.

Some functions provide detail access to PDF structures. Others are stripped-down, high performance versions of other functions which provide more information.

Yet others are handy, general-purpose utilities.

Function

Short Description

Annot.apn_bbox

PDF only: bbox of the appearance object

Annot.apn_matrix

PDF only: the matrix of the appearance object

Page.is_wrapped

check whether contents wrapping is present

adobe_glyph_names()

list of glyph names defined in Adobe Glyph List

adobe_glyph_unicodes()

list of unicodes defined in Adobe Glyph List

Annot.clean_contents()

PDF only: clean the annot’s contents object

Annot.set_apn_bbox()

PDF only: set the bbox of the appearance object

Annot.set_apn_matrix()

PDF only: set the matrix of the appearance object

ConversionHeader()

return header string for get_text methods

ConversionTrailer()

return trailer string for get_text methods

Document.del_xml_metadata()

PDF only: remove XML metadata

Document.get_char_widths()

PDF only: return a list of glyph widths of a font

Document.get_new_xref()

PDF only: create and return a new xref entry

Document.is_stream()

PDF only: check whether an xref is a stream object

Document.xml_metadata_xref()

PDF only: return XML metadata xref number

Document.xref_length()

PDF only: return length of xref table

EMPTY_IRECT()

return the (standard) empty / invalid rectangle

EMPTY_QUAD()

return the (standard) empty / invalid quad

EMPTY_RECT()

return the (standard) empty / invalid rectangle

get_pdf_now()

return the current timestamp in PDF format

get_pdf_str()

return PDF-compatible string

get_text_length()

return string length for a given font & fontsize

glyph_name_to_unicode()

return unicode from a glyph name

image_profile()

return a dictionary of basic image properties

INFINITE_IRECT()

return the (only existing) infinite rectangle

INFINITE_QUAD()

return the (only existing) infinite quad

INFINITE_RECT()

return the (only existing) infinite rectangle

make_table()

split rectangle in sub-rectangles

Page.clean_contents()

PDF only: clean the page’s contents objects

Page.get_bboxlog()

list of rectangles that envelop text, drawing or image objects

Page.get_contents()

PDF only: return a list of content xref numbers

Page.get_displaylist()

create the page’s display list

Page.get_text_blocks()

extract text blocks as a Python list

Page.get_text_words()

extract text words as a Python list

Page.get_texttrace()

low-level text information

Page.read_contents()

PDF only: get complete, concatenated /Contents source

Page.run()

run a page through a device

Page.set_contents()

PDF only: set page’s contents to some xref

Page.wrap_contents()

wrap contents with stacking commands

paper_rect()

return rectangle for a known paper format

paper_size()

return width, height for a known paper format

paper_sizes()

dictionary of pre-defined paper formats

planish_line()

matrix to map a line to the x-axis

recover_char_quad()

compute the quad of a char (“rawdict”)

recover_line_quad()

compute the quad of a subset of line spans

recover_quad()

compute the quad of a span (“dict”, “rawdict”)

recover_quad()

return the quad for a text span (“dict” / “rawdict”)

recover_span_quad()

compute the quad of a subset of span characters

sRGB_to_pdf()

return PDF RGB color tuple from an sRGB integer

sRGB_to_rgb()

return (R, G, B) color tuple from an sRGB integer

unicode_to_glyph_name()

return glyph name from a unicode

fitz_fontdescriptors

dictionary of available supplement fonts

TESSDATA_PREFIX

a copy of os.environ[“TESSDATA_PREFIX”]

pdfcolor

dictionary of almost 500 RGB colors in PDF format.

paper_size(s)

Convenience function to return width and height of a known paper format code. These values are given in pixels for the standard resolution 72 pixels = 1 inch.

Currently defined formats include ‘A0’ through ‘A10’, ‘B0’ through ‘B10’, ‘C0’ through ‘C10’, ‘Card-4x6’, ‘Card-5x7’, ‘Commercial’, ‘Executive’, ‘Invoice’, ‘Ledger’, ‘Legal’, ‘Legal-13’, ‘Letter’, ‘Monarch’ and ‘Tabloid-Extra’, each in either portrait or landscape format.

A format name must be supplied as a string (case in sensitive), optionally suffixed with “-L” (landscape) or “-P” (portrait). No suffix defaults to portrait.

  • Parameters

    s (str) – any format name from above in upper or lower case, like “A4” or “letter-l”.

    Return type

    tuple

    Returns

    (width, height) of the paper format. For an unknown format (-1, -1) is returned. Examples: fitz.paper_size(“A4”) returns (595, 842) and fitz.paper_size(“letter-l”) delivers (792, 612).


paper_rect(s)

Convenience function to return a Rect for a known paper format.

  • Parameters

    s (str) – any format name supported by paper_size().

    Return type

    Rect

    Returns

    fitz.Rect(0, 0, width, height) with width, height=fitz.paper_size(s).

  1. >>> import fitz
  2. >>> fitz.paper_rect("letter-l")
  3. fitz.Rect(0.0, 0.0, 792.0, 612.0)
  4. >>>

sRGB_to_pdf(srgb)

New in v1.17.4

Convenience function returning a PDF color triple (red, green, blue) for a given sRGB color integer as it occurs in Page.get_text() dictionaries “dict” and “rawdict”.

  • Parameters

    srgb (int) – an integer of format RRGGBB, where each color component is an integer in range(255).

    Returns

    a tuple (red, green, blue) with float items in intervall 0 <= item <= 1 representing the same color. Example sRGB_to_pdf(0xff0000) = (1, 0, 0) (red).


sRGB_to_rgb(srgb)

New in v1.17.4

Convenience function returning a color (red, green, blue) for a given sRGB color integer.

  • Parameters

    srgb (int) – an integer of format RRGGBB, where each color component is an integer in range(255).

    Returns

    a tuple (red, green, blue) with integer items in range(256) representing the same color. Example sRGB_to_pdf(0xff0000) = (255, 0, 0) (red).


glyph_name_to_unicode(name)

New in v1.18.0

Return the unicode number of a glyph name based on the Adobe Glyph List.

  • Parameters

    name (str) – the name of some glyph. The function is based on the Adobe Glyph List.

    Return type

    int

    Returns

    the unicode. Invalid name entries return 0xfffd (65533).

Note

A similar functionality is provided by package fontTools in its agl sub-package.


unicode_to_glyph_name(ch)

New in v1.18.0

Return the glyph name of a unicode number, based on the Adobe Glyph List.

  • Parameters

    ch (int) –

    the unicode given by e.g. ord("ß"). The function is based on the Adobe Glyph List.

    Return type

    str

    Returns

    the glyph name. E.g. fitz.unicode_to_glyph_name(ord("Ä")) returns 'Adieresis'.

Note

A similar functionality is provided by package fontTools: in its agl sub-package.


adobe_glyph_names()

New in v1.18.0

Return a list of glyph names defined in the Adobe Glyph List.

  • Return type

    list

    Returns

    list of strings.

Note

A similar functionality is provided by package fontTools in its agl sub-package.


adobe_glyph_unicodes()

New in v1.18.0

Return a list of unicodes for there exists a glyph name in the Adobe Glyph List.

  • Return type

    list

    Returns

    list of integers.

Note

A similar functionality is provided by package fontTools in its agl sub-package.


recover_quad(line_dir, span)

New in v1.18.9

Convenience function returning the quadrilateral envelopping the text of a text span, as returned by Page.get_text() using the “dict” or “rawdict” options.

  • Parameters

    • line_dict (tuple) – the value line["dir"] of the span’s line.

    • span (dict) – the span sub-dictionary.

  1. Returns
  2. the quadrilateral of the spans text.

make_table(rect, cols=1, rows=1)

New in v1.17.4

Convenience function to split a rectangle into sub-rectangles. Returns a list of rows lists, each containing cols Rect items. Each sub-rectangle can then be addressed by its row and column index.

  • Parameters

    • rect (rect_like) – the rectangle to split.

    • cols (int) – the desired number of columns.

    • rows (int) – the desired number of rows.

  1. Returns
  2. a list of [Rect]($b48b06fa83bf6d26.md#rect) objects of equal size, whose union equals *rect*. Here is the layout of a 3x4 table created by `cell = fitz.make_table(rect, cols=4, rows=3)`:

_images/img-make-table.jpg


planish_line(p1, p2)

  • New in version 1.16.2)*

Return a matrix which maps the line from p1 to p2 to the x-axis such that p1 will become (0,0) and p2 a point with the same distance to (0,0).

  • Parameters

    • p1 (point_like) – starting point of the line.

    • p2 (point_like) – end point of the line.

  1. Return type
  2. [Matrix]($0d91fae145b6974f.md#matrix)
  3. Returns
  4. a matrix which combines a rotation and a translation:
  5. ```
  6. >>> p1 = fitz.Point(1, 1)
  7. >>> p2 = fitz.Point(4, 5)
  8. >>> abs(p2 - p1) # distance of points
  9. 5.0
  10. >>> m = fitz.planish_line(p1, p2)
  11. >>> p1 * m
  12. Point(0.0, 0.0)
  13. >>> p2 * m
  14. Point(5.0, -5.960464477539063e-08)
  15. >>> # distance of the resulting points
  16. >>> abs(p2 * m - p1 * m)
  17. 5.0
  18. ```
  19. [![_images/img-planish.png](/projects/pymupdf-1.19.6-en/296562958c4e2200851f587535f49465.png)](https://pymupdf.readthedocs.io/en/latest/_images/img-planish.png)

paper_sizes()

A dictionary of pre-defines paper formats. Used as basis for paper_size().


fitz_fontdescriptors

  • New in v1.17.5

A dictionary of usable fonts from repository pymupdf-fonts. Items are keyed by their reserved fontname and provide information like this:

  1. In [2]: fitz.fitz_fontdescriptors.keys()
  2. Out[2]: dict_keys(['figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo',
  3. 'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1',
  4. 'symbol2'])
  5. In [3]: fitz.fitz_fontdescriptors["fimo"]
  6. Out[3]:
  7. {'name': 'Fira Mono Regular',
  8. 'size': 125712,
  9. 'mono': True,
  10. 'bold': False,
  11. 'italic': False,
  12. 'serif': True,
  13. 'glyphs': 1485}

If pymupdf-fonts is not installed, the dictionary is empty.

The dictionary keys can be used to define a Font via e.g. font = fitz.Font("fimo") – just like you can do it with the builtin fonts “Helvetica” and friends.


TESSDATA_PREFIX

  • New in v1.19.4

Copy of os.environ["TESSDATA_PREFIX"] for convenient checking whether there is integrated Tesseract OCR support.

If this attribute is None, Tesseract-OCR is either not installed, or the environment variable is not set to point to Tesseract’s language support folder.

Note

This variable is now checked before OCR functions are tried. This prevents verbose messages from MuPDF.


pdfcolor

  • New in v1.19.6

Contains about 500 RGB colors in PDF format with the color name as key. To see what is there, you can obviously look at fitz.pdfcolor.keys().

Examples:

  • fitz.pdfcolor["red"] = (1.0, 0.0, 0.0)

  • fitz.pdfcolor["skyblue"] = (0.5294117647058824, 0.807843137254902, 0.9215686274509803)

  • fitz.pdfcolor["wheat"] = (0.9607843137254902, 0.8705882352941177, 0.7019607843137254)


get_pdf_now()

Convenience function to return the current local timestamp in PDF compatible format, e.g. D:20170501121525-04’00’ for local datetime May 1, 2017, 12:15:25 in a timezone 4 hours westward of the UTC meridian.

  • Return type

    str

    Returns

    current local PDF timestamp.


get_text_length(text, fontname=’helv’, fontsize=11, encoding=TEXT_ENCODING_LATIN)

  • New in version 1.14.7

Calculate the length of text on output with a given builtin font, fontsize and encoding.

  • Parameters

    • text (str) – the text string.

    • fontname (str) – the fontname. Must be one of either the PDF Base 14 Fonts or the CJK fonts, identified by their “reserved” fontnames (see table in :meth.`Page.insert_font`).

    • fontsize (float) – the fontsize.

    • encoding (int) – the encoding to use. Besides 0 = Latin, 1 = Greek and 2 = Cyrillic (Russian) are available. Relevant for Base-14 fonts “Helvetica”, “Courier” and “Times” and their variants only. Make sure to use the same value as in the corresponding text insertion.

  1. Return type
  2. float
  3. Returns
  4. the length in points the string will have (e.g. when used in [Page.insert\_text()]($6e0784deec01ba37.md#Page.insert_text "Page.insert_text")).

Note

This function will only do the calculation – it won’t insert font nor text.

Note

The Font class offers a similar method, Font.text_length(), which supports Base-14 fonts and any font with a character map (CMap, Type 0 fonts).

Warning

If you use this function to determine the required rectangle width for the (Page or Shape) insert_textbox methods, be aware that they calculate on a by-character level. Because of rounding effects, this will mostly lead to a slightly larger number: sum([fitz.get_text_length(c) for c in text]) > fitz.get_text_length(text). So either (1) do the same, or (2) use something like fitz.get_text_length(text + “’”) for your calculation.


get_pdf_str(text)

Make a PDF-compatible string: if the text contains code points ord(c) > 255, then it will be converted to UTF-16BE with BOM as a hexadecimal character string enclosed in “<>” brackets like <feff…>. Otherwise, it will return the string enclosed in (round) brackets, replacing any characters outside the ASCII range with some special code. Also, every “(“, “)” or backslash is escaped with a backslash.

  • Parameters

    text (str) – the object to convert

    Return type

    str

    Returns

    PDF-compatible string enclosed in either () or <>.


image_profile(stream)

  • New in v1.16.7

  • Changed in v1.19.5: also return natural image orientation extracted from EXIF data if present.

Show important properties of an image provided as a memory area. Its main purpose is to avoid using other Python packages just to determine them.

  • Parameters

    stream (bytes|bytearray|BytesIO|file) – an image either in memory or an opened file. A memory resident image maybe any of the formats bytes, bytearray or io.BytesIO.

    Return type

    dict

    Returns

    No exception is ever raised: in case of error, the empty dictionary {} is returned. Otherwise, there are the following items:

    1. In [2]: fitz.image_profile(open("nur-ruhig.jpg", "rb").read())
    2. Out[2]:
    3. {'width': 439,
    4. 'height': 501,
    5. 'orientation': 0, # natural orientation (from EXIF)
    6. 'transform': (1.0, 0.0, 0.0, 1.0, 0.0, 0.0), # orientation matrix
    7. 'xres': 96,
    8. 'yres': 96,
    9. 'colorspace': 3,
    10. 'bpc': 8,
    11. 'ext': 'jpeg',
    12. 'cs-name': 'DeviceRGB'}

    There is the following relation to Exif information encoded in orientation, and correspondingly in the transform matrix-like (quoted from MuPDF documentation, ccw = counter-clockwise):

    1. Undefined

    2. 0 degree ccw rotation. (Exif = 1)

    3. 90 degree ccw rotation. (Exif = 8)

    4. 180 degree ccw rotation. (Exif = 3)

    5. 270 degree ccw rotation. (Exif = 6)

    6. flip on X. (Exif = 2)

    7. flip on X, then rotate ccw by 90 degrees. (Exif = 5)

    8. flip on X, then rotate ccw by 180 degrees. (Exif = 4)

    9. flip on X, then rotate ccw by 270 degrees. (Exif = 7)

    Note

    • For some “exotic” images (FAX encodings, RAW formats and the like), this method will not work and return None. You can however still work with such images in PyMuPDF, e.g. by using Document.extract_image() or create pixmaps via Pixmap(doc, xref). These methods will automatically convert exotic images to the PNG format before returning results.

    • You can also get the properties of images embedded in a PDF, via their xref. In this case make sure to extract the raw stream: fitz.image_profile(doc.xref_stream_raw(xref)).

    • Images as returned by the image blocks of Page.get_text() using “dict” or “rawdict” options are also supported.


ConversionHeader(“text”, filename=”UNKNOWN”)

Return the header string required to make a valid document out of page text outputs.

  • Parameters

    • output (str) – type of document. Use the same as the output parameter of get_text().

    • filename (str) – optional arbitrary name to use in output types “json” and “xml”.

  1. Return type
  2. str

ConversionTrailer(output)

Return the trailer string required to make a valid document out of page text outputs. See Page.get_text() for an example.

  • Parameters

    output (str) – type of document. Use the same as the output parameter of get_text().

    Return type

    str


Document.del_xml_metadata()

Delete an object containing XML-based metadata from the PDF. (Py-) MuPDF does not support XML-based metadata. Use this if you want to make sure that the conventional metadata dictionary will be used exclusively. Many thirdparty PDF programs insert their own metadata in XML format and thus may override what you store in the conventional dictionary. This method deletes any such reference, and the corresponding PDF object will be deleted during next garbage collection of the file.


Document.xml_metadata_xref()

Return the XML-based metadata xref of the PDF if present – also refer to Document.del_xml_metadata(). You can use it to retrieve the content via Document.xref_stream() and then work with it using some XML software.

  • Return type

    int

    Returns

    xref of PDF file level XML metadata – or 0 if none exists.


Page.run(dev, transform)

Run a page through a device.

  • Parameters

    • dev (Device) – Device, obtained from one of the Device constructors.

    • transform (Matrix) – Transformation to apply to the page. Set it to Identity if no transformation is desired.


Page.get_bboxlog()

  • New in v1.19.0
  • Returns

    a list of rectangles that envelop text, image or drawing objects. Each item is a tuple (type, (x0, y0, x1, y1)) where the second tuple consists of rectangle coordinates, and type is one of the following values:

    • "fill-text" – normal text (painted without character borders)

    • "stroke-text" – text showing character borders only

    • "ignore-text" – text that should not be displayed (e.g. as used by OCR text layers)

    • "fill-path" – drawing with fill color (and no border)

    • "stroke-path" – drawing with border (and no fill color)

    • "fill-image" – displays an image

    • "fill-shade" – display a shading

  1. The item sequence represents the **sequence in which these commands are executed** to build the pages appearance. Therefore, if an items bbox intersects or contains that of a previous item, then the previous item may be (partially) covered / hidden.
  2. So this list is useful to detect such situations. An items index in this list equals the value of [\`\`](#id5)”seqno\` keys you will find in the dictionaries returned by [Page.get\_drawings()]($6e0784deec01ba37.md#Page.get_drawings "Page.get_drawings") and [Page.get\_texttrace()](#Page.get_texttrace "Page.get_texttrace").

Page.get_texttrace()

  • New in v1.18.16

  • Changed in v1.19.0: added key “seqno”.

  • Changed in v1.19.1: stroke and fill colors now always are either RGB or GRAY

  • Changed in v1.19.3: span and character bboxes are now also correct if dir != (1, 0).

Return low-level text information of the page. The method is available for all document types. The result is a list of Python dictionaries with the following content:

  1. {
  2. 'ascender': 0.83251953125, # font ascender (1)
  3. 'bbox': (458.14019775390625, # span bbox x0 (7)
  4. 749.4671630859375, # span bbox y0
  5. 467.76458740234375, # span bbox x1
  6. 757.5071411132812), # span bbox y1
  7. 'bidi': 0, # bidirectional level (1)
  8. 'chars': ( # char information, tuple[tuple]
  9. (45, # unicode (4)
  10. 16, # glyph id (font dependent)
  11. (458.14019775390625, # origin.x (1)
  12. 755.3758544921875), # origin.y (1)
  13. (458.14019775390625, # char bbox x0 (6)
  14. 749.4671630859375, # char bbox y0
  15. 462.9649963378906, # char bbox x1
  16. 757.5071411132812)), # char bbox y1
  17. ( ... ), # more characters
  18. ),
  19. 'color': (0.0,), # text color, tuple[float] (1)
  20. 'colorspace': 1, # number of colorspace components (1)
  21. 'descender': -0.30029296875, # font descender (1)
  22. 'dir': (1.0, 0.0), # writing direction (1)
  23. 'flags': 12, # font flags (1)
  24. 'font': 'CourierNewPSMT', # font name (1)
  25. 'linewidth': 0.4019999980926514, # current line width value (3)
  26. 'opacity': 1.0, # alpha value of the text (5)
  27. 'seqno': 246, # sequence number (8)
  28. 'size': 8.039999961853027, # font size (1)
  29. 'spacewidth': 4.824785133358091, # width of space char
  30. 'type': 0, # span type (2)
  31. 'wmode': 0 # writing mode (1)
  32. }

Details:

  1. Information above tagged with “(1)” has the same meaning and value as explained in TextPage.

    • Please note that the font flags value will never contain a superscript flag bit: the detection of superscripts is done within MuPDF TextPage code – it is not a property of any font.

    • Also note, that the text color is encoded as the usual tuple of floats 0 <= f <= 1 – not in sRGB format. Depending on span["type"], interpret this as fill color or stroke color.

  2. There are 3 text span types:

    • 0: Filled text – equivalent to PDF text rendering mode 0 (0 Tr, the default in PDF), only each character’s “inside” is shown.

    • 1: Stroked text – equivalent to 1 Tr, only the character borders are shown.

    • 3: Ignored text – equivalent to 3 Tr (hidden text).

  3. Line width in this context is important only for processing span["type"] != 0: it determines the thickness of the character’s border line. This value may not be provided at all with the text data. In this case, a value of 5% of the fontsize (span["size"] * 0,05) is generated. Often, an “artificial” bold text in PDF is created by 2 Tr. There is no equivalent span type for this case. Instead, respective text is represented by two consecutive spans – which are identical in every aspect, except for their types, which are 0, resp 1. It is your responsibility to handle this type of situation - in Page.get_text(), MuPDF is doing this for you.

  4. For data compactness, the character’s unicode is provided here. Use built-in function chr() for the character itself.

  5. The alpha / opacity value of the span’s text, 0 <= opacity <= 1, 0 is invisible text, 1 (100%) is intransparent. Depending in span["type"], interpret this value as fill opacity or, resp. stroke opacity.

  6. (Changd in v1.19.0) This value is equal or close to char["bbox"] of “rawdict”. In particular, the bbox height value is always computed as if “small glyph heights” had been requested.

  7. (New in v1.19.0) This is the union of all character bboxes.

  8. (New in v1.19.0) Enumerates the commands that build up the page’s appearance. Can be used to find out whether text is effectively hidden by objects, whch are painted “later”, or over some object. So if there is a drawing or image with a higher sequence number, whose bbox overlaps (parts of) this text span, one may assume that such an object hides the resp. text. Different text spans have identical sequence numbers if they were created in one go.

Here is a list of similarities and differences of page.get_texttrace() compared to page.get_text("rawdict"):

  • The method is up to twice as fast, compared to “rawdict” extraction. Depends on the amount of text.

  • The returned data is very much smaller in size – although it provides more information.

  • Additional types of text invisibility can be detected: opacity = 0 or type > 1 or overlapping bbox of an object with a higher sequence number.

  • If MuPDF returns unicode 0xFFFD (65533) for unrecognized characters, you may still be able to deduct desired information from the glyph id.

  • The span["chars"] contains no spaces, except the document creator has explicitely coded them. They will never be generated like it happens in Page.get_text() methods. To provide some help for doing your own computations here, the width of a space character is given. This value is derived from the font where possible. Otherwise the value of a fallback font is taken.

  • There is no effort to organize text like it happens for a TextPage (the hierarchy of blocks, lines, spans, and characters). Characters are simply extracted in sequence, one by one, and put in a span. Whenever any of the span’s characteristics changes, a new span is started. So you may find characters with different origin.y values in the same span (which means they would appear in different lines). You cannot assume, that span characters are sorted in any particular order – you must make sense of the info yourself, taking span["dir"], span["wmode"], etc. into account.

  • Ligatures are represented like this:

    • MuPDF handles the following ligatures: “fi”, “ff”, “fl”, “ft”, “st”, “ffi”, and “ffl” (only the first 3 are mostly ever used). If the page contains e.g. ligature “fi”, you will find the following two character items subsequent to each other:

      1. (102, glyph, (x, y), (x0, y0, x1, y1)) # 102 = ord("f")
      2. (105, -1, (x, y), (x0, y0, x0, y1)) # 105 = ord("i"), empty bbox!
    • This means that the bbox of the first ligature character is the area containing the complete, compound glyph. Subsequent ligature components are recognizable by their glyph value -1 and a bbox of width zero.

    • You may want to replace those 2 or 3 char tuples by one, that represents the ligature itself. Use the following mapping of ligatures to unicodes:

      • "ff" -> 0xFB00

      • "fi" -> 0xFB01

      • "fl" -> 0xFB02

      • "ffi" -> 0xFB03

      • "ffl" -> 0xFB04

      • "ft" -> 0xFB05

      • "st" -> 0xFB06

      So you may want to replace the two example tuples above by the following single one: (0xFB01, glyph, (x, y), (x0, y0, x1, y1)) (there is usually no need to lookup the correct glyph id for 0xFB01 in the resp. font, but you may execute font.has_glyph(0xFB01) and use its return value).

  • Changed in v1.19.3: Similar to other text extraction methods, the character and span bboxes envelop the character quads. To recover the quads, follow the same methods recover_quad(), recover_char_quad() or :meth:´recover_span_quad` as explained in Structure of Dictionary Outputs. Use either None or span["dir"] for the writing direction.

Page.wrap_contents()

Put string pair “q” / “Q” before, resp. after a page’s /Contents object(s) to ensure that any “geometry” changes are local only.

Use this method as an alternative, minimalistic version of Page.clean_contents(). Its advantage is a small footprint in terms of processing time and impact on the data size of incremental saves. Multiple executions of this method are no problem and have no functional impact: b"q q contents Q Q" is treated like b"q contents Q".


Page.is_wrapped

Indicate whether Page.wrap_contents() may be required for object insertions in standard PDF geometry. Note that this is a quick, basic check only: a value of False may still be a false alarm. But nevertheless executing Page.wrap_contents() will have no negative side effects.

  • Return type

    bool


Page.get_text_blocks(flags=None)

Deprecated wrapper for TextPage.extractBLOCKS(). Use Page.get_text() with the “blocks” option instead.

  • Return type

    list[tuple]


Page.get_text_words(flags=None)

Deprecated wrapper for TextPage.extractWORDS(). Use Page.get_text() with the “words” option instead.

  • Return type

    list[tuple]


Page.get_displaylist()

Run a page through a list device and return its display list.

  • Return type

    DisplayList

    Returns

    the display list of the page.


Page.get_contents()

PDF only: Retrieve a list of xref of contents objects of a page. May be empty or contain multiple integers. If the page is cleaned (Page.clean_contents()), it will be one entry at most. The “source” of each /Contents object can be individually read by Document.xref_stream() using an item of this list. Method Page.read_contents() in contrast walks through this list and concatenates the corresponding sources into one bytes object.

  • Return type

    list[int]


Page.set_contents(xref)

PDF only: Let the page’s /Contents key point to this xref. Any previously used contents objects will be ignored and can be removed via garbage collection.


Page.clean_contents(sanitize=True)

  • Changed in v1.17.6

PDF only: Clean and concatenate all contents objects associated with this page. “Cleaning” includes syntactical corrections, standardizations and “pretty printing” of the contents stream. Discrepancies between contents and resources objects will also be corrected if sanitize is true. See Page.get_contents() for more details.

Changed in version 1.16.0 Annotations are no longer implicitely cleaned by this method. Use Annot.clean_contents() separately.

  • Parameters

    sanitize (bool) – (new in v1.17.6) if true, synchronization between resources and their actual use in the contents object is snychronized. For example, if a font is not actually used for any text of the page, then it will be deleted from the /Resources/Font object.

Warning

This is a complex function which may generate large amounts of new data and render old data unused. It is not recommended using it together with the incremental save option. Also note that the resulting singleton new /Contents object is uncompressed. So you should save to a new file using options “deflate=True, garbage=3”.


Page.read_contents()

New in version 1.17.0. Return the concatenation of all contents objects associated with the page – without cleaning or otherwise modifying them. Use this method whenever you need to parse this source in its entirety whithout having to bother how many separate contents objects exist.

  • Return type

    bytes


Annot.clean_contents(sanitize=True)

Clean the contents streams associated with the annotation. This is the same type of action which Page.clean_contents() performs – just restricted to this annotation.


Document.get_char_widths(xref=0, limit=256)

Return a list of character glyphs and their widths for a font that is present in the document. A font must be specified by its PDF cross reference number xref. This function is called automatically from Page.insert_text() and Page.insert_textbox(). So you should rarely need to do this yourself.

  • Parameters

    • xref (int) – cross reference number of a font embedded in the PDF. To find a font xref, use e.g. doc.get_page_fonts(pno) of page number pno and take the first entry of one of the returned list entries.

    • limit (int) – limits the number of returned entries. The default of 256 is enforced for all fonts that only support 1-byte characters, so-called “simple fonts” (checked by this method). All PDF Base 14 Fonts are simple fonts.

  1. Return type
  2. list
  3. Returns
  4. a list of *limit* tuples. Each character *c* has an entry *(g, w)* in this list with an index of *ord(c)*. Entry *g* (integer) of the tuple is the glyph id of the character, and float *w* is its normalized width. The actual width for some fontsize can be calculated as *w \* fontsize*. For simple fonts, the *g* entry can always be safely ignored. In all other cases *g* is the basis for graphically representing *c*.

This function calculates the pixel width of a string called text:

  1. def pixlen(text, widthlist, fontsize):
  2. try:
  3. return sum([widthlist[ord(c)] for c in text]) * fontsize
  4. except IndexError:
  5. raise ValueError:("max. code point found: %i, increase limit" % ord(max(text)))

Document.is_stream(xref)

  • New in version 1.14.14

PDF only: Check whether the object represented by xref is a stream type. Return is False if not a PDF or if the number is outside the valid xref range.

  • Parameters

    xref (int) – xref number.

    Returns

    True if the object definition is followed by data wrapped in keyword pair stream, endstream.


Document.get_new_xref()

Increase the xref by one entry and return that number. This can then be used to insert a new object.

  • Return type

    int :returns: the number of the new xref entry. Please note, that only a new entry in the PDF’s cross reference table is created. At this point, there will not yet exist a PDF object associated with it. To create an (empty) object with this number use doc.update_xref(xref, "<<>>").


Document.xref_length()

Return length of xref table.

  • Return type

    int

    Returns

    the number of entries in the xref table.


recover_quad(line_dir, span)

Compute the quadrilateral of a text span extracted via options “dict” or “rawdict” of Page.get_text().

  • Parameters

    • line_dir (tuple) – line["dir"] of the owning line. Use None for a span from Page.get_texttrace().

    • span (dict) – the span.

  1. Returns
  2. the [Quad]($743984f04146fd18.md#quad) of the span, usable for text marker annotations (‘Highlight’, etc.).

recover_char_quad(line_dir, span, char)

Compute the quadrilateral of a text character extracted via option “rawdict” of Page.get_text().

  • Parameters

    • line_dir (tuple) – line["dir"] of the owning line. Use None for a span from Page.get_texttrace().

    • span (dict) – the span.

    • char (dict) – the character.

  1. Returns
  2. the [Quad]($743984f04146fd18.md#quad) of the character, usable for text marker annotations (‘Highlight’, etc.).

recover_span_quad(line_dir, span, chars=None)

Compute the quadrilateral of a subset of characters of a span extracted via option “rawdict” of Page.get_text().

  • Parameters

    • line_dir (tuple) – line["dir"] of the owning line. Use None for a span from Page.get_texttrace().

    • span (dict) – the span.

    • chars (list) – the characters to consider. If omitted, identical to recoer_span(). If given, the selected extraction option must be “rawdict”.

  1. Returns
  2. the [Quad]($743984f04146fd18.md#quad) of the selected characters, usable for text marker annotations (‘Highlight’, etc.).

recover_line_quad(line, spans=None)

Compute the quadrilateral of a subset of spans of a text line extracted via options “dict” or “rawdict” of Page.get_text().

  • Parameters

    • line (dict) – the line.

    • spans (list) – a sub-list of line["spans"]. If omitted, the full line quad will be returned.

  1. Returns
  2. the [Quad]($743984f04146fd18.md#quad) of the selected line spans, usable for text marker annotations (‘Highlight’, etc.).

INFINITE_QUAD()

INFINITE_RECT()

INFINITE_IRECT()

Return the (unique) infinite rectangle Rect(-2147483648.0, -2147483648.0, 2147483520.0, 2147483520.0), resp. the IRect and Quad counterparts. It is the largest possible rectangle: all valid rectangles are contained in it.


EMPTY_QUAD()

EMPTY_RECT()

EMPTY_IRECT()

Return the “standard” empty and invalid rectangle Rect(2147483520.0, 2147483520.0, -2147483648.0, -2147483648.0) resp. quad. Its top-left and bottom-right point values are reversed compared to the infinite rectangle. It will e.g. be used to indicate empty bboxes in page.get_text("dict") dictionaries. There are however infinitely many empty or invalid rectangles.