flexdoc 0.1.0__py3-none-any.whl

flexdoc/__init__.py

@@ -0,0 +1,54 @@
+"""
+flexdoc is a source-grounded, layered document model for Markdown and text: parse to a
+`FlexDoc`, query its structure across independent layers with `collect()`, serialize it
+as a `DocGraph`, and anchor spans and edits with `SpanRef` so they survive reparse. It
+is a standalone library (chopdiff builds its diff and windowed-transform layer on top
+of it).
+
+The root exports the working set for typical use — the entry point, the serialization
+contract, the reference type, and the enums nearly every query or measurement needs:
+
+```
+from flexdoc import FlexDoc, NodeKind, TextUnit
+
+doc = FlexDoc.from_text(markdown_text)
+links = doc.collect(kinds={NodeKind.link}, recursive=True)
+words = doc.size(TextUnit.words)
+```
+
+The full public surfaces live in the submodules:
+
+- `flexdoc.docs` — `FlexDoc`, `Paragraph`, `Sentence`, `Section`, `Block`, `BlockType`,
+  the node table, `collect()`, `DocGraph`, `SpanRef` and its resolvers, render helpers
+  for source-linked HTML, token diffs/mappings, and word-token utilities.
+- `flexdoc.html` — html-in-md, html/plaintext conversion, HTML tag helpers, the content
+  extractor, and timestamp extraction.
+- `flexdoc.util` — read-time and token-count estimation.
+
+Unit types (`Paragraph`, `Sentence`, `Section`, `Block`, `Node`) are reached from a
+parsed `FlexDoc` rather than imported, so they stay in `flexdoc.docs`, as do functions
+whose bare names need module context (e.g. `resolve`). Root additions are deliberate;
+`tests/test_root_api.py` pins the exact surface.
+"""
+
+from flexdoc.docs import (
+    BlockType,
+    Detail,
+    DocGraph,
+    FlexDoc,
+    Layer,
+    NodeKind,
+    SpanRef,
+    TextUnit,
+)
+
+__all__ = [
+    "BlockType",
+    "Detail",
+    "DocGraph",
+    "FlexDoc",
+    "Layer",
+    "NodeKind",
+    "SpanRef",
+    "TextUnit",
+]

flexdoc/docs/__init__.py

