Skip to content

Data API

Overview

The playa.data module contains schemas (as TypedDict) and extractors for metadata and content from various PLAYA objects, as well as a single-dispatch function playa.data.asobj to extract said metadata from any object. This is an entirely non-lazy API. It is provided here because the PLAYA CLI uses it, and to discourage users of the library from reimplementing it themselves.

Many PLAYA objects are already dataclass or NamedTuple so they have a function or method to convert them to dict, but for a variety of reasons you shouldn't actually use this function. See here for dataclasses.asdict and its many pitfalls.

The distinction between "metadata" and "content" is admittedly not very clear for PDF. Metadata, represented by the schemas in playa.data.metadata, is:

  • attributes of pages, content streams, etc (uncontroversial)
  • outline and logical structure nodes and their properties (but not their contents)
  • annotations and their properties
  • articles and threads (TODO: PLAYA doesn't support these yet, I need to find some PDFs that have them)

Content, represented by the schemas in playa.data.content, is:

  • data in content streams (except for object streams, obviously)
  • anything that is a ContentObject (so, paths, images, glyphs)
  • marked content sections (as these cannot be created without actually parsing the content streams)

Note that the CLI doesn't exactly break things down along those lines. In particular, the default metadata output doesn't include outlines, logical structure trees, or annotations. In general, if you have performance concerns you are always better off using the lazy API, then calling asobj on specific objects as needed, as extracting all the metadata (not even the content) may be fairly slow.

Data and Metadata Objects

All of these objects are accessible through the playa.data module.

Annotation

Bases: TypedDict

Source code in playa/data/metadata.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
class Annotation(TypedDict, total=False):
    type: str
    """Type of annotation."""
    bbox: Rect
    """Bounding rectangle for annotation."""
    contents: str
    """Text contents."""
    name: str
    """Annotation name, uniquely identifying this annotation."""
    mtime: str
    """String describing date and time when annotation was most recently
    modified."""
    destination: Destination
    """Destination of a link annotation."""
    action: Action
    """Action for a link annotation."""

action instance-attribute

Action for a link annotation.

bbox instance-attribute

Bounding rectangle for annotation.

contents instance-attribute

Text contents.

destination instance-attribute

Destination of a link annotation.

mtime instance-attribute

String describing date and time when annotation was most recently modified.

name instance-attribute

Annotation name, uniquely identifying this annotation.

type instance-attribute

Type of annotation.

Color

Bases: TypedDict

Source code in playa/data/content.py 
127
128
129
130
131
class Color(TypedDict, total=False):
    values: Tuple[float, ...]
    """Component values."""
    pattern: Union[str, None]
    """Pattern name in page resources, if any."""

pattern instance-attribute

Pattern name in page resources, if any.

values instance-attribute

Component values.

ColorSpace

Bases: TypedDict

Source code in playa/data/content.py 
134
135
136
137
138
139
140
class ColorSpace(TypedDict, total=False):
    name: str
    """Name of colour space."""
    ncomponents: int
    """Number of components."""
    spec: list
    """Specification."""

name instance-attribute

Name of colour space.

ncomponents instance-attribute

Number of components.

spec instance-attribute

Specification.

DashPattern

Bases: TypedDict

Source code in playa/data/content.py 
120
121
122
123
124
class DashPattern(TypedDict, total=False):
    dash: Tuple[float, ...]
    """Lengths of dashes and gaps in user space units."""
    phase: float
    """Starting position in the dash pattern, default 0."""

dash instance-attribute

Lengths of dashes and gaps in user space units.

phase instance-attribute

Starting position in the dash pattern, default 0.

Destination

Bases: TypedDict

Destination for an outline entry or annotation.

Source code in playa/data/metadata.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class Destination(TypedDict, total=False):
    """Destination for an outline entry or annotation."""

    page_idx: int
    """Zero-based index of destination page."""
    display: str
    """How to display the destination on that page."""
    pos: Point
    """Target position."""
    top: float
    """Target top edge."""
    left: float
    """Target left edge."""
    bbox: Rect
    """Target zoom box."""
    zoom: float
    """Zoom factor."""

bbox instance-attribute

Target zoom box.

display instance-attribute

How to display the destination on that page.

left instance-attribute

Target left edge.

page_idx instance-attribute

Zero-based index of destination page.

pos instance-attribute

Target position.

top instance-attribute

Target top edge.

zoom instance-attribute

Zoom factor.

Document

Bases: TypedDict

Metadata for a PDF document.

Source code in playa/data/metadata.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
class Document(TypedDict, total=False):
    """Metadata for a PDF document."""

    pdf_version: str
    """Version of the PDF standard this document implements."""
    is_printable: bool
    """Should the user be allowed to print?"""
    is_modifiable: bool
    """Should the user be allowed to modify?"""
    is_extractable: bool
    """Should the user be allowed to extract text?"""
    encryption: "Encryption"
    """Encryption information for this document."""
    outlines: List["Outline"]
    """Outline for this document."""
    destinations: Dict[str, "Destination"]
    """Named destinations for this document."""
    structure: "StructTree"
    """Logical structure for this document.."""
    pages: List["Page"]
    """Pages in this document."""
    objects: List["IndirectObject"]
    """Indirect objects in this document."""

destinations instance-attribute

Named destinations for this document.

encryption instance-attribute

Encryption information for this document.

is_extractable instance-attribute

Should the user be allowed to extract text?

is_modifiable instance-attribute

Should the user be allowed to modify?

is_printable instance-attribute

Should the user be allowed to print?

objects instance-attribute

Indirect objects in this document.

outlines instance-attribute

Outline for this document.

pages instance-attribute

Pages in this document.

pdf_version instance-attribute

Version of the PDF standard this document implements.

structure instance-attribute

Logical structure for this document..

Encryption

Bases: TypedDict

Encryption information.

Source code in playa/data/metadata.py 
81
82
83
84
85
86
87
class Encryption(TypedDict, total=False):
    """Encryption information."""

    ids: Tuple[str, str]
    """ID values for encryption."""
    encrypt: dict
    """Encryption properties."""

encrypt instance-attribute

Encryption properties.

ids instance-attribute

ID values for encryption.

Font

Bases: TypedDict

Source code in playa/data/metadata.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
class Font(TypedDict, total=False):
    name: str
    """Font name."""
    type: str
    """Font type (Type1, Type0, TrueType, Type3, etc)."""
    ascent: float
    """Ascent in glyph space units."""
    descent: float
    """Descent in glyph space units."""
    italic_angle: float
    """Italic angle."""
    default_width: float
    """Default character width in glyph space units."""
    leading: float
    """Leading in glyph space units."""
    cap_height: float
    """Top of capital letters, in glyph space units."""
    xheight: float
    """Top of flat nonascending lowercase letters, in glyph space units."""
    stem_v: float
    """Thickness of dominant vertical stems."""
    stem_h: float
    """Thickness of dominant horizontal stems."""
    avg_width: float
    """Average width of glyphs in glyph space units."""
    max_width: float
    """Maximum width of glyphs in glyph space units."""
    stretch: str
    """Font stretch value (e.g. Condensed, Expanded)."""
    weight: float
    """Numeric weight value (100, 200, 300... 900)"""
    flags: List[str]
    """Set of flags (e.g. FixedPitch, Script, etc) for this font."""
    bbox: Rect
    """Bounding box in glyph space units."""
    matrix: Matrix
    """Matrix mapping glyph space to text space (Type3 fonts only)."""
    cidfont: "Font"
    """Descendant CIDFont (Type0 fonts only)."""

ascent instance-attribute

Ascent in glyph space units.

avg_width instance-attribute

Average width of glyphs in glyph space units.

bbox instance-attribute

Bounding box in glyph space units.

cap_height instance-attribute

Top of capital letters, in glyph space units.

cidfont instance-attribute

Descendant CIDFont (Type0 fonts only).

default_width instance-attribute

Default character width in glyph space units.

descent instance-attribute

Descent in glyph space units.

flags instance-attribute

Set of flags (e.g. FixedPitch, Script, etc) for this font.

italic_angle instance-attribute

Italic angle.

leading instance-attribute

Leading in glyph space units.

matrix instance-attribute

Matrix mapping glyph space to text space (Type3 fonts only).

max_width instance-attribute

Maximum width of glyphs in glyph space units.

name instance-attribute

Font name.

stem_h instance-attribute

Thickness of dominant horizontal stems.

stem_v instance-attribute

Thickness of dominant vertical stems.

stretch instance-attribute

Font stretch value (e.g. Condensed, Expanded).

type instance-attribute

Font type (Type1, Type0, TrueType, Type3, etc).

weight instance-attribute

Numeric weight value (100, 200, 300... 900)

xheight instance-attribute

Top of flat nonascending lowercase letters, in glyph space units.

Glyph

Bases: TypedDict

Source code in playa/data/content.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
class Glyph(TypedDict, total=False):
    text: str
    """Unicode string representation of glyph, if any."""
    cid: int
    """Character ID for glyph in font."""
    bbox: Union[Rect, None]
    """Bounding rectangle."""
    matrix: Matrix
    """Rendering matrix for glyph.  Note that the effective font size
    and the origin can be derived from this."""
    displacement: Point
    """Displacement to origin of next glyph."""
    gstate: "GraphicState"
    """Graphic state."""
    mcstack: List["Tag"]
    """Stack of enclosing marked content sections."""

bbox instance-attribute

Bounding rectangle.

cid instance-attribute

Character ID for glyph in font.

displacement instance-attribute

Displacement to origin of next glyph.

gstate instance-attribute

Graphic state.

matrix instance-attribute

Rendering matrix for glyph. Note that the effective font size and the origin can be derived from this.

mcstack instance-attribute

Stack of enclosing marked content sections.

text instance-attribute

Unicode string representation of glyph, if any.

GraphicState

Bases: TypedDict

Source code in playa/data/content.py 
 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
class GraphicState(TypedDict, total=False):
    clipping_path: None  # TODO
    """The current clipping path (sec. 8.5.4), default `None`"""
    linewidth: float
    """Line width in user space units (sec. 8.4.3.2), default 1"""
    linecap: int
    """Line cap style (sec. 8.4.3.3), default 0 """
    linejoin: int
    """Line join style (sec. 8.4.3.4), default 0"""
    miterlimit: float
    """Maximum length of mitered line joins (sec. 8.4.3.5), default 10"""
    dash: "DashPattern"
    """Dash pattern for stroking (sec 8.4.3.6), default solid line `((), 0)`"""
    intent: str
    """Rendering intent (sec. 8.6.5.8), default `RelativeColorimetric`'"""
    stroke_adjustment: bool
    """A flag specifying whether to compensate for possible rasterization
    effects when stroking a path with a line width that is small relative to
    the pixel resolution of the output device (sec. 10.7.5), default `False`"""
    blend_mode: Union[str, List[str]]
    """The current blend mode that shall be used in the transparent imaging
    model (sec. 11.3.5), default `Normal`"""
    smask: Union[None, dict]
    """A soft-mask dictionary (sec. 11.6.5.1) or None, default `None`"""
    salpha: float
    """The constant shape or constant opacity value used for stroking
    operations (sec. 11.3.7.2 & 11.6.4.4), default 1"""
    nalpha: float
    """The constant shape or constant opacity value used for non-stroking
    operations, default 1"""
    alpha_source: bool
    """A flag specifying whether the current soft mask and alpha constant
    parameters shall be interpreted as shape values (true) or opacity values
    (false), default `False`"""
    black_pt_comp: str
    """The black point compensation algorithm that shall be used when
    converting CIE-based colours (sec. 8.6.5.9), default `Default`"""
    flatness: float
    """The precision with which curves shall be rendered on
    the output device (sec. 10.6.2), default 1"""
    scolor: "Color"
    """Colour used for stroking operations, default black `((0,), None)`"""
    scs: "ColorSpace"
    """Colour space used for stroking operations, default `DeviceGray`"""
    ncolor: "Color"
    """Colour used for non-stroking operations, default black `((0,) None)`"""
    ncs: "ColorSpace"
    """Colour space used for non-stroking operations, default `DeviceGray`"""
    font: Font
    """Descriptor of current font."""
    fontsize: float
    """Font size in unscaled text space units (**not** in points, can
    be scaled using a text or glyph's `matrix` to obtain user space
    units), default if not present is 1.0."""
    charspace: float
    """Character spacing in unscaled text space units, default if not present is 0."""
    wordspace: float
    """Word spacing in unscaled text space units, default if not present is 0."""
    scaling: float
    """Horizontal scaling factor multiplied by 100, default if not present is 100."""
    leading: float
    """Leading in unscaled text space units, default if not present is 0."""
    render_mode: int
    """Text rendering mode (PDF 1.7 Table 106), default if not present is 0."""
    rise: float
    """Text rise (for super and subscript) in unscaled text space
    units, default if not present is 0."""
    knockout: bool
    """The text knockout flag, shall determine the behaviour of overlapping
    glyphs within a text object in the transparent imaging model (sec. 9.3.8),
    default `True`"""

alpha_source instance-attribute

A flag specifying whether the current soft mask and alpha constant parameters shall be interpreted as shape values (true) or opacity values (false), default False

black_pt_comp instance-attribute

The black point compensation algorithm that shall be used when converting CIE-based colours (sec. 8.6.5.9), default Default

blend_mode instance-attribute

The current blend mode that shall be used in the transparent imaging model (sec. 11.3.5), default Normal

charspace instance-attribute

Character spacing in unscaled text space units, default if not present is 0.

clipping_path instance-attribute

The current clipping path (sec. 8.5.4), default None

dash instance-attribute

Dash pattern for stroking (sec 8.4.3.6), default solid line ((), 0)

flatness instance-attribute

The precision with which curves shall be rendered on the output device (sec. 10.6.2), default 1

font instance-attribute

Descriptor of current font.

fontsize instance-attribute

Font size in unscaled text space units (not in points, can be scaled using a text or glyph's matrix to obtain user space units), default if not present is 1.0.

intent instance-attribute

Rendering intent (sec. 8.6.5.8), default RelativeColorimetric'

knockout instance-attribute

The text knockout flag, shall determine the behaviour of overlapping glyphs within a text object in the transparent imaging model (sec. 9.3.8), default True

leading instance-attribute

Leading in unscaled text space units, default if not present is 0.

linecap instance-attribute

Line cap style (sec. 8.4.3.3), default 0

linejoin instance-attribute

Line join style (sec. 8.4.3.4), default 0

linewidth instance-attribute

Line width in user space units (sec. 8.4.3.2), default 1

miterlimit instance-attribute

Maximum length of mitered line joins (sec. 8.4.3.5), default 10

nalpha instance-attribute

The constant shape or constant opacity value used for non-stroking operations, default 1

ncolor instance-attribute

Colour used for non-stroking operations, default black ((0,) None)

ncs instance-attribute

Colour space used for non-stroking operations, default DeviceGray

render_mode instance-attribute

Text rendering mode (PDF 1.7 Table 106), default if not present is 0.

rise instance-attribute

Text rise (for super and subscript) in unscaled text space units, default if not present is 0.

salpha instance-attribute

The constant shape or constant opacity value used for stroking operations (sec. 11.3.7.2 & 11.6.4.4), default 1

scaling instance-attribute

Horizontal scaling factor multiplied by 100, default if not present is 100.

scolor instance-attribute

Colour used for stroking operations, default black ((0,), None)

scs instance-attribute

Colour space used for stroking operations, default DeviceGray

smask instance-attribute

A soft-mask dictionary (sec. 11.6.5.1) or None, default None

stroke_adjustment instance-attribute

A flag specifying whether to compensate for possible rasterization effects when stroking a path with a line width that is small relative to the pixel resolution of the output device (sec. 10.7.5), default False

wordspace instance-attribute

Word spacing in unscaled text space units, default if not present is 0.

Image

Bases: TypedDict

Source code in playa/data/content.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
class Image(TypedDict, total=False):
    ctm: Matrix
    """Coordinate transformation matrix, default is `(1, 0, 0, 1, 0, 0)`"""
    xobject_name: str
    """Name of XObject in page resources, if any."""
    bbox: Union[Rect, None]
    """Bounding rectangle for image."""
    srcsize: Tuple[int, int]
    """Size of source image in pixels."""
    bits: int
    """Number of bits per component, if required (default 1)."""
    imagemask: bool
    """True if the image is a mask."""
    stream: dict
    """Content stream dictionary."""
    colorspace: Union[ColorSpace, None]
    """Colour space for this image, if required."""

bbox instance-attribute

Bounding rectangle for image.

bits instance-attribute

Number of bits per component, if required (default 1).

colorspace instance-attribute

Colour space for this image, if required.

ctm instance-attribute

Coordinate transformation matrix, default is (1, 0, 0, 1, 0, 0)

imagemask instance-attribute

True if the image is a mask.

srcsize instance-attribute

Size of source image in pixels.

stream instance-attribute

Content stream dictionary.

xobject_name instance-attribute

Name of XObject in page resources, if any.

IndirectObject

Bases: TypedDict

Source code in playa/data/metadata.py 
252
253
254
255
256
257
258
259
260
class IndirectObject(TypedDict, total=False):
    objid: int
    """Indirect object ID."""
    genno: int
    """Generation number."""
    type: str
    """Name of Python type to which this object was converted."""
    obj: Union[float, int, str, bool, dict, list]
    """Object metadata (for streams) or data (otherwise)."""

genno instance-attribute

Generation number.

obj instance-attribute

Object metadata (for streams) or data (otherwise).

objid instance-attribute

Indirect object ID.

type instance-attribute

Name of Python type to which this object was converted.

MarkedContent

Bases: TypedDict

Source code in playa/data/content.py 
143
144
145
146
147
148
149
class MarkedContent(TypedDict, total=False):
    name: str
    """Marked content section tag name."""
    mcid: int
    """Marked content section ID."""
    props: dict
    """Marked content property dictionary (without MCID)."""

mcid instance-attribute

Marked content section ID.

name instance-attribute

Marked content section tag name.

props instance-attribute

Marked content property dictionary (without MCID).

Outline

Bases: TypedDict

Outline item for a PDF document.

Source code in playa/data/metadata.py 
90
91
92
93
94
95
96
97
98
class Outline(TypedDict, total=False):
    """Outline item for a PDF document."""

    title: str
    """Title of this outline entry."""
    destination: "Destination"
    """Destination (or target of GoTo action)."""
    children: List["Outline"]
    """Children of this entry."""

children instance-attribute

Children of this entry.

destination instance-attribute

Destination (or target of GoTo action).

title instance-attribute

Title of this outline entry.

Page

Bases: TypedDict

Metadata for a PDF page.

Source code in playa/data/metadata.py 
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class Page(TypedDict, total=False):
    """Metadata for a PDF page."""

    page_idx: int
    """0-based page number."""
    page_label: Union[str, None]
    """Page label (could be roman numerals, letters, etc)."""
    page_id: int
    """Indirect object ID."""
    mediabox: Rect
    """Extent of physical page, in base units (1/72 inch)."""
    cropbox: Rect
    """Extent of visible area, in base units (1/72 inch)."""
    rotate: int
    """Page rotation in degrees."""
    resources: "Resources"
    """Page resources."""
    annotations: List["Annotation"]
    """Page annotations."""
    contents: List["StreamObject"]
    """Metadata for content streams."""

annotations instance-attribute

Page annotations.

contents instance-attribute

Metadata for content streams.

cropbox instance-attribute

Extent of visible area, in base units (1/72 inch).

mediabox instance-attribute

Extent of physical page, in base units (1/72 inch).

page_id instance-attribute

Indirect object ID.

page_idx instance-attribute

0-based page number.

page_label instance-attribute

Page label (could be roman numerals, letters, etc).

resources instance-attribute

Page resources.

rotate instance-attribute

Page rotation in degrees.

Path

Bases: TypedDict

Source code in playa/data/content.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
class Path(TypedDict, total=False):
    ctm: Matrix
    """Coordinate transformation matrix, default is `(1, 0, 0, 1, 0, 0)`"""
    stroke: bool
    """True if the outline of the path is stroked."""
    fill: bool
    """True if the path is filled."""
    evenodd: bool
    """True if the filling of complex paths uses the even-odd
    winding rule, False if the non-zero winding number rule is
    used (PDF 1.7 section 8.5.3.3)"""
    segments: List["PathSegment"]
    """Path segments."""
    gstate: "GraphicState"
    """Graphic state."""
    mcstack: List["Tag"]
    """Stack of enclosing marked content sections."""

ctm instance-attribute

Coordinate transformation matrix, default is (1, 0, 0, 1, 0, 0)

evenodd instance-attribute

True if the filling of complex paths uses the even-odd winding rule, False if the non-zero winding number rule is used (PDF 1.7 section 8.5.3.3)

fill instance-attribute

True if the path is filled.

gstate instance-attribute

Graphic state.

mcstack instance-attribute

Stack of enclosing marked content sections.

segments instance-attribute

Path segments.

stroke instance-attribute

True if the outline of the path is stroked.

PathSegment

Bases: TypedDict

Source code in playa/data/content.py 
199
200
201
202
203
204
class PathSegment(TypedDict, total=False):
    operator: str
    """Normalized path operator (PDF 1.7 section 8.5.2).  Note that "re"
    will be expanded into its constituent line segments."""
    points: List[Point]
    """Point or control points for path segment."""

operator instance-attribute

Normalized path operator (PDF 1.7 section 8.5.2). Note that "re" will be expanded into its constituent line segments.

points instance-attribute

Point or control points for path segment.

Resources

Bases: TypedDict

Source code in playa/data/metadata.py 
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
class Resources(TypedDict, total=False):
    ext_gstates: Dict[str, dict]
    """Extended graphic state dictionaries."""
    color_spaces: Dict[str, Any]
    """Color space descriptors."""
    patterns: Dict[str, Any]
    """Pattern objects."""
    shadings: Dict[str, dict]
    """Shading dictionaries."""
    xobjects: Dict[str, "XObject"]
    """XObject streams."""
    fonts: Dict[str, Font]
    """Font dictionaries."""
    procsets: List[str]
    """Procedure set names."""
    properties: Dict[str, dict]
    """property dictionaires."""

color_spaces instance-attribute

Color space descriptors.

ext_gstates instance-attribute

Extended graphic state dictionaries.

fonts instance-attribute

Font dictionaries.

patterns instance-attribute

Pattern objects.

procsets instance-attribute

Procedure set names.

properties instance-attribute

property dictionaires.

shadings instance-attribute

Shading dictionaries.

xobjects instance-attribute

XObject streams.

StreamObject

Bases: TypedDict

Source code in playa/data/metadata.py 
239
240
241
242
243
244
245
246
247
248
249
class StreamObject(TypedDict, total=False):
    stream_id: int
    """Indirect object ID."""
    genno: int
    """Generation number."""
    length: int
    """Length of raw stream data."""
    filters: List[str]
    """List of filters."""
    params: List[dict]
    """Filter parameters."""

filters instance-attribute

List of filters.

genno instance-attribute

Generation number.

length instance-attribute

Length of raw stream data.

params instance-attribute

Filter parameters.

stream_id instance-attribute

Indirect object ID.

StructElement

Bases: TypedDict

Node in logical structure tree.

Source code in playa/data/metadata.py 
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
class StructElement(TypedDict, total=False):
    """Node in logical structure tree."""

    type: str
    """Type of structure element (or "StructTreeRoot" for root)."""
    role: str
    """Role of structure element (root has no role)."""
    page_idx: int
    """Page on which this structure element's content begins."""
    title: str
    """Title of structure element."""
    language: str
    """Language of structure element."""
    alternate_description: str
    """Alternate description."""
    abbreviation_expansion: str
    """Abbreviation expansion."""
    actual_text: str
    """Unicode text content."""
    children: List["StructElement"]
    """Children of this node."""
    attributes: dict
    """Structure attributes."""
    class_name: str
    """Structure attribute class name."""

abbreviation_expansion instance-attribute

Abbreviation expansion.

actual_text instance-attribute

Unicode text content.

alternate_description instance-attribute

Alternate description.

attributes instance-attribute

Structure attributes.

children instance-attribute

Children of this node.

class_name instance-attribute

Structure attribute class name.

language instance-attribute

Language of structure element.

page_idx instance-attribute

Page on which this structure element's content begins.

role instance-attribute

Role of structure element (root has no role).

title instance-attribute

Title of structure element.

type instance-attribute

Type of structure element (or "StructTreeRoot" for root).

StructTree

Bases: TypedDict

Logical structure tree for a PDF document.

Source code in playa/data/metadata.py 
174
175
176
177
178
class StructTree(TypedDict, total=False):
    """Logical structure tree for a PDF document."""

    root: StructElement
    """Root node of the tree."""

root instance-attribute

Root node of the tree.

Tag

Bases: TypedDict

Source code in playa/data/content.py 
152
153
154
155
156
157
158
class Tag(TypedDict, total=False):
    name: str
    """Tag name."""
    mcid: int
    """Marked content section ID."""
    props: dict
    """Marked content property dictionary (without MCID)."""

mcid instance-attribute

Marked content section ID.

name instance-attribute

Tag name.

props instance-attribute

Marked content property dictionary (without MCID).

Text

Bases: TypedDict

Source code in playa/data/content.py 
33
34
35
36
37
38
39
40
41
42
43
44
class Text(TypedDict, total=False):
    chars: str
    """Unicode string representation of text."""
    bbox: Union[Rect, None]
    """Bounding rectangle for all glyphs in text."""
    matrix: Matrix
    """Text rendering matrix.  Note that the effective font size
    and the origin can be derived from this."""
    gstate: "GraphicState"
    """Graphic state."""
    mcstack: List["Tag"]
    """Stack of enclosing marked content sections."""

bbox instance-attribute

Bounding rectangle for all glyphs in text.

chars instance-attribute

Unicode string representation of text.

gstate instance-attribute

Graphic state.

matrix instance-attribute

Text rendering matrix. Note that the effective font size and the origin can be derived from this.

mcstack instance-attribute

Stack of enclosing marked content sections.

XObject

Bases: TypedDict

Source code in playa/data/metadata.py 
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
class XObject(TypedDict, total=False):
    type: str
    """Type of XObject."""
    xobject_id: int
    """Indirect object ID."""
    genno: int
    """Generation number."""
    length: int
    """Length of raw stream data."""
    filters: List[str]
    """List of filters."""
    params: List[dict]
    """Filter parameters."""
    resources: "Resources"
    """Resources specific to this XObject, if any."""

filters instance-attribute

List of filters.

genno instance-attribute

Generation number.

length instance-attribute

Length of raw stream data.

params instance-attribute

Filter parameters.

resources instance-attribute

Resources specific to this XObject, if any.

type instance-attribute

Type of XObject.

xobject_id instance-attribute

Indirect object ID.

asobj(obj)

JSON serializable representation of PDF object metadata.

Source code in playa/data/_asobj.py 
12
13
14
15
16
17
18
19
20
21
@functools.singledispatch
def asobj(obj):
    """JSON serializable representation of PDF object metadata."""
    # functools.singledispatch can't register None
    if obj is None:
        return None
    # Catch dataclasses that don't have a specific serializer
    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
        return {k: asobj(v) for k, v in obj.__dict__.items()}
    return repr(obj)