Shared classes

Length objects

Length values in python-docx are expressed as a standardized Length value object. Length is a subclass of int, having all the behavior of an int. In addition, it has built-in units conversion properties, e.g.:

>>> inline_shape.height
914400
>>> inline_shape.height.inches
1.0

Length objects are constructed using a selection of convenience constructors, allowing values to be expressed in the units most appropriate to the context.

class docx.shared.Length

Base class for length constructor classes Inches, Cm, Mm, Px, and Emu. Behaves as an int count of English Metric Units, 914,400 to the inch, 36,000 to the mm. Provides convenience unit conversion methods in the form of read-only properties. Immutable.

cm

The equivalent length expressed in centimeters (float).

emu

The equivalent length expressed in English Metric Units (int).

inches

The equivalent length expressed in inches (float).

mm

The equivalent length expressed in millimeters (float).

pt

Floating point length in points

twips

The equivalent length expressed in twips (int).

class docx.shared.Inches

Convenience constructor for length in inches, e.g. width = Inches(0.5).

class docx.shared.Cm

Convenience constructor for length in centimeters, e.g. height = Cm(12).

class docx.shared.Mm

Convenience constructor for length in millimeters, e.g. width = Mm(240.5).

class docx.shared.Pt

Convenience value class for specifying a length in points

class docx.shared.Twips

Convenience constructor for length in twips, e.g. width = Twips(42). A twip is a twentieth of a point, 635 EMU.

class docx.shared.Emu

Convenience constructor for length in English Metric Units, e.g. width = Emu(457200).

RGBColor objects

class docx.shared.RGBColor(r, g, b)

Immutable value object defining a particular RGB color.

r, g, and b are each an integer in the range 0-255 inclusive. Using the hexidecimal integer notation, e.g. 0x42 may enhance readability where hex RGB values are in use:

>>> lavender = RGBColor(0xff, 0x99, 0xcc)

classmethod from_string(rgb_hex_str)

Return a new instance from an RGB color hex string like '3C2F80'.