feature: add custom properties support

[Apteryks]

Add read/write as well as add/delete functionality regarding custom properties.

[scanny]

Hi Maxim, can you say a little more about what these are and how one might want to use them? I'm guessing they're the properties in the app.xml part but not quite sure :)

[Apteryks]

Hello Steve! The custom properties can be accessed/modified by navigating to the File menu --> Properties --> Advanced properties --> Customization (or something similar - rightmost tab) of any MS Office document. These properties are stored in the /docProps/custom.xml file.

They can be useful for storing extra bits of information easily in a document. For example, when generating documents programmatically, it could be necessary to know if the template used is version X or in language Y. The following is a snippet of the custom properties (I've streamlined the file) in one of the documents I'm working with:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Properties
  xmlns="http://schemas.openxmlformats.org/officeDocument/2006/custom-properties"
  xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">
  <property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="7"
    name="ProjectId">
    <vt:lpwstr>None</vt:lpwstr>
  </property>
  <property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="9"
    name="ClientName">
    <vt:lpwstr>None</vt:lpwstr>
  </property>
  <property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="10"
    name="DocumentVersion">
    <vt:lpwstr>None</vt:lpwstr>
  </property>
  <property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="13"
    name="TemplateLanguage">
    <vt:lpwstr>None</vt:lpwstr>
  </property>
</Properties>

[scanny]

Ah, the app.xml, got it.

I have on my list to adapt the Core Properties implementation from python-pptx over to python-docx but haven't quite got around to it yet:
https://github.com/scanny/python-pptx/blob/master/pptx/parts/coreprops.py

Looks like this one actually has a lower XML element count.

Any idea what those fmtid GUIDs are?

[Apteryks]

The custom properties I'm talking about live in the file custom.xml (I just checked, this is also true for .pptx files). If your document doesn't have any custom property defined, then you will not see this file.

I could find some information regarding the fmtid, which stands for "Format ID", in the ISO-IEC-29500-1.pdf referenced specification, section 22.3, "Custom Properties". It says the fmtid "uniquely relates a custom property with an OLE property", and "The possible values for this attribute are defined by the ST_Guid simple type (§22.9.2.4)."

[scanny]

Got it, thanks Maxim :)

[renejsum]

I have added custom properties to python-docx. Since custom props are named by the user, I am not using the @Property tag, but implementing it as a dictionary

The interface right now is

document = Document('demo.docx')
print "revision is: " % document.custom_properties["Revision"]
document.custom_properties["Name"] = "Rene"
document.custom_properties["Revision"] = "1.0.0"
document.save("demo.docx")

Steve proposed that I had a look at OPC and implement it there, since it is shared across all Office formats. I will have a look at that.

I am working a bit on and off on this, but have a weeks vacation this week :-)

[Apteryks]

Excellent, renejsum! The interface makes sense to me!

[pa2wlt]

In the reply above @renejsum wrote he added custom_properties to python.docx. Though I can't find it in the code or a corresponding commit. Perhaps @scanny or @Apteryks have any suggestion where to look?

[scanny]

I would look for it in a fork on @renejsum's GitHub page.

[pa2wlt]

Thx @scanny. I did so indeed. Though @renejsum has only one fork, python-opc that has only one contributor... @scanny. The latest commit in is date Oct 2013, and the post of @renejsum above was two years later. Perhaps I looked at the wrong place?

[scanny]

Hmm, sounds like @renejsum hasn't published yet.

What's your use-case/situation?

[renejsum]

Sorry guys, have been a little distracted by other things lately

I have uploaded my version of python-docx to https://github.com/renejsum/python-docx, it was not created as a fork, but I just cloned @scanny 's repo. I am not a git expert, not sure if that will have any implications?

You are welcome to look at my changes and use them however you see fit...

@scanny proposed to implement the customprops in python-opc, but I have not done that due to lack of talent and time :-)

[pa2wlt]

Thx @renejsum and @scanny. Will pick this up later and see if I can get it to work.
Use-case/situation: I once created some VBA forms and macro's in Word, that basically do nothing more than provide a somehow user friendly interface for the Custom Document Properties. Though VBA has only been implemented very limited in Office 2016 for Mac. And Microsoft launched the opportunity to create Office add-ins, using html/javascript. I created one with some fields and buttons, and this works fine. However, ... there seems to be no option to read / write the Custom Document Properties. Now I thought that I might give it a try with Python, though I'm not a Python expert.

[renejsum]

Example of usage of my changes can be found at https://gist.github.com/renejsum/0ea621aabd0e4640391ddb3e361f6c02