Rich text

This section documents rich text nodes, inline objects, and timestamps.

text

Rich text and inline object representations.

This subpackage exposes org_parser.text.RichText together with public inline object abstractions used to construct or inspect rich text programmatically.

Classes:

Name	Description
RichText	Rich text content represented as Org inline objects.
InlineObject	Base class for inline markup objects.
PlainText	Plain text object.
LineBreak	Hard line break object.
InlineEntity	Org entity inline object.
CompletionCounter	Completion counter object, e.g. [1/3] or [50%].
Bold	Bold inline markup object.
Italic	Italic inline markup object.
Underline	Underline inline markup object.
StrikeThrough	Strike-through inline markup object.
Subscript	Subscript inline object.
Superscript	Superscript inline object.
Verbatim	Verbatim inline markup object.
Code	Inline code markup object.
ExportSnippet	Export snippet object, e.g. @@html:<em>@@.
FootnoteReference	Footnote reference object.
Citation	Citation object.
InlineSourceBlock	Inline source block object.
Macro	Macro call object, e.g. {{{name}}} or {{{name(args)}}}.
InlineBabelCall	Inline babel call object, e.g. call_double[:exports none](n=4).
PlainLink	Plain link object.
AngleLink	Angle link object.
RegularLink	Regular bracket link object.
Target	Target object, e.g. <<name>>.
RadioTarget	Radio target object, e.g. <<<phrase>>>.

RichText

RichText(
    text_or_parts: str | list[InlineObject] = "",
    *,
    parent: Document | Heading | Element | None = None,
)

Rich text content represented as Org inline objects.

The instance remains parse-tree-backed until mutated. While clean, string conversion yields the exact verbatim source range from the original parse input. Once mutated, rendering is reconstructed from the cached object sequence.

Parameters:

Name	Type	Description	Default
text_or_parts	str | list[InlineObject]	Initial content as a plain string or an explicit list of inline object abstractions.	''

Example:

>>> from org_parser.text import RichText
>>> text = RichText.from_source("Use *bold* text")
>>> text.parts[1].raw
'*bold*'

Methods:

Name	Description
__eq__	Compare by rendered textual content.
__getitem__	Return one inline-object part (or part slice).
__hash__	Hash by rendered textual content.
__iter__	Iterate over inline-object parts.
__len__	Return number of inline-object parts.
__repr__	Return a developer-friendly representation.
__str__	Return rich text as Org syntax.
append	Append content.
from_node	Create a org_parser.text.RichText from a single tree-sitter node.
from_nodes	Create a org_parser.text.RichText from multiple contiguous nodes.
from_source	Parse source and return one strict org_parser.text.RichText value.
insert	Insert content at index.
mark_dirty	Mark this rich text as dirty.
prepend	Prepend content.
reformat	Mark nested inline objects, then this rich text, as dirty.

Attributes:

Name	Type	Description
dirty	bool	Whether this rich text has been mutated after creation.
parent	Document | Heading | Element | None	Parent object that contains this rich text, if any.
parts	list[InlineObject]	Inline object parts in source order.
stripped	RichText	Return a new rich text value with inline markup removed.
text	str	Textual representation of this rich text.
trimmed	RichText	Return a new rich text value with outer whitespace removed.

dirty property

dirty: bool

Whether this rich text has been mutated after creation.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this rich text, if any.

parts property

parts: list[InlineObject]

Inline object parts in source order.

Example:

>>> from org_parser.text import RichText
>>> text = RichText.from_source("Use *bold* text")
>>> len(text.parts)
4

stripped property

stripped: RichText

Return a new rich text value with inline markup removed.

This keeps visible text content while removing emphasis delimiters and bracket wrappers for links/citations/footnotes.

text property writable

text: str

Textual representation of this rich text.

Example:

>>> from org_parser.text import RichText
>>> text = RichText.from_source("Use *bold* text")
>>> text.text
'Use *bold* text'
>>> text.text = "updated"
>>> text.text
'updated'

trimmed property

trimmed: RichText

Return a new rich text value with outer whitespace removed.

The returned value preserves object identity for unchanged inline parts where safe. Timestamp parts are cloned so each rich-text value keeps its own mutable timestamp instances.

__eq__

__eq__(other: object) -> bool

Compare by rendered textual content.

__getitem__

__getitem__(
    index: int | slice,
) -> InlineObject | list[InlineObject]

Return one inline-object part (or part slice).

