Adding elements nonsequentially

[etfre]

It would be nice, especially when using loaded documents, to be able to manipulate a document in some manner beyond appending elements to their parent element. Two possibilities that leap to mind:

1. Add an index kwarg to the various add methods so that they can be used in lieu of insert. Possibly include a delete method as well.
2. Subclass the paragraphs and runs properties of the Document and Paragraph classes, respectively. Overwrite the various list methods to appropriately modify the underlying Etree elements. For instance, d.paragraphs[3] = "Hello world" would replace the 4th paragraph with a new hello world paragraph. This could be powerful and flexible, but it also feels hackish. I'm not really sure.

Thoughts?

[scanny]

I like your suggestion of adding an optional index parameter to the add methods. That seems like a natural extension and initially strikes me as cleaner than adding a separate set of `insert_x()' methods.

Another API approach that seems useful is something like paragraph.insert_paragraph_after() and .insert_paragraph_before(). I've come across situations where you have a paragraph you're essentially using as a cursor position and want to add items on one side or the other, i.e. above or below. I suppose that extends to insert_x_before/after() methods on Run and perhaps in-run objects as well (text, break, picture, etc.) although at the in-run level that does seem like it might proliferate methods in an unsightly way, n^2 where n is the number of in-run object types.

This notion ultimately takes one to a cursor concept, either an empty insertion point or a continuous range of characters, as is provided by the MS API in their Range object. That notion hadn't initially appealed to me, both because it would be a very significant implementation challenge and because it didn't seem terrifically intuitive to learn. Also I suspected it was somewhat forced on that design because the API works on a 'live' document running in an application window and that API mimics what happens when using the mouse or keyboard to select a range of text on which to operate. Now that I get further along in the project I do appreciate some of its virtues though, in particular concentrating this n^2 number of method calls down to n number. Also, it essentially introduces the concept of character and operations at that level, even though that's below the level of a single element in the XML.

I believe your second suggestion works today if you add .text to the left hand side, e.g. paragraphs[3].text = "foobar". I'm not sure I see an advantage to allowing direct string assignments to a paragraph object as a replacement for that. There is more than one reason to assign a string value to a paragraph object, e.g. paragraph = 'Heading 1' and it strikes me it contributes to readability to require the programmer to be explicit about which property they mean,paragraph.style` in this second example.

I suppose at the moment I'd be inclined to favor your first suggestion. It would be a minor extension to the API and seems like it would support the most important use cases if implemented on Paragraph and Run.

[scanny]

Hi Evan, I just had another idea here I wanted to bounce off you.

Basically its having an .insert_paragraph_before() and .insert_paragraph_after() method, but a bit more abstract.

The idea would be actually to introduce a BlockElement class that both Paragraph and Table inherit from. Then BlockElement would have .insert_paragraph_before() (and after) and .insert_table_before() and after. The main concept being that you can use any block-level element as a 'cursor' to specify the relative position for inserting any new block-level element.

Extending the idea to runs, there would be something like RunLevelElement having .insert_run_before() and after, and whatever other run-level elements there are.

I think there would be a pretty elegant implementation for these, because the essential add operations are already there, and it would just be a case of getting the element inserted on the right side of a peer element.

What do you think?

[bslatkin]

I ended up needing to work around this limitation, and here's what I did:

r = CT_R.new()
para._p.insert(1, r)
run = Run(r)
run.style = 'my style'
run.add_text('my text')

Pretty brittle because I needed to insert the run before everything else but after the paragraph's styling item. But it worked! Would be great if this were part of the python-docx API.

[scanny]

@bslatkin can you say a little more about the use case this is a part of? I need a little more context to validate the API ideas I have about this one. Is it that you have an existing paragraph that has some content in it and you need to insert text ahead of it but in the same paragraph?

[bslatkin]

@scanny Exactly.

[scanny]

btw, you can do something like this that might be more robust for the time being:

r_cursor = r_element_to_insert_ahead_of()  # perhaps p.r_lst[0] or paragraph.runs[0]._r
r = CT_R.new()
r_cursor.addprevious(r)
...

[scanny]

Added Paragraph.insert_paragraph_before() as feature #68.

Considering also adding Paragraph.insert_paragraph_after() pending identification of differentiated use case.