@@ -0,0 +1,155 @@
+# flake8: noqa: F401
+
+from flexdoc.docs.base_blocks import BaseBlock, base_blocks
+from flexdoc.docs.block_info import CodeInfo, ListInfo, TableInfo
+from flexdoc.docs.block_tree import Block, parse_blocks, walk_blocks
+from flexdoc.docs.block_types import BlockType, block_type_for
+from flexdoc.docs.collect import collect
+from flexdoc.docs.debug import (
+    doc_graph_yaml,
+    doc_report,
+    doc_report_data,
+    dump_views,
+)
+from flexdoc.docs.doc_graph import (
+    DEFAULT_INCLUDE,
+    Detail,
+    DocGraph,
+    NodeModel,
+    SourceInfo,
+    Views,
+    build_doc_graph,
+)
+from flexdoc.docs.flex_doc import FlexDoc
+from flexdoc.docs.links import Link
+from flexdoc.docs.node import LAYER_NESTING, Layer, NestingGuarantee, Node, NodeKind, NodeTable
+from flexdoc.docs.node_table import build_node_table
+from flexdoc.docs.paragraphs import Offsets, Paragraph, Sentence, SentIndex
+from flexdoc.docs.render import parse_source_span_attr, render_node_attrs, wrap_with_node_attrs
+from flexdoc.docs.search_tokens import search_tokens
+from flexdoc.docs.sections import Section
+from flexdoc.docs.sizes import TextUnit
+from flexdoc.docs.span_ref import SpanRef, resolve, resolve_and_update
+from flexdoc.docs.token_diffs import (
+    DIFF_FILTER_NONE,
+    DiffFilter,
+    DiffOp,
+    DiffStats,
+    OpType,
+    TokenDiff,
+    diff_docs,
+    diff_wordtoks,
+    scored_diff_wordtoks,
+)
+from flexdoc.docs.token_mapping import TokenMapping
+from flexdoc.docs.wordtoks import (
+    BOF_STR,
+    BOF_TOK,
+    EOF_STR,
+    EOF_TOK,
+    PARA_BR_STR,
+    PARA_BR_TOK,
+    SENT_BR_STR,
+    SENT_BR_TOK,
+    SPACE_TOK,
+    SYMBOL_SEP,
+    Tag,
+    first_wordtok,
+    is_break_or_space,
+    is_div,
+    is_header_tag,
+    is_tag,
+    is_tag_close,
+    is_tag_open,
+    is_whitespace_or_punct,
+    is_word,
+    join_wordtoks,
+    normalize_wordtok,
+    wordtok_len,
+    wordtok_to_str,
+    wordtokenize,
+    wordtokenize_with_offsets,
+)
+
+__all__ = [
+    "DEFAULT_INCLUDE",
+    "Detail",
+    "DocGraph",
+    "NodeModel",
+    "SourceInfo",
+    "Views",
+    "build_doc_graph",
+    "search_tokens",
+    "TextUnit",
+    "Block",
+    "BlockType",
+    "block_type_for",
+    "parse_blocks",
+    "walk_blocks",
+    "CodeInfo",
+    "ListInfo",
+    "TableInfo",
+    "Offsets",
+    "Link",
+    "Paragraph",
+    "Section",
+    "Sentence",
+    "SentIndex",
+    "FlexDoc",
+    "DIFF_FILTER_NONE",
+    "DiffFilter",
+    "DiffOp",
+    "DiffStats",
+    "OpType",
+    "TokenDiff",
+    "diff_docs",
+    "diff_wordtoks",
+    "scored_diff_wordtoks",
+    "TokenMapping",
+    "BOF_STR",
+    "BOF_TOK",
+    "EOF_STR",
+    "EOF_TOK",
+    "PARA_BR_STR",
+    "PARA_BR_TOK",
+    "SENT_BR_STR",
+    "SENT_BR_TOK",
+    "SPACE_TOK",
+    "SYMBOL_SEP",
+    "Tag",
+    "first_wordtok",
+    "is_break_or_space",
+    "is_div",
+    "is_header_tag",
+    "is_tag",
+    "is_tag_close",
+    "is_tag_open",
+    "is_whitespace_or_punct",
+    "is_word",
+    "join_wordtoks",
+    "normalize_wordtok",
+    "wordtok_len",
+    "wordtok_to_str",
+    "wordtokenize",
+    "wordtokenize_with_offsets",
+    "BaseBlock",
+    "base_blocks",
+    "collect",
+    "doc_report",
+    "doc_report_data",
+    "doc_graph_yaml",
+    "dump_views",
+    "LAYER_NESTING",
+    "Layer",
+    "NestingGuarantee",
+    "Node",
+    "NodeKind",
+    "NodeTable",
+    "build_node_table",
+    "SpanRef",
+    "resolve",
+    "resolve_and_update",
+    "render_node_attrs",
+    "wrap_with_node_attrs",
+    "parse_source_span_attr",
+]

flexdoc/docs/base_blocks.py