__hash__

__hash__() -> int

Hash by rendered textual content.

__iter__

__iter__() -> Iterator[InlineObject]

Iterate over inline-object parts.

__len__

__len__() -> int

Return number of inline-object parts.

__repr__

__repr__() -> str

Return a developer-friendly representation.

__str__

__str__() -> str

Return rich text as Org syntax.

append

append(part: InlineObject | str) -> None

Append content.

Example:

>>> from org_parser.text import RichText
>>> text = RichText("A")
>>> text.append("B")
>>> text.text
'AB'

from_node classmethod

from_node(
    node: Node,
    *,
    document: Document,
    parent: Document | Heading | Element | None = None,
) -> RichText

Create a org_parser.text.RichText from a single tree-sitter node.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node to parse.	required
document	Document	The owning org_parser.document.Document.	required
parent	Document | Heading | Element | None	Optional parent owner object.	None

from_nodes classmethod

from_nodes(
    nodes: Sequence[Node],
    *,
    document: Document,
    parent: Document | Heading | Element | None = None,
) -> RichText

Create a org_parser.text.RichText from multiple contiguous nodes.

Parameters:

Name	Type	Description	Default
nodes	Sequence[Node]	Ordered sequence of tree-sitter nodes to parse.	required
document	Document	The owning org_parser.document.Document.	required
parent	Document | Heading | Element | None	Optional parent owner object.	None

from_source classmethod

from_source(source: str) -> RichText

Parse source and return one strict org_parser.text.RichText value.

The source must parse to exactly one paragraph element and no headings or zeroth-section metadata.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing one rich-text paragraph.	required

Returns:

Type	Description
RichText	Parsed org_parser.text.RichText for the paragraph content.

Raises:

Type	Description
ValueError	If parsing fails or the structure is not one paragraph.

insert

insert(index: int, part: InlineObject | str) -> None

Insert content at index.

Example:

>>> from org_parser.text import RichText, PlainText
>>> text = RichText("AC")
>>> text.insert(0, "B")
>>> text.text
'BAC'

mark_dirty

mark_dirty() -> None

Mark this rich text as dirty.

prepend

prepend(part: InlineObject | str) -> None

Prepend content.

Example:

>>> from org_parser.text import RichText
>>> text = RichText("B")
>>> text.prepend("A")
>>> text.text
'AB'

reformat

reformat() -> None

Mark nested inline objects, then this rich text, as dirty.

InlineObject

Base class for inline markup objects.

Methods:

Name	Description
__str__	Render this inline object to Org text.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render this inline object to Org text.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

PlainText dataclass

PlainText(text: str)

Bases: InlineObject

Plain text object.

Methods:

Name	Description
__str__	Render plain text as-is.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render plain text as-is.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

LineBreak dataclass

LineBreak(trailing: str = '')

Bases: InlineObject

Hard line break object.

Methods:

Name	Description
__str__	Render a hard line break token.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render a hard line break token.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

InlineEntity dataclass

InlineEntity(name: str, has_braces: bool = False)

Bases: InlineObject

Org entity inline object.

Represents named entities (e.g. \alpha, \\Rightarrow) and the non-breaking-space form \\_ (backslash-underscore followed by one or more spaces).

For named entities has_braces indicates whether the {} suffix was written (\alpha{}), which prevents the entity name from merging with adjacent text in some export backends.

The \\_ form is represented with name="_". Its __str__ always emits a single trailing space; round-trip fidelity for multiple trailing spaces relies on the parse-tree-backed source slice in org_parser.text.RichText.

Parameters:

Name	Type	Description	Default
name	str	Entity name (e.g. "alpha") or "_" for the \\_ form.	required
has_braces	bool	Whether the {} suffix was written (named entities only).	False

Methods:

Name	Description
__str__	Render entity to Org syntax.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render entity to Org syntax.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

CompletionCounter dataclass

CompletionCounter(value: str)

Bases: InlineObject

Completion counter object, e.g. [1/3] or [50%].

Example:

>>> from org_parser.text import CompletionCounter
>>> document = loads("* Heading")
>>> document[0].counter = CompletionCounter("1/3")
>>> print(str(document))
* [1/3] Heading

Methods:

Name	Description
__str__	Render completion counter.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render completion counter.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Bold dataclass

Bold(body: list[InlineObject])

Bases: InlineObject

Bold inline markup object.

Methods:

Name	Description
__str__	Render bold markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render bold markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Italic dataclass

