Feat: Add Alt text properties and setters

[pa-t]

Adds ability to read and set alt text. Wanted to be able to leverage this library to add in alt text for screen readers for the visually impaired

Property methods taken from @cray2015 pr: https://github.com/scanny/python-pptx/pull/512

[pa-t]

@scanny I tried the snippet you added in the comments of the #512 PR:

alt_text = shape._element._nvXxPr.cNvPr.attrib.get("desc", "")

And it did not work for me, while this implementation did:

>>> from pptx import Presentation
>>> pr = Presentation("/Users/pat/Downloads/Test Slide Deck.pptx")
>>> pr.slides[2].shapes[1]._element._nvXxPr.cNvPr.attrib.get("desc", "")
''
>>> pr.slides[2].shapes[1].alt_text
'This is better alt text'

[scanny]

Yes, quite right, I left off the "r" on descr, I'll get that fixed up :)

[pa-t]

Ah ok, i see that working now. Is there any reason behind not wanting to have this be officially supported? I think it would be a nice addition. Are there some edge cases you are worried about?

[scanny]

It would be great for it to be added to the package, it's just not likely for that to happen this week and I'm not sure when we'll get to it. New features need documentation, tests, and a version deployment to ride along with. Just "working" is not even close to complete enough. So there's more effort here than may be immediately apparent. A local function works today and is vendored in your own code-base so you don't need to wait for someone else to add it or fix or otherwise adjust it later.

[pa-t]

Thats fine, I just wasn't sure what you needed for ACs. I just pushed a test for the getting and setting of the alt text field. Not sure where best to add documentation but if you point i will write it. Thanks @scanny

[scanny]

@pa-t This looks pretty good and I think I'm going to be in here soon adding some other things so I can probably bundle it in; I've made it a shortlist item.

On the docs, the key thing is the analysis document, which you can think of as a PPEP (python-pptx enhancement proposal). Here one of the ones we have so far: https://python-pptx.readthedocs.io/en/latest/dev/analysis/shp-shapes.html.

In this particular case, I think you would just be adding some things to this existing page since this is really a small extension to available shape properties. But the key things are:

• the general proposal
• the behavior of this "thing" as exhibited by PowerPoint, like in this case how does that field get filled in, how often would it contain useful information, does it get a default set by PowerPoint when you add a shape or edit its text or something.
• what are the aspects of the XML schema we need to understand to do the right thing by way of adding oxml elements and attributes that behave consistent with the spec.
• What is the MS Office API for this thing. This is more important than you might think because it often gives hints that the behavior is not as simple as we initially thought. Also we derive the name from it usually so it's in a familiar place to someone coming from or going to one of the MS libraries.
• Where should it live in the object hierarchy. Is it applicable to all shapes or only some?
• A spec of the behavior of the proposed API element, importantly including its type signature. Is it an optional value? Does it have a default value? Etc.

All that gives us enough to determine whether we've got the design right. So generally this would be the first commit and we can discuss and refine it before investing in an implementation. This analysis is separately mergeable once resolved. You're welcome to make an initial implemention just for exploratory purposes, in this case that's a great idea. It's just that we might change our mind about aspects of the design or behavior so you wouldn't want to put in more work than you'd be willing to do over if the approach changes, as it often does.

The user documentation is derived from the docstrings, so that comes later and is usually pretty automatic.

[scanny]

Say @pa-t, on the documentation bit, not sure we'd need a lot, but can you help me understand when alt-text is used and what it's for? A couple questions:

• Where/when is alt-text present? Like which shapes in particular.
• Does it get added automatically by PowerPoint or do you have to take a UI action to add it?
• If there's an autoshape, like a rectangle, and it has text in it, would the text be used as alt-text or does it even need alt text?

And anything else you can think of. I'm trying to place it in a user context to understand how the feature would be used, when it would be relevant, etc.

[pa-t]

hey @scanny

• I'd say alt-text is mainly present for images, but it could be used for charts and diagrams too. Nothing is stopping users from adding alt-text to actual text boxes
• You have to take action to add it, I can't speak on specifically PowerPoint, but in google slides you right click on the shape and then can select alt-text. This field is also available under format options
• In this case where there is a shape with text, it does not need alt-text. However, a user could set the alt-text so that a screen reader has an easier time conveying the information

I think the best way to frame this feature is through the lens of enabling more accessibility support. Screen readers are the main use case, only other use i can think of is in the case of remote resources not loading and defaulting to alt-text

Do you want me to write the docs for this?

[scanny]

I'd be thinking we want to resolve to a short blurb that goes in the docstring and leave it at that. Probably no more than 50 words and maybe less, but as long as it needs to be to set folks' expectations. I think starting big and then whittling down to a concise summary (like we're doing) is the right approach.

The thing I don't see yet is the default behavior. Does this get anything by default? Otherwise I'm thinking it going to be empty 99.99% of the time. If PowerPoint automatically provides default values when (at least certain) shapes are created, what are those? Like is it the filename of the image in the case of a Picture for example? Or would the user expect these to be blank unless they happened to know the author had explicitly set them?

[scanny]

Also, what is this attribute called in the MS API? A search on "powerpoint vba get alt text" is a good place to start.

[pa-t]

No nothing is set by default, it is just left empty. The user has to set this value. Found this doc page where it is just called AlternativeText

[pa-t]

@scanny how does something like this read:

The alt_text property allows for enhanced accessibility support in presentations by enabling the addition of alternative text to shapes. This feature primarily benefits screen readers, providing a description when the shape cannot be visually interpreted. By default, this property is empty and must be manually set by the user.