I’m interested in exploring a standardized approach to making Python codebases more accessible to developers who are visually impaired or neurodivergent.
While Python’s syntax is famous for being “executable pseudocode,” the reliance on visual indentation can pose unique challenges for screen-reader users. I am proposing a discussion around an informational PEP to establish “Accessibility Hints.”
Key ideas include:
Accessibility Docstrings: Standardizing a :hint: field for plain-English summaries of complex logic.
Linter Support: Tools that warn when nesting depth becomes an accessibility barrier.
Doc-standardization: Requiring alt-text for diagrams in official Python documentation.
Example Concept:
Python
def process_data_pipeline(data):
"""
:accessibility-hint: This function uses a three-stage nested loop.
Skip to line 45 for the final return statement.
"""
I’m looking for general feedback on whether the community feels this belongs in a formal PEP or as a third-party project.
The three ideas will likely have separate solutions. PEPs are about revising the Python language and the CPython distribution. Linters are 3rd party projects so you have to talk to 1 or more of them separately.
Python has a few .png (and possible other) images. My understanding is that alt text is added as an attribute to html img tags, such as in <img src="dog.jpg" alt="A golden retriever playing fetch in a park">. Our docs are written in .rst format (Documentation) and converted to .html (among other possibilities) with Sphinx. Read more in the devguide. I did not immediately see anything about images, but if .rst allows for image text, I should hope that Sphinx would produce the proper img tag. If our few illustrations do not have alt text now, I would expect such to be accepted if the pipeline will handle it.
I am a bit dubious that adding special purpose hints to docstrings throughout the code base would be accepted. I would think about 3rd party possibilities for this.
Thank you for the detailed feedback! This is very helpful for narrowing the scope.
Regarding Documentation: I will definitely look into the Devguide and Sphinx capabilities for .rst. If the pipeline already supports alt-text but it’s simply not being used in our .png illustrations, then a documentation-focused PEP (or even a direct contribution) to mandate alt-text for all future PEPs and core docs seems like a clear path forward.
Regarding Accessibility Hints in Docstrings: I understand the skepticism about ‘special purpose’ tags. However, my concern with keeping this purely 3rd-party is fragmentation. If we don’t have a standard field (like :accessibility:), then one library might use :hint:, another uses :alt:, and screen-reader developers won’t know which one to support.
Even if it starts as a 3rd-party convention, would there be interest in an Informational PEP that simply recommends a specific format? This would give 3rd-party tool authors a single ‘source of truth’ to build toward.
I’ll take your advice and research the current .rst image handling. Does anyone here have experience with Sphinx’s .. image:: or .. figure:: directives regarding alt attributes?
Thank you, Sir! It’s great to see that .rst already has the infrastructure for this.
It’s surprising that nearly 40% of the images in the core docs are still missing :alt: tags. I would be very happy to take this on. I’ll review the ‘alt decision tree’ you linked and start preparing PRs for the macOS and Windows ‘Using Python’ sections.
Regarding the ‘Accessibility Hints’ for code: While I work on the documentation PRs, I’d still like to keep the conversation open about code-level accessibility. Perhaps once we’ve standardized the documentation, we can revisit how to provide similar ‘navigational’ clarity for screen-reader users directly within complex code blocks.
I’ll head over to the Devguide now to make sure I follow the correct process for these documentation PRs.
I don’t understand the difference between what would go in a :hint: docstring and what would go in a comment? Both are an explanation of the surrounding code.
That’s a great question, Sir. From a purely visual perspective, they are very similar, but for a screen-reader user, the difference is semantic intent.
Comments are often granular and scattered. A screen reader has to read them line-by-line along with the code. If a function is 50 lines long, a blind developer has to listen to all of it to build a mental map.
The :hint: tag acts like ‘Alt-Text for Logic.’ Because it is a standardized field, we can program IDEs and screen readers to:
Announce the hint first when a user navigates to a function.
Allow the user to ‘skip’ the boilerplate code if the hint tells them the logic they are looking for is further down.
Think of it like an <h1> tag in HTML versus just making text bold. Both look big, but the <h1> tells the browser (and the screen reader) that ‘This is a major heading.’ The :hint: tells the tool ‘This is the summary you should read to the user before they dive into the syntax.’
Thanks for the reminder on the guidelines. To be honest, I am a 12th-grade student and a ‘learning-by-doing’ developer. Since English is not my first language, I used an LLM to help me polish my grammar and structure my proposal so I wouldn’t sound unprofessional to the core team.Moreover, before i reply to any post, comment, reply etc, I first copy it on Notepad, type a response, check it whether it is accurate, and then post it. Basics of Python were taught us in Grade-11th, from there my interest developed in this language as it is easy, as compared to C#, C++,etc.
However, the idea comes from my own interest in making code more accessible. I’m not just a ‘bot’—I’m a practical student who wants to help. I am already looking at the Windows documentation files on GitHub to add those alt-text tags you mentioned.
I’ll make sure my future posts are more ‘raw’ and reflect my own voice as I learn the process. Thanks for the guidance!
None of the fields we currently use in docstrings are currently standardized, so there’s little hope here.
In any case, tooling can always be made configurable to select which field/section should be used by screen readers. Some docstring parsing tools can already parse arbitrarily-named sections. For example with Griffe (I’m the author):
>>> import griffe
>>> sections = griffe.Docstring("""
... Summary.
...
... Accessibility Hint:
... This function uses a three-stage...
... """).parse("google")
>>> hint = next(
... s for s in sections
... if s.kind is griffe.DocstringSectionKind.admonition
... and s.value.kind == "accessibility-hint"
... )
>>> hint.value.contents
'This function uses a three-stage...'