Italic(body: list[InlineObject])

Bases: InlineObject

Italic inline markup object.

Methods:

Name	Description
__str__	Render italic markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render italic markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Underline dataclass

Underline(body: list[InlineObject])

Bases: InlineObject

Underline inline markup object.

Methods:

Name	Description
__str__	Render underline markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render underline markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

StrikeThrough dataclass

StrikeThrough(body: list[InlineObject])

Bases: InlineObject

Strike-through inline markup object.

Methods:

Name	Description
__str__	Render strike-through markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render strike-through markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Subscript dataclass

Subscript(body: list[InlineObject], form: str = '{}')

Bases: InlineObject

Subscript inline object.

Methods:

Name	Description
__str__	Render subscript markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render subscript markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Superscript dataclass

Superscript(body: list[InlineObject], form: str = '{}')

Bases: InlineObject

Superscript inline object.

Methods:

Name	Description
__str__	Render superscript markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render superscript markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Verbatim dataclass

Verbatim(body: str)

Bases: InlineObject

Verbatim inline markup object.

Methods:

Name	Description
__str__	Render verbatim markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render verbatim markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Code dataclass

Code(body: str)

Bases: InlineObject

Inline code markup object.

Methods:

Name	Description
__str__	Render code markup.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render code markup.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

ExportSnippet dataclass

ExportSnippet(backend: str, value: str | None = None)

Bases: InlineObject

Export snippet object, e.g. @@html:<em>@@.

Methods:

Name	Description
__str__	Render export snippet.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render export snippet.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

FootnoteReference dataclass

FootnoteReference(
    label: str | None = None,
    definition: list[InlineObject] | None = None,
)

Bases: InlineObject

Footnote reference object.

Methods:

Name	Description
__str__	Render footnote reference.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render footnote reference.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Citation dataclass

Citation(body: str | None = None, style: str | None = None)

Bases: InlineObject

Citation object.

Methods:

Name	Description
__str__	Render citation object.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render citation object.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

InlineSourceBlock dataclass

InlineSourceBlock(
    language: str,
    headers: str | None = None,
    body: str | None = None,
)

Bases: InlineObject

Inline source block object.

Methods:

Name	Description
__str__	Render inline source block.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render inline source block.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Macro dataclass

Macro(name: str, arguments: str | None = None)

Bases: InlineObject

Macro call object, e.g. {{{name}}} or {{{name(args)}}}.

Methods:

Name	Description
__str__	Render macro call.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render macro call.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

InlineBabelCall dataclass

InlineBabelCall(
    name: str,
    arguments: str | None = None,
    inside_header: str | None = None,
    outside_header: str | None = None,
)

Bases: InlineObject

Inline babel call object, e.g. call_double[:exports none](n=4).

Represents the inline form of an Org babel call that can appear inside paragraph text and heading titles.

Parameters:

Name	Type	Description	Default
name	str	The called function name.	required
arguments	str | None	Optional argument string inside (…).	None
inside_header	str | None	Optional header string inside the first […].	None
outside_header	str | None	Optional header string inside the second […].	None

Methods:

Name	Description
__str__	Render inline babel call.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render inline babel call.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

PlainLink dataclass

PlainLink(link_type: str, path: str)

Bases: InlineObject

Plain link object.

Methods:

Name	Description
__str__	Render plain link.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render plain link.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

AngleLink dataclass

AngleLink(path: str, link_type: str | None = None)

Bases: InlineObject

Angle link object.

Methods:

Name	Description
__str__	Render angle link.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render angle link.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

RegularLink dataclass

RegularLink(
    path: str, description: list[InlineObject] | None = None
)

Bases: InlineObject

Regular bracket link object.

Methods:

Name	Description
__str__	Render regular link.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render regular link.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

Target dataclass

Target(value: str)

Bases: InlineObject

Target object, e.g. <<name>>.

Methods:

Name	Description
__str__	Render target.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render target.

reformat

reformat() -> None

No-op reformat for immutable inline objects.

RadioTarget dataclass

RadioTarget(body: list[InlineObject])

Bases: InlineObject

Radio target object, e.g. <<<phrase>>>.

Methods:

Name	Description
__str__	Render radio target.
reformat	No-op reformat for immutable inline objects.

__str__

__str__() -> str

Render radio target.

reformat

reformat() -> None

No-op reformat for immutable inline objects.