1.. _documents: 2 3Working with Documents 4========================== 5 6|docx| allows you to create new documents as well as make changes to existing 7ones. Actually, it only lets you make changes to existing documents; it's just 8that if you start with a document that doesn't have any content, it might feel 9at first like you're creating one from scratch. 10 11This characteristic is a powerful one. A lot of how a document looks is 12determined by the parts that are left when you delete all the content. Things 13like styles and page headers and footers are contained separately from the main 14content, allowing you to place a good deal of customization in your starting 15document that then appears in the document you produce. 16 17Let's walk through the steps to create a document one example at a time, 18starting with two of the main things you can do with a document, open it and 19save it. 20 21 22Opening a document 23------------------ 24 25The simplest way to get started is to open a new document without specifying 26a file to open:: 27 28 from docx import Document 29 30 document = Document() 31 document.save('test.docx') 32 33This creates a new document from the built-in default template and saves it 34unchanged to a file named 'test.docx'. The so-called "default template" is 35actually just a Word file having no content, stored with the installed |docx| 36package. It's roughly the same as you get by picking the *Word Document* 37template after selecting Word's **File > New from Template...** menu item. 38 39 40REALLY opening a document 41------------------------- 42 43If you want more control over the final document, or if you want to change an 44existing document, you need to open one with a filename:: 45 46 document = Document('existing-document-file.docx') 47 document.save('new-file-name.docx') 48 49Things to note: 50 51* You can open any Word 2007 or later file this way (.doc files from Word 2003 52 and earlier won't work). While you might not be able to manipulate all the 53 contents yet, whatever is already in there will load and save just fine. The 54 feature set is still being built out, so you can't add or change things like 55 headers or footnotes yet, but if the document has them |docx| is polite 56 enough to leave them alone and smart enough to save them without actually 57 understanding what they are. 58 59* If you use the same filename to open and save the file, |docx| will obediently 60 overwrite the original file without a peep. You'll want to make sure that's 61 what you intend. 62 63 64Opening a 'file-like' document 65------------------------------ 66 67|docx| can open a document from a so-called *file-like* object. It can also 68save to a file-like object. This can be handy when you want to get the source 69or target document over a network connection or from a database and don't want 70to (or aren't allowed to) interact with the file system. In practice this means 71you can pass an open file or StringIO/BytesIO stream object to open or save 72a document like so:: 73 74 f = open('foobar.docx', 'rb') 75 document = Document(f) 76 f.close() 77 78 # or 79 80 with open('foobar.docx', 'rb') as f: 81 source_stream = StringIO(f.read()) 82 document = Document(source_stream) 83 source_stream.close() 84 ... 85 target_stream = StringIO() 86 document.save(target_stream) 87 88The ``'rb'`` file open mode parameter isn't required on all operating 89systems. It defaults to ``'r'`` which is enough sometimes, but the 'b' 90(selecting binary mode) is required on Windows and at least some versions of 91Linux to allow Zipfile to open the file. 92 93Okay, so you've got a document open and are pretty sure you can save it 94somewhere later. Next step is to get some content in there ... 95