maintenance: raw-string the LaTeX-carrying docstrings across the six workspace repos

[Jammy2211]

From PyAutoMind draft/maintenance/workspaces/latex_raw_string_docstrings.md. One issue, six independent prose-only PRs (one per repo) — no API surface, so no cross-repo merge ordering.

Unblocked by PyAutoHands #250 / PR #251 (merged c887290), which taught the notebook and env parsers to accept an r""" opener. Before that, raw-stringing these files would have shipped tutorial prose as code cells and silently dropped __Env__ declarations.

Two failure classes, only one of them visible

	what it is	diagnostic
warned	\s, \l, \[ — escapes Python does not recognise	SyntaxWarning per compile; slated to become SyntaxError
silent	\t in \theta, \f in \frac, \r in \rm, \b in \beta	none at all — the value is just corrupted

\theta_E in HowToLens chapter_4/tutorial_3_scaling_relation.py was literally TAB + "heta_E". A warning-only sweep misses this entire class — chapter_4/tutorial_5_cluster_scale.py has only silent hits and zero warnings.

The warning sweep is interpreter-dependent. Invalid escapes are a SyntaxWarning only on Python 3.12+; on 3.11 they are a DeprecationWarning, so a SyntaxWarning-only sweep returns a vacuous zero and looks exactly like "already fixed". Verified on 3.11.15. Both categories were collected.

Result — 41 files, 180 literals, 131 corruptions repaired

repo	files	literals	corruptions repaired
HowToFit	4	13	7
HowToGalaxy	4	20	13
HowToLens	8	32	21
autofit_workspace	2	2	1
autogalaxy_workspace	6	30	28
autolens_workspace	17	83	61

Both sweeps return zero in all six repos (one documented residue, below).

Verification

Per repo, in order:

1. Baseline regeneration is a no-op — run the generator before editing and confirm zero dirty files, so generator noise cannot fake the gate.
2. Both sweeps zero after the change.
3. Runtime value check — every changed literal's value compared HEAD vs worktree. The r prefix may only ever remove corruption; a value that gains a character or changes any other way fails. 131 repaired, 0 unexpected.
4. Diff-empty gate — regenerate, then git diff notebooks/ markdown/ llms-full.txt workspace_index.json must be empty. Passes byte-exactly in all six.
5. autolens_workspace only — all 57 __Env__ declarations re-read identically via read_env_declaration. Four of the raw-stringed files carry __Env__, so this exercises the PyAutoHands fix end to end.

One refinement to the gate as written

HowToFit's four plt.ylabel("Normalized Residuals ($\sigma$)") labels are runtime strings in code cells, not docstrings. Code cells copy source verbatim, so the r legitimately appears in the notebook there. The gate holds exactly as stated for every docstring; that one repo shows a code-cell delta by design. Prose cells are unchanged everywhere.

Left deliberately alone

• autolens_workspace/scripts/group/likelihood_function.py — keeps 2 warnings + 1 silent hit. Three docstrings use the double-backslash convention ($\\theta$, \\frac, \\vec) mixed with a few single-backslash macros. Adding r would double the already-correct escapes and change the rendered LaTeX; fixing it means un-doubling 18 backslashes, a prose edit this task excludes. Worth a follow-up to settle the convention. Unambiguous literals in that file were still fixed (4 warned → 2, 3 silent → 1).
• Already-escaped \\ anywhere ($\\chi^2$ in two autogalaxy interferometer files, " \\[-2pt]" in autofit samples.py). In a non-raw literal that is already one literal backslash — correct. These warn about nothing and corrupt nothing.
• Deliberate escapes — real newlines in print("\nInfo:") and friends.
• autolens_workspace/dataset/cluster/a2744/prep.py:38 — line.split("\t") is a genuine TSV tab.

Method

The r prefix was applied only where every backslash in the literal sits in a LaTeX context ($…$, \(…\), \[…\], \begin{}…\end{}, or a markdown code span), with an absolute veto on \\, escaped quotes and numeric escapes regardless of context. Anything else was reported for a human to read and decided individually. Prose is untouched — only the delimiter gains an r.

Still to file

A -W error::SyntaxWarning compile guard in workspace CI so this cannot regress — noting it would catch only the warned class; the silent class needs the AST sweep.

[Jammy2211]

Shipped — all six PRs merged.

repo	PR	files	literals	repaired
HowToFit	PyAutoLabs/HowToFit#47	4	13	7
HowToGalaxy	PyAutoLabs/HowToGalaxy#70	4	20	13
HowToLens	PyAutoLabs/HowToLens#73	8	32	21
autofit_workspace	PyAutoLabs/autofit_workspace#145	2	2	1
autogalaxy_workspace	PyAutoLabs/autogalaxy_workspace#218	6	30	28
autolens_workspace	#492	17	83	61

41 files, 180 literals, 131 silent corruptions repaired. Both sweeps zero everywhere except the one documented residue.

Two things worth carrying forward

The diff-empty gate in the plan cannot catch a wrong edit here. It is necessary but structurally blind: the generator reads source text, not runtime values, so a corrupted value regenerates byte-identically. The check that actually catches mistakes is comparing every changed literal's runtime value HEAD vs worktree and asserting the r prefix only ever removes corruption. It caught two real errors mid-task — a print("\nInfo:") newline about to be destroyed, and 12 already-escaped $\\chi^2$ about to be doubled into LaTeX line breaks. Final tally: 131 repaired, 0 unexpected.

\\ is always deliberate, whatever the surrounding context. In a non-raw literal it already means one literal backslash, so the author got it right and r would double it. A math-context rule alone lets these through, because they sit inside $…$.

HowToLens#73 was merged with smoke red — and the red is not this work's

Two chapter_3 pixelization scripts fail numba Pass nopython_type_inference; neither is in the diff, and all 8 files that are in it pass. Decisive control: re-running the last green main build (run 255, commit dcb67e9, zero changes from the branch, fresh dependency install) now fails identically — HowToLens main is red on its own.

Suspected cause, not proven: PyAutoLabs/PyAutoArray#453 (in-place Cholesky buffer + new numba kernels for fnnls_cholesky) merged minutes before. Two candidate mechanisms were tested under the exact CI versions (numba 0.67.0 + scipy 1.17.1) and both passed. Open for whoever owns that solver.

Follow-up: shipped, not filed

PyAutoLabs/PyAutoBrain#245 adds a hygiene escapes mode, so this debt is caught continuously. Preferred over the -W error::SyntaxWarning CI guard this issue proposed — that would catch only the warned class, and would pass vacuously on Python 3.11, where invalid escapes are a DeprecationWarning.

Record: PyAutoMind complete/2026/08/latex-raw-string-docstrings.md.

---

Generated by Claude Code