[Jinyong-Li]

Summary

The comment-writing APIs currently accept control characters that TOML forbids. For example, copying ANSI-colored log text into a comment emits ESC into the document; both tomlkit.parse() and Python's tomllib.loads() then reject the saved output:

import tomlkit

doc = tomlkit.document()
doc.add(tomlkit.comment("copied \x1b[31mlog text"))
tomlkit.parse(doc.as_string())  # InvalidControlChar

Validate comment characters before changing an item or array. comment(), Item.comment(), and Array.add_line(comment=...) now raise ValueError for forbidden controls. Tabs and Unicode text remain valid, and standalone multiline comments retain LF/CRLF endings. Bare carriage returns in the input are rejected. This follows the TOML comment rules.

The tests cover every forbidden ASCII control other than the separately handled line endings, all three public entry points, preservation of existing data after rejection, and valid Unicode/line-ending controls. On unmodified master, 93 of the new cases fail and 3 pass.

Validation on Windows / CPython 3.13.5:

• python -m pytest -q tests: 1,421 passed, including the initialized toml-test corpus.
• Pinned pre-commit hooks on all four changed files: passed.
• git diff --check: passed.
• mypy tomlkit tests/test_api.py with mypy 1.19.1 reports the same 7 existing errors on this patch and an unchanged checkout of 55d0768; no new diagnostics.

Duplicate Check

• I searched the open PRs and found none that already fixes this issue.
• Searched open and closed issues/PRs for comment controls, invalid comments, NUL, bare carriage returns, and validate_comment, and inspected the open PR list. Prefix every line of a multiline comment with # #511 adds multiline comment rendering; this patch validates the characters passed to the comment-writing APIs.

Agent Drafting Metadata

• Agent: OpenAI Codex
• Model: GPT-6
• Notes: AI assistance was used for investigation, implementation, tests, and this description under the account owner's authorization. All reported local checks were executed.

[human-attestation]

✅ Human Attestation: @Jinyong-Li attested this PR at commit 769982d (2026-11-06T21:22:48.884Z).

I have read and understood all agent-written code in this PR. / 我已阅读并理解此 PR 中 Agent 编写的全部代码。

Later pushes to this PR stay attested. Attestation page

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[frostming]

Why not move these two lines into the validation function as well?

[Jinyong-Li]

Thanks for the suggestion! I‘ve moved those checks into validate_comment().