@@ -0,0 +1,170 @@
+"""
+Sequential base-block partition of a Markdown document.
+
+A base block is a unit of the flat, depth-annotated partition described in
+flexdoc-spec section 6. The partition is ordered by source position, its spans are
+non-overlapping, and together they cover every non-whitespace character of the
+document exactly once (the gaps are inter-block and structural whitespace). It is the
+view for block-by-block processing and resequencing.
+
+Each base block retains its exact `source_span`, so exact source reconstruction is
+available by slicing the source at those spans (or via the structural `blocks()` tree).
+Reassembling the rendered base-block *text* is lossy for list-item continuation content:
+list markers and continuation indentation are whitespace outside the trimmed spans, so a
+naive text concatenation normalizes them. Reconstruct from offsets when exactness matters.
+
+Leaf/atomic blocks (heading, paragraph, table, code, thematic_break, html, and
+a whole blockquote) are each one base block. Lists decompose: each list item at every
+nesting level is its own base block with increasing depth, and a list item's continuation
+content (paragraphs after or between nested sublists) is emitted with its own real block
+type at the item's depth — never relabeled `list_item`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from marko.element import Element
+
+from flexdoc.docs.block_tree import Block, parse_blocks
+from flexdoc.docs.block_types import BlockType
+
+# Block types that are always atomic (never decomposed into child base blocks).
+_ATOMIC_TYPES = frozenset(
+    {
+        BlockType.heading,
+        BlockType.paragraph,
+        BlockType.table,
+        BlockType.code,
+        BlockType.thematic_break,
+        BlockType.html,
+        BlockType.footnote,
+        BlockType.blockquote,
+    }
+)
+
+# Block types representing lists that decompose into list_item children.
+_LIST_TYPES = frozenset({BlockType.list, BlockType.ordered_list})
+
+
+@dataclass
+class BaseBlock:
+    """
+    A single unit of the sequential base-block partition. Carries the underlying
+    `Block` (with its type, span, and children) and the `depth` indicating nesting
+    level (0 for top-level blocks, increasing for nested list items).
+    """
+
+    block: Block
+    depth: int
+
+
+def base_blocks(
+    text: str, *, item_partition_depth: int = 6, parsed: Element | None = None
+) -> list[BaseBlock]:
+    """
+    Produce the flat, depth-annotated sequential block partition.
+
+    - `item_partition_depth = N` (default 6): split list items down to N nesting
+      levels; content nested deeper stays whole inside its depth-N base block.
+    - `item_partition_depth = -1`: unlimited; split at every nesting level.
+    - `item_partition_depth = 0`: lists are not split; each list is one base block.
+
+    Blockquotes are always one base block regardless of depth.
+
+    `parsed` is the marko parse of `text`; pass it to reuse a shared parse, else `text`
+    is parsed here.
+
+    Invariants: the result is ordered by source position, spans are non-overlapping, and
+    together they cover every non-whitespace character exactly once. Exact source
+    reconstruction is via each block's `source_span` (not by concatenating block text;
+    see the module docstring for the continuation-content caveat).
+    """
+    blocks = parse_blocks(text, parsed)
+    result: list[BaseBlock] = []
+    _collect_base_blocks(text, blocks, 0, item_partition_depth, result)
+    return result
+
+
+def _collect_base_blocks(
+    text: str,
+    blocks: list[Block],
+    depth: int,
+    max_depth: int,
+    out: list[BaseBlock],
+) -> None:
+    """
+    Recursively collect base blocks. Lists decompose into their list_item
+    children; list items decompose further if they contain nested lists (up to
+    `max_depth`). Atomic blocks and blockquotes are emitted whole.
+    """
+    for block in blocks:
+        if block.type in _ATOMIC_TYPES:
+            out.append(BaseBlock(block=block, depth=depth))
+        elif block.type in _LIST_TYPES:
+            if max_depth == 0:
+                # Lists not split: emit the whole list as one base block.
+                out.append(BaseBlock(block=block, depth=depth))
+            else:
+                # Decompose: each list_item child becomes a base block (or further
+                # decomposes if it contains nested lists).
+                for item in block.children:
+                    _emit_list_item(text, item, depth, max_depth, 1, out)
+        elif block.type == BlockType.list_item:
+            # A bare list_item at the top level (unusual) is treated as atomic.
+            out.append(BaseBlock(block=block, depth=depth))
+        else:
+            # Any other block type not explicitly handled: emit as atomic.
+            out.append(BaseBlock(block=block, depth=depth))
+
+
+def _emit_list_item(
+    text: str,
+    item: Block,
+    depth: int,
+    max_depth: int,
+    current_nesting: int,
+    out: list[BaseBlock],
+) -> None:
+    """
+    Emit a list item as base blocks. A leaf item (no nested lists, or at the depth
+    limit) emits its full span as one block. Otherwise the item decomposes, in source
+    order, into:
+
+    - one `list_item` head block spanning from the item start (the list marker) through
+      its lead content up to the first nested sublist, at `depth`;
+    - each nested sublist's items, recursed at `depth + 1`;
+    - each *continuation* block (content after or between sublists) emitted with its own
+      real block type (e.g. `paragraph`), at `depth`.
+
+    Continuation content keeps its real type rather than being mislabeled `list_item`, so
+    a consumer can tell a continuation paragraph apart from an independent list item.
+    Spans are non-overlapping and cover every non-whitespace character. Exact source
+    reconstruction is via each block's `source_span` (or the structural `blocks()` tree),
+    not by concatenating base-block text: list-marker and continuation indentation are
+    whitespace outside the trimmed spans.
+    """
+    nested_lists = [c for c in item.children if c.type in _LIST_TYPES]
+    at_depth_limit = max_depth != -1 and current_nesting >= max_depth
+
+    if not nested_lists or at_depth_limit:
+        out.append(BaseBlock(block=item, depth=depth))
+        return
+
+    # Head: the marker plus lead content up to the first nested sublist, typed list_item.
+    first_nested_start = min(c.span[0] for c in nested_lists)
+    head_end = first_nested_start
+    while head_end > item.span[0] and text[head_end - 1].isspace():
+        head_end -= 1
+    if head_end > item.span[0]:
+        head = Block(type=item.type, span=(item.span[0], head_end), children=[], tight=item.tight)
+        out.append(BaseBlock(block=head, depth=depth))
+
+    # Then, in source order: recurse into each sublist; emit each continuation block
+    # (any non-list child past the head) with its own real type.
+    for child in item.children:
+        if child.type in _LIST_TYPES:
+            for nested_item in child.children:
+                _emit_list_item(text, nested_item, depth + 1, max_depth, current_nesting + 1, out)
+        elif child.span[1] > head_end:
+            out.append(BaseBlock(block=child, depth=depth))

flexdoc/docs/block_info.py

@@ -0,0 +1,167 @@
+"""
+Typed, parser-authoritative metadata for code, table, and list blocks.
+
+The structs (`CodeInfo`, `TableInfo`, `ListInfo`) and the pure extractors that read them
+off a marko block element are the single place that knows how to pull a
+language/dimension/list fact from the parse. Both the structural `Block` path (the
+density-invariant source of truth) and the `Paragraph` editing-view path reuse these, so
+neither re-parses and both agree.
+
+Extraction is parser-authoritative: every fact comes from a marko element attribute
+(`FencedCode.lang`, `Table.num_of_cols` and per-cell `.align`, `List.ordered`/`.start`/
+subtree), never a regex over source text, matching `block_types.py`'s rule.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from marko.block import CodeBlock, FencedCode, List, ListItem
+from marko.element import Element
+from marko.ext.gfm.elements import Table, TableCell, TableRow
+
+Alignment = Literal["left", "center", "right", "default"]
+"""A table column's alignment; `default` when the delimiter row leaves it undefined (no
+colon), so the per-column list is always explicit strings, never empty/null entries."""
+
+
+@dataclass(frozen=True)
+class CodeInfo:
+    """Typed metadata for a code block."""
+
+    language: str | None
+    """Fenced info-string language; `None` for an indented code block (no info string)."""
+    line_count: int
+    """Body lines, excluding the fence lines."""
+
+
+@dataclass(frozen=True)
+class TableInfo:
+    """Typed metadata for a GFM table."""
+
+    rows: int
+    """Total rows, including the header row."""
+    cols: int
+    """Columns (marko `Table.num_of_cols`)."""
+    cells: int
+    """`rows * cols`."""
+    alignments: list[Alignment]
+    """Per-column alignment, length `cols`."""
+
+
+@dataclass(frozen=True)
+class ListInfo:
+    """Typed metadata for a list block."""
+
+    ordered: bool
+    start: int | None
+    """`List.start` when ordered (e.g. `3` for `3.`), else `None`."""
+    max_depth: int
+    """`1` for a flat list, `2` with one level of nested sublist, and so on."""
+    item_count: int
+    """Direct `list_item` children."""
+
+
+def _code_body(element: FencedCode | CodeBlock) -> str:
+    """The code block's body text: its `RawText` children concatenated."""
+    parts: list[str] = []
+    for child in getattr(element, "children", []) or []:
+        raw = getattr(child, "children", None)
+        if isinstance(raw, str):
+            parts.append(raw)
+    return "".join(parts)
+
+
+def code_info_for(element: Element) -> CodeInfo | None:
+    """`CodeInfo` if `element` is a fenced or indented code block, else `None`."""
+    if not isinstance(element, (FencedCode, CodeBlock)):
+        return None
+    lang = getattr(element, "lang", "") or ""
+    return CodeInfo(language=lang or None, line_count=len(_code_body(element).splitlines()))
+
+
+def _alignment(cell: object) -> Alignment:
+    """A cell's column alignment; `default` when the delimiter leaves it undefined."""
+    match getattr(cell, "align", None):
+        case "left" | "center" | "right" as align:
+            return align
+        case _:
+            return "default"
+
+
+def table_info_for(element: Element) -> TableInfo | None:
+    """`TableInfo` if `element` is a GFM table, else `None`."""
+    if not isinstance(element, Table):
+        return None
+    table_rows = [c for c in element.children if isinstance(c, TableRow)]
+    cols = int(getattr(element, "num_of_cols", 0) or 0)
+    header_cells = (
+        [c for c in table_rows[0].children if isinstance(c, TableCell)] if table_rows else []
+    )
+    alignments: list[Alignment] = [_alignment(c) for c in header_cells]
+    rows = len(table_rows)
+    return TableInfo(rows=rows, cols=cols, cells=rows * cols, alignments=alignments)
+
+
+def _list_max_depth(element: List) -> int:
+    """Max list nesting: `1` for a flat list, `+1` per level of nested sublist."""
+    deepest = 0
+    for item in element.children:
+        if not isinstance(item, ListItem):
+            continue
+        for sub in getattr(item, "children", []) or []:
+            if isinstance(sub, List):
+                deepest = max(deepest, _list_max_depth(sub))
+    return 1 + deepest
+
+
+def list_info_for(element: Element) -> ListInfo | None:
+    """`ListInfo` if `element` is a list, else `None`."""
+    if not isinstance(element, List):
+        return None
+    ordered = bool(element.ordered)
+    start = int(element.start) if ordered and getattr(element, "start", None) is not None else None
+    item_count = sum(1 for c in element.children if isinstance(c, ListItem))
+    return ListInfo(
+        ordered=ordered, start=start, max_depth=_list_max_depth(element), item_count=item_count
+    )
+
+
+## Tests
+
+
+def _parse_first(markdown: str) -> Element:
+    from flowmark import flowmark_markdown
+    from marko.block import BlankLine
+
+    parsed = flowmark_markdown().parse(markdown)
+    return next(el for el in parsed.children if not isinstance(el, BlankLine))
+
+
+def test_code_info_extractor():
+    assert code_info_for(_parse_first("```python\nx = 1\ny = 2\n```\n")) == CodeInfo("python", 2)
+    # Indented code has no info string, so language is None.
+    assert code_info_for(_parse_first("    indented\n    code\n")) == CodeInfo(None, 2)
+    # A non-code element yields None.
+    assert code_info_for(_parse_first("just a paragraph\n")) is None
+
+
+def test_table_info_extractor():
+    table = _parse_first("| a | b | c |\n|:--|:-:|--:|\n| 1 | 2 | 3 |\n| 4 | 5 | 6 |\n")
+    info = table_info_for(table)
+    assert info == TableInfo(rows=3, cols=3, cells=9, alignments=["left", "center", "right"])
+    # Columns with no alignment marker are "default", never empty/None.
+    plain = _parse_first("| a | b |\n| - | - |\n| 1 | 2 |\n")
+    assert table_info_for(plain) == TableInfo(
+        rows=2, cols=2, cells=4, alignments=["default", "default"]
+    )
+    assert table_info_for(_parse_first("paragraph\n")) is None
+
+
+def test_list_info_extractor():
+    ordered = _parse_first("3. a\n4. b\n   - nested1\n   - nested2\n5. c\n")
+    assert list_info_for(ordered) == ListInfo(ordered=True, start=3, max_depth=2, item_count=3)
+    flat = _parse_first("- a\n- b\n")
+    assert list_info_for(flat) == ListInfo(ordered=False, start=None, max_depth=1, item_count=2)
+    assert list_info_for(_parse_first("paragraph\n")) is None

flexdoc/docs/block_tree.py

@@ -0,0 +1,142 @@
+"""
+Structural block tree for a Markdown document, with exact source spans.
+
+This is the opt-in, whole-document structural view (`FlexDoc.blocks()`) that resolves
+what blank-line paragraph splitting cannot: it keeps a fenced code block whole even when
+it contains blank lines, and it decomposes a list into individual `list_item`s with
+nested sublists regardless of item spacing.
+
+Block boundaries and spans come straight from flowmark's parser: every block element
+produced by `flowmark_markdown().parse(text)` carries an authoritative
+`element.span = (start, end)` read from marko's own parser state (see
+`flowmark.markdown_ast.block_span`). flexdoc makes no block-boundary decisions of its
+own, so there is no regex scanner and no per-line heuristic.
+
+Containers (lists, list items, blockquotes) fully populate their block children
+recursively, so a table inside a blockquote or a paragraph inside a list item is
+reachable in the tree. The top-level `blocks()`/`parse_blocks` ordering and the `Block`
+dataclass shape are unchanged.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from flowmark import flowmark_markdown
+from flowmark.markdown_ast import block_span
+from marko.block import BlankLine, CodeBlock, List, ListItem
+from marko.block import Quote as MarkoQuote
+from marko.element import Element
+
+from flexdoc.docs.block_info import (
+    CodeInfo,
+    ListInfo,
+    TableInfo,
+    code_info_for,
+    list_info_for,
+    table_info_for,
+)
+from flexdoc.docs.block_types import BlockType, block_type_for
+
+
+@dataclass
+class Block:
+    """
+    A structural block with an exact `[start, end)` span into the source.
+
+    `children` holds nested blocks: a `list`/`ordered_list` block's children are its
+    `list_item`s, and a `list_item`'s children are ALL its block children (paragraphs,
+    nested lists, tables, code, etc.). A `blockquote`'s children are its nested blocks.
+    Leaf blocks (heading, code, table, thematic_break, etc.) have no children. `span` is
+    trimmed of surrounding whitespace, so `source[start:end]` is the block's exact text.
+
+    `tight` carries CommonMark list density for `list`/`ordered_list` blocks (`True` when
+    items have no blank lines between them), and is `None` for every other block type.
+    The block tree is density-invariant: a loose list still decomposes into one list
+    block with the same `list_item` children as its tight form, so `tight` records the
+    spacing without changing the structure or the tallies.
+
+    `code_info`, `table_info`, and `list_info` carry typed, parser-authoritative metadata
+    (see `block_info`): each is non-`None` only for its block kind (`code` / `table` /
+    `list`/`ordered_list`). They are derived facts about the same source span, so they do
+    not participate in equality or `repr` (a block's identity is its type/span/children).
+    """
+
+    type: BlockType
+    span: tuple[int, int]
+    children: list[Block] = field(default_factory=list)
+    tight: bool | None = None
+    code_info: CodeInfo | None = field(default=None, compare=False, repr=False)
+    table_info: TableInfo | None = field(default=None, compare=False, repr=False)
+    list_info: ListInfo | None = field(default=None, compare=False, repr=False)
+
+
+def parse_blocks(text: str, parsed: Element | None = None) -> list[Block]:
+    """
+    Parse `text` into a tree of structural `Block`s with exact source spans.
+
+    `parsed` is the marko parse of `text`; pass it to reuse a shared parse (the caller
+    guarantees it is the parse of exactly this `text`), else `text` is parsed here.
+    """
+    return _blocks_from(text, parsed if parsed is not None else flowmark_markdown().parse(text))
+
+
+def walk_blocks(blocks: list[Block], _depth: int = 0) -> Iterator[tuple[Block, int]]:
+    """
+    Depth-first traversal of a block tree, yielding `(block, depth)` pairs.
+    Top-level blocks have depth 0; their children have depth 1, and so on.
+    """
+    for block in blocks:
+        yield block, _depth
+        yield from walk_blocks(block.children, _depth + 1)
+
+
+def _trim(text: str, lo: int, hi: int, *, keep_leading: bool = False) -> tuple[int, int]:
+    """Shrink a span to drop surrounding whitespace (marko spans include trailing newlines
+    and a nested element's leading indentation/marker line). When `keep_leading` is True,
+    only trailing whitespace is stripped (for indented code blocks whose leading spaces are
+    syntax)."""
+    if not keep_leading:
+        while lo < hi and text[lo].isspace():
+            lo += 1
+    while hi > lo and text[hi - 1].isspace():
+        hi -= 1
+    return lo, hi
+
+
+def _blocks_from(text: str, parent: Element) -> list[Block]:
+    """
+    Build `Block`s from `parent`'s block children, skipping blank lines. Every
+    container populates all its block children recursively: a `list` decomposes into
+    `list_item`s, a `list_item` keeps all its block children (paragraphs, nested lists,
+    tables, code, etc.), and a `blockquote` keeps all its nested blocks.
+    """
+    blocks: list[Block] = []
+    children: list[Element] = getattr(parent, "children", []) or []
+    for element in children:
+        if isinstance(element, BlankLine):
+            continue
+        block_type = block_type_for(element)
+        # Indented code blocks: preserve leading whitespace (the 4-space indent is syntax).
+        span = _trim(text, *block_span(element), keep_leading=isinstance(element, CodeBlock))
+        tight: bool | None = None
+        if isinstance(element, List):
+            sub = _blocks_from(text, element)
+            tight = element.tight
+        elif isinstance(element, (ListItem, MarkoQuote)):
+            sub = _blocks_from(text, element)
+        else:
+            sub = []
+        blocks.append(
+            Block(
+                block_type,
+                span,
+                sub,
+                tight,
+                code_info=code_info_for(element),
+                table_info=table_info_for(element),
+                list_info=list_info_for(element),
+            )
+        )
+    return blocks