feature: document lxml element of proxy classes for advanced users

[scanny]

Proxy classes such as Document, Paragraph, and Table each hold a private reference to the lxml element they correspond to, <w:document>, <w:p>, and <w:tbl> respectively. With these elements, advanced users can call the underlying lxml API directly to develop customized solutions the existing API does not yet support.

Add documentation so advanced users can readily access these elements without consulting the source code.

[notionparallax]

Hi, is there anything I can do to help this along?
I need to get to the formatting on a run, and this seems like the only way to do it. (I'm processing existing documents)

<w:r>
  <w:rPr>
    <w:rFonts w:ascii="HelveticaNeueLT Com 45 Lt" w:cs="Times New Roman" w:eastAsia="Calibri" w:hAnsi="HelveticaNeueLT Com 45 Lt"/>
    <w:sz w:val="20"/>
    <w:szCs w:val="20"/>
    <w:shd w:fill="00FF00" w:val="clear"/>  <=== THE BIT I WANT
  </w:rPr>
  <w:t>Public Building/Cultural</w:t>
</w:r>

Handling just this bit to pull out the shading is fine, but parsing the whole doc seems way too much like hard work!

Update

I got around this in a bit of a hacky way with this:

def isShaded(aRun):
    return "<w:shd" in aRun._r.xml

[scanny]

You can access this element with the lxml API using something like this:

>>> from docx.oxml.shared import qn
>>> assert isinstance(Run, run)
>>> rPr = run._r.rPr
>>> shd = rPr.find(qn('w:shd'))  # returns the shd child element or None if not present
>>> shd.get(qn('w:fill'))
'00FF00'
>>> shd.get(qn('w:val'))
'clear'

[danmilon]

I'm making use of the underlying lxml API too because I need to store the XPath of some runs. I'd feel more confident if it was documented and I was assured the property name wont change in the future.

[onlyjus]

I added the shading element in my merge request. Have it functioning for table cells. Should be easily added to runs.

[scanny]

@progamniac please ask support questions on StackOverflow using the python-docx tag.