Skip to content

fix: accept raw-string (r""") docstring openers in both parsers - #251

Merged
Jammy2211 merged 1 commit into
mainfrom
claude/latex-raw-string-docstrings-9h4ine
Aug 20, 2026
Merged

fix: accept raw-string (r""") docstring openers in both parsers#251
Jammy2211 merged 1 commit into
mainfrom
claude/latex-raw-string-docstrings-9h4ine

Conversation

@Jammy2211

Copy link
Copy Markdown
Collaborator

Closes #250.

Two independent PyAutoHands docstring parsers silently mis-handled an r""" opener. Neither raised, and there are currently zero raw narrative docstrings in any workspace, which is why this never fired.

This blocks the 41-file workspace raw-stringing task (PyAutoMind draft/maintenance/workspaces/latex_raw_string_docstrings.md): those tutorial docstrings carry LaTeX and must be raw — unprefixed, \theta is a TAB followed by heta — and raw is exactly what these two parsers rejected.

The two defects

add_notebook_quotes._narrative_docstring_ranges tested lines[start].startswith('"""'). A raw block is a perfectly good column-0 ast.Expr(Constant(str)), so it reached that test and failed it — the block was dropped as a cell boundary and the tutorial prose shipped as a Python code cell containing a bare string literal.

env_config._DOCSTRING_DELIM_RE matched a bare delimiter only. An r""" opener was walked past and the block's closer matched as an opener instead, inverting docstring parity for the rest of the file: an __Env__ section further down was read as if it sat outside a docstring and read_env_declaration returned None, silently losing the ENV: declaration and rerouting the script's smoke profile. Seven autolens_workspace scripts carry __Env__ sections.

Reproduced against main @ cdea28c on a probe pair differing only by an r:

before after
_narrative_docstring_ranges [(6,10)] — raw block dropped [(0,2), (6,10)]
read_env_declaration None ['jax']

The change

Both sites accept an optional r/R prefix on either delimiter. The notebook converter replaces the opener line outright when it emits the cell, so the prefix never reaches the generated artefact and output is byte-identical — which is what makes the downstream task's diff-empty gate meaningful.

Six regression tests, each verified to fail with the source change reverted:

  • test_add_notebook_quotes — raw block converts byte-identically to the same block unprefixed; all six prefix/delimiter forms produce identical output.
  • test_env_config — the parity case (declaration survives an earlier raw docstring, which a single-block test would miss); declaration inside the raw block itself; all six forms parse.
  • test_strip_env_declarations — an __Env__ section in a raw block strips as a plain one does.

Verification

  • Full suite 14 failed / 337 passed on this branch vs 14 failed / 331 passed on mainidentical failure sets. All 14 are ipynb-py-convert failing to build in the dev container; CI installs it, so they run green here.
  • Boundary set confirmed not to have widened: column-0 raw single-quoted strings, assigned literals, raw bytes literals and f-strings all remain non-boundaries.
  • generate_markdown.script_title verified unaffected (its regex finds the """ after the r, same title either way); navigator reads already-converted output.

Notes for the reviewer

  • The notebook-level assertion the issue sketched is made on the converted source instead: the converter replaces the opener line outright, so byte-identical conversion is the tighter claim, and it does not depend on ipynb-py-convert.
  • No reformatting: this repo is not black-formatted (44 files on main would change), so the new code matches surrounding style rather than a formatter.
  • Independent of feature/hands-hygiene-leftovers — that branch touches AGENTS.md, generate_release_notes.py, bin/autohands and two unrelated tests, so there is zero file overlap and the two can merge in either order.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MTjtx5mdituitiyQYFGn2E


Generated by Claude Code

Two independent PyAutoHands docstring parsers silently mis-handled an r"""
opener. Neither raised, and there are currently zero raw narrative docstrings
in any workspace, which is why this never fired.

add_notebook_quotes._narrative_docstring_ranges tested
lines[start].startswith('"""'). A raw block is a perfectly good column-0
ast.Expr(Constant(str)), so it reached that test and failed it — the block was
dropped as a cell boundary and the tutorial prose shipped as a Python CODE
cell containing a bare string literal.

env_config._DOCSTRING_DELIM_RE matched a bare delimiter only. An r""" opener
was walked past and the block's CLOSER matched as an opener instead, inverting
docstring parity for the rest of the file: an __Env__ section further down was
read as if it sat outside a docstring and read_env_declaration returned None,
silently losing the ENV: declaration and rerouting the script's smoke profile.

Both sites now accept an optional r/R prefix on either delimiter. The notebook
converter replaces the opener line outright when it emits the cell, so the
prefix never reaches the generated artefact and output is byte-identical.

Six regression tests, each verified to fail without the source change:

  test_add_notebook_quotes
    - raw block converts byte-identically to the same block unprefixed
    - all six prefix/delimiter forms produce identical output
  test_env_config
    - the PARITY case: declaration survives an EARLIER raw docstring (this is
      what a single-block test would miss)
    - declaration inside the raw block itself
    - all six prefix/delimiter forms parse
  test_strip_env_declarations
    - an __Env__ section in a raw block strips as a plain one does

Checked and confirmed unaffected: generate_markdown.script_title (its regex
finds the """ after the r) and navigator (reads already-converted output).
Verified the boundary set did not widen — column-0 raw single-quoted strings,
assigned literals, raw bytes literals and f-strings all remain non-boundaries.

Unblocks the 41-file workspace raw-stringing task (PyAutoMind
draft/maintenance/workspaces/latex_raw_string_docstrings.md).
@Jammy2211
Jammy2211 merged commit c887290 into main Aug 20, 2026
3 checks passed
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.

fix: notebook + env parsers silently mis-handle raw-string (r""") docstrings

2 participants