OpenDocumentClasses

The OpenDocument classes

The OpenDocumentChart, OpenDocumentDrawing, OpenDocumentImage, OpenDocumentPresentation, OpenDocumentSpreadsheet and OpenDocumentText classes derive from the OpenDocument class. These methods are available:

• save(filename, addsuffix=False) This method will write to a file what you have constructed. If you provide the argument addsuffix=True, it will add the “.od?” suffix to the filename automatically based on the class name.

• write(fileobject) Writes the document to a file-like object of the type available from StringIO.

• addPicture(filename, mediatype=None, content=None) Adds a file to the Pictures directory in the zip archive and adds the new filename to the manifest. If content is not None, then use this as the image rather than open the filename. The return value is the new file name, which you can use for the href attribute in the draw.Image class. If mediatype is None, then guess the mediatype from the file name.

• addThumbnail(content=None) If content is None, adds a nice 128x128 pixel, but rather bulky thumbnail to the document. Otherwise the content must be a png image in memory that will then be added to the document.

• addObject(object) Adds a subobject to the document. The return value is the folder name of the object in the document container, which you use for the href attribute in the draw.Object class.

• xml() Generates the full document as an XML file and returns it as a string in UTF-8 encoding.

• OpenDocumentChart is used for pie charts etc. It provides the chart property, which is where you add your elements.
• OpenDocumentDrawing is used for vector-based drawings. It provides the drawing property, which is where you add your elements.
• OpenDocumentImage is used for images. It provides the image property, which is where you add your elements.
• OpenDocumentPresentation provides the presentation property, which is where you add your elements.
• OpenDocumentSpreadsheet provides the spreadsheet property, which is where you add your elements.
• OpenDocumentText provides the text property, which is where you add your elements.

Loading a document

ODFPY can load a document into memory, which you can then change with the API. Example:

from odf.opendocument import load

doc = load("my document.odt")
doc.save("new document.odt")

Manipulating the document

There are also methods for manipulating the document. These are methods of the OpenDocument class:

• getMediaType() Returns the media type
• getStyleByName() Returns a style element from the document with that name, otherwise None. Searches both automatic and common styles.
• createElement(class) Method to create an element. Inconvenient, but follows XML-DOM. Does not allow attributes as arguments, therefore can't check grammar.
• createTextNode(data) Creates a text node given the specified string
• createCDATASection(data) Creates a CDATA section node whose value is the specified string.
• getElementsByType(class) Returns a list of all elements of a given type.

Example:

Print the style reference from all paragraphs.

from odf.opendocument import load
from odf import text

doc = load("my document.odt")

for paragraph in doc.getElementsByType(text.P):
    print paragraph.getAttribute('stylename')

Subobjects

Subobjects are a way to embed documents inside documents. Typically these can be charts, formulas or spreadsheets inside a text, presentation or spreadsheet. The way it works in odfpy, is that you create your objects the normal way by the OpenDocument classes. Then you use the addObject() method to join one to the other. Here is an example:

from odf import opendocument, draw

# Create the subdocument
chart_document = opendocument.OpenDocumentChart()

# Create the main document
main_document = opendocument.OpenDocumentText()

drawn_frame = draw.Frame(width="6in", height="5in", anchortype="paragraph")
main_document.text.addElement(drawn_frame)

# Here we add the subdocument to the main document. 
# We get back a reference to use in the href.
object_location = main_document.addObject(chart_document)
drawn_object = draw.Object(href=object_location)
drawn_frame.addElement(drawn_object)

main_document.save("mydocument.odt")

You can add pictures to both documents. You can even have several levels of subobjects, but OOo makes it impossible to add an object when you edit an embedded subobject, so it is probably not a good idea.

See the subobject.py file in the examples folder for a real example.