jellycell.format.pep723

PEP-723 script block extraction and re-insertion.

Jupytext treats the # /// script block as a regular code cell and mutates it on first round-trip (prepending a # %% marker). We strip the block pre-parse and reinsert it verbatim post-write (spec §1 “piggyback map”, §2.2 “Format”).

The block must be at the top of the file per spec §7; :func:position_ok is used by the pep723-position lint rule.

See Also: PEP 723 — https://peps.python.org/pep-0723/

Module Contents

Functions

extract	Extract the PEP-723 script block from text.
insert	Insert a PEP-723 block ahead of body.
parse_content	Parse the TOML content of a PEP-723 block (strips the # prefixes).
jellycell_overrides	Extract [tool.jellycell] overrides from a PEP-723 block, if any.
position_ok	Return True iff any PEP-723 block is at the top of the file.
move_to_top	Move a mid-file PEP-723 block to the top of text.

Data

PEP723_PATTERN

API

jellycell.format.pep723.PEP723_PATTERN

‘compile(…)’

jellycell.format.pep723.extract(text: str) → tuple[str | None, str]

Extract the PEP-723 script block from text.

Returns: (block, body). block is the verbatim matched substring or None if no block is present. body is text with the block removed. Round-trip byte-exact via :func:insert.

jellycell.format.pep723.insert(block: str | None, body: str) → str

Insert a PEP-723 block ahead of body.

Inverse of :func:extract for block-at-top inputs: insert(*extract(text)) == text.

jellycell.format.pep723.parse_content(block: str) → dict[str, Any]

Parse the TOML content of a PEP-723 block (strips the # prefixes).

jellycell.format.pep723.jellycell_overrides(block: str | None) → dict[str, Any]

Extract [tool.jellycell] overrides from a PEP-723 block, if any.

Returns an empty dict if no block, no [tool], or no [tool.jellycell].

jellycell.format.pep723.position_ok(text: str) → bool

Return True iff any PEP-723 block is at the top of the file.

Implements the pep723-position lint rule (spec §7): a block is well-positioned iff only whitespace precedes its opening # /// script.

jellycell.format.pep723.move_to_top(text: str) → str

Move a mid-file PEP-723 block to the top of text.

No-op if there’s no block or the block is already at the top. Auto-fix for the pep723-position lint violation.