Skip to content

docs: fix stale table.direction example to table_direction in WD_TABLE_DIRECTION#1567

Open
MohammadaliMasjedi-source wants to merge 1 commit into
python-openxml:masterfrom
MohammadaliMasjedi-source:docs/fix-table-direction-example
Open

docs: fix stale table.direction example to table_direction in WD_TABLE_DIRECTION#1567
MohammadaliMasjedi-source wants to merge 1 commit into
python-openxml:masterfrom
MohammadaliMasjedi-source:docs/fix-table-direction-example

Conversation

@MohammadaliMasjedi-source

Copy link
Copy Markdown

What's wrong

The documented example for WD_TABLE_DIRECTION shows:

from docx.enum.table import WD_TABLE_DIRECTION

table = document.add_table(3, 3)
table.direction = WD_TABLE_DIRECTION.RTL

But the Table object exposes the property as table_direction, not direction. Because
Table has no __slots__, table.direction = WD_TABLE_DIRECTION.RTL does not raise — it
just 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 that
RTL was never applied, which is arguably worse than an error.

The stale example appears in two places:

  1. src/docx/enum/table.py — docstring of class WD_TABLE_DIRECTION
  2. docs/api/enum/WdTableDirection.rst — the rendered API-reference page

What this PR changes

Replace table.direction with table.table_direction in both spots, so the documented example
actually 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.RTL writes <w:bidiVisual/> into w:tblPr. The
mechanism existed; the docs example was just mis-named.

How I verified it

Ran a small script against python-docx==1.2.0 (current latest, matching master):

  1. table.direction = ... does not raise, but also does not write <w:bidiVisual> (silent no-op);
  2. table.table_direction = WD_TABLE_DIRECTION.RTL sets and round-trips correctly;
  3. only the table_direction assignment makes the saved document's w:tblPr contain <w:bidiVisual>.

All checks passed.


I put this together with some AI assistance for the drafting, and verified the behavior against
master myself with a small script before opening the PR. Happy to adjust to your preferences.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant