feature: document lxml element of proxy classes for advanced users

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.

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

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'

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.

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

@progamniac

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

Merge pull request #7 from BayooG/feature/add_comments_on_run_level

fix-autotest-and-bug (python-openxml#7)

Navigation Menu

Repository navigation

feature: document lxml element of proxy classes for advanced users #7

Update

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feature: document lxml element of proxy classes for advanced users #7

Description

Activity

notionparallax commented on Mar 19, 2014

Update

scanny commented on Mar 19, 2014

danmilon commented on Apr 25, 2014

onlyjus commented on Apr 27, 2014

scanny commented on Aug 12, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions