Skip to content

Blocks

rn_forge.commons.fs.blocks

Managed blocks: one owner's fenced region inside a file another owner writes.

A :class:ManagedBlock owns the bytes between two markers and preserves the rest of the file.

Example::

block = ManagedBlock("my-tool")
text = block.render(gitignore_text, ".my-tool/backups/\n")
block.extract(text)   # -> '.my-tool/backups/\n'
block.remove(text)    # -> the original text

HASH_COMMENT = '#' module-attribute

Comment style for #-commented files (.gitignore, YAML, TOML, Python).

HTML_COMMENT = '<!--' module-attribute

Comment style for Markdown and HTML.

ManagedBlock(name, comment=HASH_COMMENT, indent='', end_indent=None) dataclass

A named, fenced region of a file owned by one generator.

Parameters:

Name Type Description Default
name str

The block's name, appearing in both markers. Two blocks in one file must not share a name.

required
comment str

"#" for hash-commented formats (the default) or "<!--" for Markdown/HTML.

HASH_COMMENT
indent str

Leading whitespace the markers carry, for formats where the block sits inside an indented structure (mkdocs.yml's nav: uses two spaces). Applied to the markers only; the body is inserted as given.

''
end_indent str | None

Leading whitespace of the end marker alone. None (the default) uses indent; "" puts the end marker at the left margin.

None

begin property

The opening marker line, without its trailing newline.

end property

The closing marker line, without its trailing newline.

extract(text)

Return the block's body, or None when the block is absent.

    The body is everything strictly between the markers (``""`` for an
    empty block), with the file's newline sequence normalised to ``"

"`` so that it compares equal to freshly rendered content regardless of how the file on disk is terminated.

    Raises:
        AppException: The markers are malformed (see :meth:`render`).

remove(text)

Return text with the block and its markers removed.

A single blank line left immediately before the removed block is dropped with it — that is the separator :meth:render inserts, so repeated render/remove cycles do not accumulate whitespace. Any further blank lines were the file's own and are kept. Returns text unchanged when the block is absent.

Raises:

Type Description
AppException

The markers are malformed (see :meth:render).

render(text, body)

Return text with the block's body replaced by body.

When the block is absent it is appended to the end of text, separated by a blank line. Everything outside the markers is preserved byte for byte: the surrounding text keeps its own newline sequences, its indentation and its lack (or presence) of a terminal newline. Inside the markers the generator owns the bytes, so body is re-terminated with the newline sequence the file itself uses.

Raises:

Type Description
AppException

A marker appears more than once, one marker is present without the other, or they appear in the wrong order.