docs: fix stale table.direction example to table_direction in WD_TABLE_DIRECTION#1567
Open
MohammadaliMasjedi-source wants to merge 1 commit into
Conversation
The WD_TABLE_DIRECTION example showed `table.direction = WD_TABLE_DIRECTION.RTL`, but the actual property is `Table.table_direction`. Plain `table.direction = ...` is a silent no-op: it sets an ordinary attribute, raises nothing, and never writes `<w:bidiVisual>`, so users believe RTL was applied when it wasn't. Fixes the example in both the enum docstring and the hand-maintained .rst reference. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's wrong
The documented example for
WD_TABLE_DIRECTIONshows:But the
Tableobject exposes the property astable_direction, notdirection. BecauseTablehas no__slots__,table.direction = WD_TABLE_DIRECTION.RTLdoes not raise — itjust creates a throwaway instance attribute that nothing ever reads and that never writes
<w:bidiVisual>. So the documented example is a silent no-op: the user gets no signal thatRTL was never applied, which is arguably worse than an error.
The stale example appears in two places:
src/docx/enum/table.py— docstring ofclass WD_TABLE_DIRECTIONdocs/api/enum/WdTableDirection.rst— the rendered API-reference pageWhat this PR changes
Replace
table.directionwithtable.table_directionin both spots, so the documented exampleactually applies right-to-left cell ordering. Docs only — no code/behavior change.
This also clears up the confusion behind #1502: RTL cell ordering is supported —
table.table_direction = WD_TABLE_DIRECTION.RTLwrites<w:bidiVisual/>intow:tblPr. Themechanism existed; the docs example was just mis-named.
How I verified it
Ran a small script against
python-docx==1.2.0(current latest, matchingmaster):table.direction = ...does not raise, but also does not write<w:bidiVisual>(silent no-op);table.table_direction = WD_TABLE_DIRECTION.RTLsets and round-trips correctly;table_directionassignment makes the saved document'sw:tblPrcontain<w:bidiVisual>.All checks passed.
I put this together with some AI assistance for the drafting, and verified the behavior against
mastermyself with a small script before opening the PR. Happy to adjust to your preferences.