While adding alt-text, I ran into an API/compatibility issue.

I’d like to let users set alt text at insertion time via:

• Document.add_picture(...)
• Run.add_picture(...)

These are public APIs. Internally they call:

• StoryPart.new_pic_inline(...)
• CT_Inline.new_pic_inline(...)

However, the existing API and tests assume a 3-arg positional call chain:

document.add_picture(path, width, height)
run.add_picture(path, width, height)
part.new_pic_inline(image, width, height)

If we extend this with positional title / descr, we either:

• break those expectations and risk user code,
• or start passing extra None arguments around, which is brittle and obscures intent.

I think there are three options:

1. Keep add_picture as-is; only add:

   • InlineShape.alt_text
   • InlineShape.alt_title
     Users set alt text after insertion:

   shape = doc.add_picture("img.png")
   shape.alt_text = "..."

2. Extend via keyword-only args (backwards compatible):

   • add_picture(..., *, title=None, descr=None)
   • Plumb these through internally as keyword args only.

3. Internal-only clean break (future-proof core, public stays stable)

   • Keep public APIs as-is (users can optionally pass title/descr as kwargs).
   • Make internal constructors keyword-only and clearer:
     • StoryPart.new_inline_picture(..., *, width=None, height=None, title=None, descr=None)
       (optionally keep new_pic_inline(...) as a shim that calls new_inline_picture(...) and deprecate it)
     • CT_Inline.new_pic_inline(..., *, title=None, descr=None) and CT_Inline.new(..., *, title=None, descr=None)
   • Run.add_picture(...) forwards only provided kwargs to new_inline_picture(...).
   • This gives us a clean, extensible internal surface (ready for future options like wrapping/hyperlink) without changing public behavior. Guidance requested on whether to include the shim + deprecation, or go straight to the new names.

@scanny Which option would you prefer?