Elements

This section documents structural element objects in the semantic tree.

element

Greater and lesser element representations.

This subpackage provides Python types that wrap individual tree-sitter nodes corresponding to Org Mode elements — the structural building blocks of an org document such as paragraphs, plain lists, source blocks, drawers, and planning entries.

The primary base type is org_parser.element.Element. Concrete subclasses cover all known Org element node types; unknown or error nodes are recovered as a org_parser.element.Paragraph wrapping the verbatim source text.

Classes:

Name	Description
Element	Base class for an Org Mode element node.
AffiliatedKeyword	Base class for affiliated keyword lines (#+KEY: value).
BabelCall	A #+call: babel call element.
BlankLine	A blank separator line between body elements.
CaptionKeyword	A #+CAPTION: affiliated keyword line.
CenterBlock	#+begin_center block with mutable nested element contents.
Comment	A single-line # comment.
CommentBlock	#+begin_comment block with mutable raw text contents.
Drawer	Generic drawer element with a mutable name and body.
DynamicBlock	#+begin: dynamic block with mutable nested element contents.
ExampleBlock	#+begin_example block with mutable raw text contents.
ExportBlock	#+begin_export block with mutable raw text contents.
FixedWidthBlock	Fixed-width area line with mutable content text.
HorizontalRule	A horizontal rule line (five or more dashes).
Indent	Indentation wrapper node with nested body elements.
Keyword	Special keyword element, e.g. #+TITLE: Value.
List	Plain list element containing mutable org_parser.element.ListItem instances.
ListItem	One mutable plain-list item with all item-level metadata.
Logbook	Specialized drawer for :LOGBOOK: entries.
Paragraph	Paragraph element that stores parsed rich-text body content.
PlotKeyword	A #+PLOT: affiliated keyword line.
Properties	Property drawer element with dictionary-like mutable access.
QuoteBlock	#+begin_quote block with mutable nested element contents.
Repeat	Repeated-task logbook entry represented as a specialized list item.
ResultsKeyword	A #+RESULTS: affiliated keyword line.
SourceBlock	#+begin_src block with mutable source text contents.
SpecialBlock	#+begin_<name> block with mutable nested element contents.
Table	Org table semantic element.
TableEl	Opaque Table.el grid semantic element.
TblnameKeyword	A #+TBLNAME: affiliated keyword line.
VerseBlock	#+begin_verse block with mutable nested element contents.
DirtyList	List that invokes a callback after each in-place mutation.

Element

Element(
    *, parent: Document | Heading | Element | None = None
)

Base class for an Org Mode element node.

Concrete subclasses represent specific element types (paragraph, list, drawer, block, etc.). This class should not be instantiated directly.

Parameters:

Name	Type	Description	Default
parent	Document | Heading | Element | None	Optional parent object that owns this element.	None

Methods:

Name	Description
__repr__	Return a developer-friendly representation.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a developer-friendly representation.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

AffiliatedKeyword

AffiliatedKeyword(
    *,
    value: str | None,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Base class for affiliated keyword lines (#+KEY: value).

Affiliated keywords annotate the element immediately following them in the document body. The four concrete subclasses are org_parser.element.CaptionKeyword, org_parser.element.TblnameKeyword, org_parser.element.ResultsKeyword, and org_parser.element.PlotKeyword.

Subclasses set _keyword to the canonical upper-cased keyword string used for rendering (e.g. "CAPTION", "TBLNAME").

Parameters:

Name	Type	Description	Default
value	str | None	Optional plain-text value following the keyword.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the keyword line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.
value	str | None	Optional plain-text value following the keyword, or None.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

value property writable

value: str | None

Optional plain-text value following the keyword, or None.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the keyword line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

BabelCall

BabelCall(
    *,
    name: str,
    arguments: str | None = None,
    inside_header: str | None = None,
    outside_header: str | None = None,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

A #+call: babel call element.

Represents a top-level Org babel call line of the form::

# +call: NAME[INSIDE-HEADER](ARGUMENTS)[OUTSIDE-HEADER]

Only name is required; the three optional components default to None when absent from the source.

Parameters:

Name	Type	Description	Default
name	str	The called function name (e.g. "double").	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
parent	Document | Heading | Element | None	Optional parent owner object.	None

Example:

>>> from org_parser.element import BabelCall
>>> c = BabelCall.from_source("#+call: foo(bar)")
>>> c.name
'foo'
>>> c.arguments
'bar'

Methods:

Name	Description
__repr__	Return a developer-friendly representation.
__str__	Render the babel call line.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.BabelCall from a babel_call tree-sitter node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
arguments	str | None	Optional argument string, or None when no arguments are given.
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
inside_header	str | None	Optional inside-header string (the first […]), or None.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
name	str	The name of the called function.
outside_header	str | None	Optional outside-header string (the second […]), or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

arguments property writable

arguments: str | None

Optional argument string, or None when no arguments are given.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

inside_header property writable

inside_header: str | None

Optional inside-header string (the first […]), or None.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

name property writable

name: str

The name of the called function.

outside_header property writable

outside_header: str | None

Optional outside-header string (the second […]), or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a developer-friendly representation.

__str__

__str__() -> str

Render the babel call line.

Clean parse-backed instances preserve their verbatim source text. Dirty or scratch-built instances are reconstructed from fields.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.BabelCall from a babel_call tree-sitter node.

Parameters:

Name	Type	Description	Default
node	Node	The babel_call tree-sitter node.	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) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

BlankLine

BlankLine(
    *, parent: Document | Heading | Element | None = None
)

Bases: Element

A blank separator line between body elements.

Org Mode blank lines are structurally significant — they separate elements — but carry no semantic content of their own.

Methods:

Name	Description
__repr__	Return a developer-friendly representation.
__str__	Render the blank line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.BlankLine from a blank_line node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a developer-friendly representation.

__str__

__str__() -> str

Render the blank line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.BlankLine from a blank_line node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

CaptionKeyword

CaptionKeyword(
    *,
    value: str | None,
    short: str | None = None,
    parent: Document | Heading | Element | None = None,
)

Bases: AffiliatedKeyword

A #+CAPTION: affiliated keyword line.

Captions annotate the element immediately following them (typically a table or image). The optional short form (#+CAPTION[short]: in Org syntax) is stored separately.

Parameters:

Name	Type	Description	Default
value	str | None	The caption text following #+CAPTION:.	required
short	str | None	Optional short caption text inside […], or None.	None

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the caption line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.CaptionKeyword from a caption_keyword node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
short	str | None	Optional short caption text (the […] portion), or None.
text	str	Stringified text representation of this element.
value	str | None	Optional plain-text value following the keyword, or None.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

short property writable

short: str | None

Optional short caption text (the […] portion), or None.

text property

text: str

Stringified text representation of this element.

value property writable

value: str | None

Optional plain-text value following the keyword, or None.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the caption line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.CaptionKeyword from a caption_keyword node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

CenterBlock

CenterBlock(
    *,
    parameters: str | None = None,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: _ContainerBlock

#+begin_center block with mutable nested element contents.

Example:

>>> from org_parser.element import CenterBlock
>>> b = CenterBlock.from_source('''\
... #+begin_center :width 60
... content
... #+end_center
... ''')
>>> b.parameters
':width 60'
>>> b.body_text
'content\n'

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.CenterBlock from a center_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark contents and this block dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Mutable block contents as semantic elements.
body_text	str	Stringified text of all nested block body elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parameters	str | None	Optional trailing parameters from the begin line.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable block contents as semantic elements.

body_text property

body_text: str

Stringified text of all nested block body elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parameters property writable

parameters: str | None

Optional trailing parameters from the begin line.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.CenterBlock from a center_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark contents and this block dirty for scratch-built rendering.

Comment

Comment(
    *,
    text: str,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

A single-line # comment.

Parameters:

Name	Type	Description	Default
text	str	The comment body text, excluding the leading # marker and optional following space.	required

Example:

>>> from org_parser import loads
>>> document = loads("# comment")
>>> document.body[0].text
'comment'

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the comment line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Comment from a comment node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Mutable comment body text (excluding the # prefix).

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property writable

text: str

Mutable comment body text (excluding the # prefix).

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the comment line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Comment from a comment node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

CommentBlock

CommentBlock(
    *,
    body: str,
    parent: Document | Heading | Element | None = None,
)

Bases: _TextBlock

#+begin_comment block with mutable raw text contents.

Example:

>>> from org_parser.element import CommentBlock
>>> b = CommentBlock.from_source('''\
... #+begin_comment
... content
... #+end_comment
... ''')
>>> b.body
'content\n'

Methods:

Name	Description
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.CommentBlock from a comment_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	str	Mutable block contents text without delimiters.
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: str

Mutable block contents text without delimiters.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.CommentBlock from a comment_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

Drawer

Drawer(
    *,
    name: str,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Generic drawer element with a mutable name and body.

Parameters:

Name	Type	Description	Default
name	str	Drawer name without surrounding colons.	required
body	Sequence[Element]	Parsed child elements contained in the drawer.	()
parent	Document | Heading | Element | None	Optional parent owner object.	None

Example:

>>> from org_parser.element import Drawer
>>> d = Drawer.from_source('''\
... :DRAWER:
... some content
... :END:
... ''')
>>> d.name
'DRAWER'
>>> d.body_text
'some content\n'

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a tree-oriented representation for debugging.
__str__	Render drawer text preserving source text while clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Drawer from a tree-sitter drawer node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark body and this drawer dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Mutable list of drawer body elements.
body_text	str	Stringified text of all drawer body elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
name	str	Drawer name without surrounding colons.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable list of drawer body elements.

body_text property

body_text: str

Stringified text of all drawer body elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

name property writable

name: str

Drawer name without surrounding colons.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render drawer text preserving source text while clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Drawer from a tree-sitter drawer node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark body and this drawer dirty for scratch-built rendering.

DynamicBlock

DynamicBlock(
    *,
    name: str,
    parameters: str | None = None,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: _ContainerBlock

#+begin: dynamic block with mutable nested element contents.

Example:

>>> from org_parser.element import DynamicBlock
>>> b = DynamicBlock.from_source('''\
... #+begin: notes :value
... content
... #+end:
... ''')
>>> b.name
'notes'
>>> b.parameters
':value'
>>> b.body_text
'content\n'

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.DynamicBlock from a dynamic_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark contents and this block dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Mutable block contents as semantic elements.
body_text	str	Stringified text of all nested block body elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
name	str	Dynamic block name from the begin line.
parameters	str | None	Optional trailing parameters from the begin line.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable block contents as semantic elements.

body_text property

body_text: str

Stringified text of all nested block body elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

name property writable

name: str

Dynamic block name from the begin line.

parameters property writable

parameters: str | None

Optional trailing parameters from the begin line.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.DynamicBlock from a dynamic_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark contents and this block dirty for scratch-built rendering.

ExampleBlock

ExampleBlock(
    *,
    parameters: str | None = None,
    body: str,
    parent: Document | Heading | Element | None = None,
)

Bases: _TextBlock

#+begin_example block with mutable raw text contents.

Example:

>>> from org_parser.element import ExampleBlock
>>> b = ExampleBlock.from_source('''\
... #+begin_example :param
... content
... #+end_example
... ''')
>>> b.body
'content\n'
>>> b.parameters
':param'

Methods:

Name	Description
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.ExampleBlock from an example_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	str	Mutable block contents text without delimiters.
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parameters	str | None	Optional trailing parameters from the begin line.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: str

Mutable block contents text without delimiters.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parameters property writable

parameters: str | None

Optional trailing parameters from the begin line.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.ExampleBlock from an example_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

ExportBlock

ExportBlock(
    *,
    backend: str,
    parameters: str | None = None,
    body: str,
    parent: Document | Heading | Element | None = None,
)

Bases: _TextBlock

#+begin_export block with mutable raw text contents.

Example:

>>> from org_parser.element import ExportBlock
>>> b = ExportBlock.from_source('''\
... #+begin_export  markdown:gfm
... # content
... #+end_export
... ''')
>>> b.body
'# content\n'
>>> b.parameters
':gfm'
>>> b.backend
'markdown'

Methods:

Name	Description
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.ExportBlock from an export_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
backend	str	Export backend identifier from begin line.
body	str	Mutable block contents text without delimiters.
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parameters	str | None	Optional trailing parameters from the begin line.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

backend property writable

backend: str

Export backend identifier from begin line.

body property writable

body: str

Mutable block contents text without delimiters.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parameters property writable

parameters: str | None

Optional trailing parameters from the begin line.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.ExportBlock from an export_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

FixedWidthBlock

FixedWidthBlock(
    *,
    body: str,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Fixed-width area line with mutable content text.

Example:

>>> from org_parser.element import FixedWidthBlock
>>> b = FixedWidthBlock.from_source(": content\n")
>>> b.body
'content\n'

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render fixed-width line preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.FixedWidthBlock from a fixed_width node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	str	Mutable fixed-width content text without : prefixes.
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: str

Mutable fixed-width content text without : prefixes.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render fixed-width line preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.FixedWidthBlock from a fixed_width node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

HorizontalRule

HorizontalRule(
    *,
    rule: str = "-----",
    parent: Document | Heading | Element | None = None,
)

Bases: Element

A horizontal rule line (five or more dashes).

Parameters:

Name	Type	Description	Default
rule	str	The rule text without its trailing newline (e.g. "-----").	'-----'

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the rule line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.HorizontalRule from a horizontal_rule node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
rule	str	Mutable rule text without the trailing newline.
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

rule property writable

rule: str

Mutable rule text without the trailing newline.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the rule line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.HorizontalRule from a horizontal_rule node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

Indent

Indent(
    *,
    body: Sequence[Element] = (),
    indent: str | None = None,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Indentation wrapper node with nested body elements.

Grammar indent nodes represent one contiguous indented chunk.

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a tree-oriented representation for debugging.
__str__	Render indentation block text.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Build one org_parser.element.Indent from a tree-sitter indent node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark body and this block dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Nested elements contained by this indentation block.
body_text	str	Stringified text of all nested indentation-block elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
indent	str | None	Leading indentation for this block's first line, if known.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Nested elements contained by this indentation block.

body_text property

body_text: str

Stringified text of all nested indentation-block elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

indent property writable

indent: str | None

Leading indentation for this block's first line, if known.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render indentation block text.

Clean parse-backed instances preserve their verbatim source text. Dirty instances join their body elements.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

from_node(
    node: Node,
    document: Document,
    *,
    parent: Document | Heading | Element | None = None,
    child_factory: Callable[..., Element],
) -> Indent

Build one org_parser.element.Indent from a tree-sitter indent node.

The child_factory callable is responsible for dispatching each named body field child to the appropriate element constructor for the current parsing context. It must accept the positional arguments (node, document) and the keyword argument parent.

Parameters:

Name	Type	Description	Default
node	Node	A tree-sitter indent node.	required
document	Document	The owning org_parser.document.Document.	required
parent	Document | Heading | Element | None	Optional parent element to assign to the returned block.	None
child_factory	Callable[..., Element]	Callable with signature (child_node, document, *, parent) -> Element used to build each named body child.	required

Returns:

Type	Description
Indent	An org_parser.element.Indent whose body elements are built by
Indent	child_factory and whose source span is attached for clean
Indent	round-trip rendering.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark body and this block dirty for scratch-built rendering.

Keyword

Keyword(
    *,
    key: str,
    value: RichText | str,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Special keyword element, e.g. #+TITLE: Value.

Parameters:

Name	Type	Description	Default
key	str	Upper-cased keyword key.	required
value	RichText | str	Keyword value rich text.	required
parent	Document | Heading | Element | None	Optional parent owner object.	None

Example:

>>> from org_parser import loads
>>> document.keywords.append(Keyword.from_source("#+TITLE: Document"))
>>> print(str(document))
#+TITLE: Document

Methods:

Name	Description
__repr__	Return a developer-friendly representation.
__str__	Render keyword line.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Keyword from a tree-sitter special_keyword node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark value and this keyword dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
key	str	The upper-cased keyword key.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.
value	RichText	The mutable keyword value rich text.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

key property writable

key: str

The upper-cased keyword key.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

value property writable

value: RichText

The mutable keyword value rich text.

__repr__

__repr__() -> str

Return a developer-friendly representation.

__str__

__str__() -> str

Render keyword line.

Clean parse-backed instances preserve their verbatim source text. Dirty instances are rendered from semantic fields.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Keyword from a tree-sitter special_keyword node.

Parameters:

Name	Type	Description	Default
node	Node	The special_keyword tree-sitter node.	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) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark value and this keyword dirty for scratch-built rendering.

List

List(
    *,
    items: Sequence[ListItem] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Plain list element containing mutable org_parser.element.ListItem instances.

Example:

>>> from org_parser.element import ListItem
>>> from org_parser import loads
>>> document = loads('''
... - Item 0
... - Item 1
... ''')
>>> document.body[0][0].checkbox = "X"
>>> document.body[0][1].bullet = '+'
>>> print(str(document))
- [X] Item 0
+ Item 1

Methods:

Name	Description
__getitem__	Return one list item (or list-item slice).
__iter__	Iterate over list items.
__len__	Return number of list items.
__repr__	Return a tree-oriented representation for debugging.
__str__	Render list text preserving source while clean and parse-backed.
append_item	Append one list item with optional dirty propagation.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.List from a list node.
from_source	Parse source and return one strict semantic element.
insert_item	Insert one list item at index.
mark_dirty	Mark this list and all direct items as dirty.
reformat	Mark all items and this list dirty.
set_items	Set list items with optional dirty propagation.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
items	list[ListItem]	Mutable list items in source order.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

items property writable

items: list[ListItem]

Mutable list items in source order.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one list item (or list-item slice).

__iter__

__iter__() -> Iterator[ListItem]

Iterate over list items.

__len__

__len__() -> int

Return number of list items.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render list text preserving source while clean and parse-backed.

append_item

append_item(
    item: ListItem, *, mark_dirty: bool = True
) -> None

Append one list item with optional dirty propagation.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.List from a list node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

insert_item

insert_item(index: int, item: ListItem) -> None

Insert one list item at index.

mark_dirty

mark_dirty() -> None

Mark this list and all direct items as dirty.

reformat

reformat() -> None

Mark all items and this list dirty.

set_items

set_items(
    value: list[ListItem], *, mark_dirty: bool = True
) -> None

Set list items with optional dirty propagation.

ListItem

ListItem(
    *,
    bullet: str,
    ordered_counter: str | None = None,
    counter_set: str | None = None,
    checkbox: str | None = None,
    item_tag: RichText | str | None = None,
    first_line: RichText | str | None = None,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: Element

One mutable plain-list item with all item-level metadata.

Example:

>>> from org_parser.element import ListItem
>>> from org_parser.text import RichText
>>> from org_parser import loads
>>> document = loads("- Item 0\n")
>>> document.body[0].items.append(ListItem(bullet="-", first_line=RichText("Item 1")))
>>> document.body[0][0].checkbox = "X"
>>> document.body[0][1].bullet = '+'
>>> print(str(document))
- [X] Item 0
+ Item 1

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a tree-oriented representation for debugging.
__str__	Render list-item text from semantic fields when dirty.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create one org_parser.element.ListItem from a list_item parse node.
from_source	Parse source and return one strict org_parser.element.ListItem.
mark_dirty	Mark this element as dirty.
reformat	Mark all child content and this item dirty.

Attributes:

Name	Type	Description
body	list[Element]	Mutable body elements for this list item.
body_text	str	Stringified text of all list body elements.
bullet	str	Bullet marker (-, +, *, ., or )).
checkbox	str | None	Checkbox status character: " ", "X", "-", or None.
column	int | None	Zero-based source column of this element's parse node, or None.
counter_set	str | None	Counter-set cookie value without wrapper syntax.
dirty	bool	Whether this element has been mutated after creation.
first_line	RichText | None	First-line rich text after bullet metadata.
item_tag	RichText | None	Descriptive-list tag rich text before :: when present.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
ordered_counter	str | None	Ordered-list counter value for numeric/alpha bullets.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable body elements for this list item.

body_text property

body_text: str

Stringified text of all list body elements.

bullet property writable

bullet: str

Bullet marker (-, +, *, ., or )).

checkbox property writable

checkbox: str | None

Checkbox status character: " ", "X", "-", or None.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

counter_set property writable

counter_set: str | None

Counter-set cookie value without wrapper syntax.

dirty property

dirty: bool

Whether this element has been mutated after creation.

first_line property writable

first_line: RichText | None

First-line rich text after bullet metadata.

item_tag property writable

item_tag: RichText | None

Descriptive-list tag rich text before :: when present.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

ordered_counter property writable

ordered_counter: str | None

Ordered-list counter value for numeric/alpha bullets.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render list-item text from semantic fields when dirty.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create one org_parser.element.ListItem from a list_item parse node.

from_source classmethod

from_source(source: str) -> ListItem

Parse source and return one strict org_parser.element.ListItem.

The source must parse to exactly one list item wrapped by one plain list element and no other semantic nodes.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one list item.	required

Returns:

Type	Description
ListItem	Parsed org_parser.element.ListItem.

Raises:

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

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark all child content and this item dirty.

Logbook

Logbook(
    *,
    body: Sequence[Element] = (),
    clock_entries: Sequence[Clock] = (),
    repeats: Sequence[Repeat] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: Drawer

Specialized drawer for :LOGBOOK: entries.

Example:

>>> from org_parser.element import Logbook
>>> d = Logbook.from_source('''    ... :LOGBOOK:
... CLOCK: [2025-10-10]
... - State "DONE"       from "TODO"       <2025-10-10>
... :END:
... ''')
>>> d.name
'LOGBOOK'
>>> len(d.clock_entries)
1
>>> len(d.repeats)
1

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a tree-oriented representation for debugging.
__str__	Render drawer text preserving source text while clean.
append_to_body_without_dirty	Append one body element without changing this drawer's dirty state.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Logbook from logbook_drawer node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark all logbook children and this drawer dirty.

Attributes:

Name	Type	Description
body	list[Element]	Mutable list of drawer body elements.
body_text	str	Stringified text of all drawer body elements.
clock_entries	list[Clock]	Clock entries extracted from logbook body.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
name	str	Drawer name without surrounding colons.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
repeats	list[Repeat]	Repeated task entries extracted from list items in this logbook.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable list of drawer body elements.

body_text property

body_text: str

Stringified text of all drawer body elements.

clock_entries property writable

clock_entries: list[Clock]

Clock entries extracted from logbook body.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

name property writable

name: str

Drawer name without surrounding colons.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

repeats property writable

repeats: list[Repeat]

Repeated task entries extracted from list items in this logbook.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render drawer text preserving source text while clean.

append_to_body_without_dirty

append_to_body_without_dirty(element: Element) -> None

Append one body element without changing this drawer's dirty state.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Logbook from logbook_drawer node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark all logbook children and this drawer dirty.

Paragraph

Paragraph(
    *,
    body: RichText | str,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Paragraph element that stores parsed rich-text body content.

Parameters:

Name	Type	Description	Default
body	RichText | str	Parsed paragraph body rich text.	required
parent	Document | Heading | Element | None	Optional parent owner object.	None

Example:

>>> from org_parser.element import Paragraph
>>> paragraph = Paragraph.from_source("Paragraph text")
>>> paragraph.body_text
'Paragraph text'

Methods:

Name	Description
__repr__	Return a developer-friendly representation.
__str__	Render paragraph text.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Paragraph from a tree-sitter paragraph node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark body and this paragraph dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	RichText	Mutable rich-text body of this paragraph.
body_text	str	Stringified text of the paragraph body.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: RichText

Mutable rich-text body of this paragraph.

body_text property

body_text: str

Stringified text of the paragraph body.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a developer-friendly representation.

__str__

__str__() -> str

Render paragraph text.

Clean parse-backed instances preserve their verbatim source text. Dirty instances are rendered from semantic body text.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Paragraph from a tree-sitter paragraph node.

Parameters:

Name	Type	Description	Default
node	Node	The paragraph tree-sitter node.	required
document	Document	The owning org_parser.document.Document, or None for programmatic construction (source defaults to b"").	required
parent	Document | Heading | Element | None	Optional parent owner object.	None

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark body and this paragraph dirty for scratch-built rendering.

PlotKeyword

PlotKeyword(
    *,
    value: str | None,
    parent: Document | Heading | Element | None = None,
)

Bases: AffiliatedKeyword

A #+PLOT: affiliated keyword line.

Carries gnuplot configuration for the table immediately following it.

Parameters:

Name	Type	Description	Default
value	str | None	The plot configuration string, or None.	required

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the keyword line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.PlotKeyword from a plot_keyword node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.
value	str | None	Optional plain-text value following the keyword, or None.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

value property writable

value: str | None

Optional plain-text value following the keyword, or None.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the keyword line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.PlotKeyword from a plot_keyword node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

Properties

Properties(
    *,
    properties: Mapping[str, PropertyValue] | None = None,
    parent: Document | Heading | Element | None = None,
)

Bases: Element, MutableMapping[str, PropertyValue]

Property drawer element with dictionary-like mutable access.

Example:

>>> from org_parser.element import Properties
>>> d = Properties.from_source('''    ... :PROPERTIES:
... :key: Value
... :END:
... ''')
>>> d.name
'PROPERTIES'
>>> d["key"]
'Value

Methods:

Name	Description
__delitem__	Delete one property key.
__getitem__	Return the stored value for one property key.
__iter__	Iterate over property keys in insertion order.
__len__	Return number of stored properties.
__repr__	Return a tree-oriented representation for debugging.
__setitem__	Set one property value.
__str__	Render property drawer preserving source text while clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Properties from property_drawer node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark rich-text values and this drawer dirty.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__delitem__

__delitem__(key: str) -> None

Delete one property key.

__getitem__

__getitem__(key: str) -> PropertyValue

Return the stored value for one property key.

__iter__

__iter__() -> Iterator[str]

Iterate over property keys in insertion order.

__len__

__len__() -> int

Return number of stored properties.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__setitem__

__setitem__(key: str, value: PropertyValue) -> None

Set one property value.

__str__

__str__() -> str

Render property drawer preserving source text while clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Properties from property_drawer node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark rich-text values and this drawer dirty.

QuoteBlock

QuoteBlock(
    *,
    parameters: str | None = None,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: _ContainerBlock

#+begin_quote block with mutable nested element contents.

Example:

>>> from org_parser.element import QuoteBlock
>>> b = QuoteBlock.from_source('''\
... #+begin_quote :left
... content
... #+end_quote
... ''')
>>> b.parameters
':left'
>>> b.body_text
'content\n'

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.QuoteBlock from a quote_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark contents and this block dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Mutable block contents as semantic elements.
body_text	str	Stringified text of all nested block body elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parameters	str | None	Optional trailing parameters from the begin line.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable block contents as semantic elements.

body_text property

body_text: str

Stringified text of all nested block body elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parameters property writable

parameters: str | None

Optional trailing parameters from the begin line.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.QuoteBlock from a quote_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark contents and this block dirty for scratch-built rendering.

Repeat

Repeat(
    *,
    after: str | None,
    before: str | None,
    timestamp: Timestamp,
    body: Sequence[Element] = (),
    bullet: str = "-",
    ordered_counter: str | None = None,
    counter_set: str | None = None,
    item_tag: RichText | str | None = None,
    first_line: RichText | str | None = None,
    checkbox: str | None = None,
    parent: Document | Heading | Element | None = None,
)

Bases: ListItem

Repeated-task logbook entry represented as a specialized list item.

Example:

>>> from org_parser import loads
>>> from org_parser.element import Repeat
>>> from org_parser.time import Timestamp
>>> heading = loads("* TODO Heading 1").children[0]
>>> ts = Timestamp.from_source("<2025-10-10>")
>>> heading.add_repeat(Repeat(after="DONE", before="TODO", timestamp=ts))
>>> print(str(heading))
* TODO Heading 1
:LOGBOOK:
- State "DONE"       from "TODO"       <2025-10-10>
:END:

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a tree-oriented representation for debugging.
__str__	Render repeat entry preserving source text while clean.
attach_document	Attach owning document reference without changing dirty state.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_list_item	Build a org_parser.element.Repeat from one list item when pattern-matched.
from_node	Create one org_parser.element.ListItem from a list_item parse node.
from_source	Parse source as one list item and convert to org_parser.element.Repeat.
mark_dirty	Mark this element as dirty.
reformat	Mark timestamp, any child content, and this entry dirty.

Attributes:

Name	Type	Description
after	str | None	Task state after the repeat transition.
before	str | None	Task state before the repeat transition.
body	list[Element]	Mutable body elements for this list item.
body_text	str	Stringified text of all list body elements.
bullet	str	Bullet marker (-, +, *, ., or )).
checkbox	str | None	Checkbox status character: " ", "X", "-", or None.
column	int | None	Zero-based source column of this element's parse node, or None.
counter_set	str | None	Counter-set cookie value without wrapper syntax.
dirty	bool	Whether this element has been mutated after creation.
first_line	RichText | None	First-line rich text after bullet metadata.
is_completed	bool	Whether this repeat transition moved into a done TODO state.
item_tag	RichText | None	Descriptive-list tag rich text before :: when present.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
ordered_counter	str | None	Ordered-list counter value for numeric/alpha bullets.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.
timestamp	Timestamp	Timestamp recorded for the repeat transition.

after property writable

after: str | None

Task state after the repeat transition.

before property writable

before: str | None

Task state before the repeat transition.

body property writable

body: list[Element]

Mutable body elements for this list item.

body_text property

body_text: str

Stringified text of all list body elements.

bullet property writable

bullet: str

Bullet marker (-, +, *, ., or )).

checkbox property writable

checkbox: str | None

Checkbox status character: " ", "X", "-", or None.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

counter_set property writable

counter_set: str | None

Counter-set cookie value without wrapper syntax.

dirty property

dirty: bool

Whether this element has been mutated after creation.

first_line property writable

first_line: RichText | None

First-line rich text after bullet metadata.

is_completed property

is_completed: bool

Whether this repeat transition moved into a done TODO state.

item_tag property writable

item_tag: RichText | None

Descriptive-list tag rich text before :: when present.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

ordered_counter property writable

ordered_counter: str | None

Ordered-list counter value for numeric/alpha bullets.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

timestamp property writable

timestamp: Timestamp

Timestamp recorded for the repeat transition.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render repeat entry preserving source text while clean.

attach_document

attach_document(value: Document | None) -> None

Attach owning document reference without changing dirty state.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_list_item classmethod

from_list_item(
    item: ListItem, document: Document
) -> Repeat | None

Build a org_parser.element.Repeat from one list item when pattern-matched.

from_node classmethod

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

Create one org_parser.element.ListItem from a list_item parse node.

from_source classmethod

from_source(source: str) -> Repeat | None

Parse source as one list item and convert to org_parser.element.Repeat.

This follows the same behavior as calling Repeat.from_list_item(ListItem.from_source(source), document).

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one list item.	required

Returns:

Type	Description
Repeat | None	Parsed org_parser.element.Repeat when the item matches repeat
Repeat | None	syntax, otherwise None.

Raises:

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

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark timestamp, any child content, and this entry dirty.

ResultsKeyword

ResultsKeyword(
    *,
    value: str | None,
    parent: Document | Heading | Element | None = None,
)

Bases: AffiliatedKeyword

A #+RESULTS: affiliated keyword line.

Marks the block immediately following it as the results of a source block evaluation.

Parameters:

Name	Type	Description	Default
value	str | None	Optional trailing text on the results line, or None.	required

.. note:: The #+RESULTS[hash]: hash annotation defined in the Org Mode specification is not yet implemented in the underlying tree-sitter grammar. Inputs containing [hash] currently produce an ERROR parse node; the hash therefore cannot be exposed here until grammar support is added.

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the keyword line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.ResultsKeyword from a results_keyword node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.
value	str | None	Optional plain-text value following the keyword, or None.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

value property writable

value: str | None

Optional plain-text value following the keyword, or None.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the keyword line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.ResultsKeyword from a results_keyword node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

SourceBlock

SourceBlock(
    *,
    language: str | None = None,
    switches: str | None = None,
    body: str,
    parent: Document | Heading | Element | None = None,
)

Bases: _TextBlock

#+begin_src block with mutable source text contents.

Example:

>>> from org_parser.element import SourceBlock
>>> b = SourceBlock.from_source('''\
... #+begin_src  python :export stdout
... print("Hello world!")
... #+end_src
... ''')
>>> b.body
'# print("Hello world!")\n'
>>> b.switches
':export stdout'
>>> b.language
'python'

Methods:

Name	Description
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.SourceBlock from a src_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	str	Mutable block contents text without delimiters.
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
language	str | None	Optional source language from begin line.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
switches	str | None	Optional source block switches from begin line.
text	str	Stringified text representation of this element.

body property writable

body: str

Mutable block contents text without delimiters.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

language property writable

language: str | None

Optional source language from begin line.

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

switches property writable

switches: str | None

Optional source block switches from begin line.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.SourceBlock from a src_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

SpecialBlock

SpecialBlock(
    *,
    name: str,
    parameters: str | None = None,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: _ContainerBlock

#+begin_<name> block with mutable nested element contents.

Example:

>>> from org_parser.element import SpecialBlock
>>> b = SpecialBlock.from_source('''\
... #+begin_NOTE :notes
... content
... #+end_NOTE
... ''')
>>> b.name
'NOTE'
>>> b.parameters
':notes'
>>> b.body_text
'content\n'

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.SpecialBlock from a special_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark contents and this block dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Mutable block contents as semantic elements.
body_text	str	Stringified text of all nested block body elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
name	str	Special block name (the <name> in #+begin_<name>).
parameters	str | None	Optional trailing parameters from the begin line.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable block contents as semantic elements.

body_text property

body_text: str

Stringified text of all nested block body elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

name property writable

name: str

Special block name (the <name> in #+begin_<name>).

parameters property writable

parameters: str | None

Optional trailing parameters from the begin line.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.SpecialBlock from a special_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark contents and this block dirty for scratch-built rendering.

Table

Table(
    *,
    rows: list[TableRow | TableRuleRow],
    formulas: Sequence[str] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Org table semantic element.

Parameters:

Name	Type	Description	Default
rows	list[TableRow | TableRuleRow]	Mutable table rows (data rows and rule rows).	required
formulas	Sequence[str]	Table formulas without #+TBLFM: prefix.	()
parent	Document | Heading | Element | None	Optional parent owner object.	None

Example:

>>> from org_parser import loads
>>> document = loads('''
... | 1 | 2 |
... | 3 | 4 |
... ''')
>>> document.body[0][1][1] = 5
>>> print(str(document))
| 1 | 2 |
| 3 | 5 |

Methods:

Name	Description
__getitem__	Return one table row (or row slice).
__iter__	Iterate over table rows.
__len__	Return number of rows in this table.
__repr__	Return a tree-oriented representation for debugging.
__setitem__	Replace one table row.
__str__	Render table.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.Table from an org_table node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
formulas	list[str]	Mutable table formulas without #+TBLFM: prefix.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
rows	list[TableRow | TableRuleRow]	Mutable table rows (data rows and rule rows).
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

formulas property writable

formulas: list[str]

Mutable table formulas without #+TBLFM: prefix.

Example:

>>> from org_parser import loads
>>> document = loads('''
... | 1 | 2 |
... | 3 | 4 |
... #+TBLFM: @1$1=5
... ''')
>>> document.body[0].formulas
['@1$1=5']

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

rows property writable

rows: list[TableRow | TableRuleRow]

Mutable table rows (data rows and rule rows).

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one table row (or row slice).

__iter__

__iter__() -> Iterator[TableRow | TableRuleRow]

Iterate over table rows.

__len__

__len__() -> int

Return number of rows in this table.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__setitem__

__setitem__(
    index: int, value: TableRow | TableRuleRow
) -> None

Replace one table row.

__str__

__str__() -> str

Render table.

Clean parse-backed tables preserve original source text. Dirty tables are always rendered as aligned Org tables.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.Table from an org_table node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

TableEl

TableEl(
    *, parent: Document | Heading | Element | None = None
)

Bases: Element

Opaque Table.el grid semantic element.

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the original Table.el grid text.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.TableEl from a tableel_table node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the original Table.el grid text.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.TableEl from a tableel_table node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

TblnameKeyword

TblnameKeyword(
    *,
    value: str | None,
    parent: Document | Heading | Element | None = None,
)

Bases: AffiliatedKeyword

A #+TBLNAME: affiliated keyword line.

Assigns a name to the table immediately following it, allowing other parts of the document to refer to it by name.

Parameters:

Name	Type	Description	Default
value	str | None	The table name, or None when the keyword has no value.	required

Methods:

Name	Description
__repr__	Return a tree-oriented representation for debugging.
__str__	Render the keyword line, preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.TblnameKeyword from a tblname_keyword node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark this element dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body_text	str	Stringified body text for elements that implement body content.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.
value	str | None	Optional plain-text value following the keyword, or None.

body_text property

body_text: str

Stringified body text for elements that implement body content.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

value property writable

value: str | None

Optional plain-text value following the keyword, or None.

__repr__

__repr__() -> str

Return a tree-oriented representation for debugging.

__str__

__str__() -> str

Render the keyword line, preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.TblnameKeyword from a tblname_keyword node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark this element dirty for scratch-built rendering.

VerseBlock

VerseBlock(
    *,
    body: Sequence[Element] = (),
    parent: Document | Heading | Element | None = None,
)

Bases: _ContainerBlock

#+begin_verse block with mutable nested element contents.

Example:

>>> from org_parser.element import VerseBlock
>>> b = VerseBlock.from_source('''\
... #+begin_verse
... content
... #+end_verse
... ''')
>>> b.body_text
'content\n'

Methods:

Name	Description
__getitem__	Return one body element (or body slice).
__iter__	Iterate over body elements.
__len__	Return number of body elements.
__repr__	Return a semantic representation for debugging.
__str__	Render block text preserving source while parse-backed and clean.
attach_keyword	Attach an affiliated keyword to this element without marking it dirty.
attach_source	Attach parse-tree source backing to this element.
from_node	Create a org_parser.element.VerseBlock from a verse_block node.
from_source	Parse source and return one strict semantic element.
mark_dirty	Mark this element as dirty.
reformat	Mark contents and this block dirty for scratch-built rendering.

Attributes:

Name	Type	Description
body	list[Element]	Mutable block contents as semantic elements.
body_text	str	Stringified text of all nested block body elements.
column	int | None	Zero-based source column of this element's parse node, or None.
dirty	bool	Whether this element has been mutated after creation.
keywords	list[AffiliatedKeyword]	Affiliated keywords attached to this element, in document order.
line	int | None	Zero-based source line of this element's parse node, or None.
parent	Document | Heading | Element | None	Parent object that contains this element, if any.
text	str	Stringified text representation of this element.

body property writable

body: list[Element]

Mutable block contents as semantic elements.

body_text property

body_text: str

Stringified text of all nested block body elements.

column property

column: int | None

Zero-based source column of this element's parse node, or None.

dirty property

dirty: bool

Whether this element has been mutated after creation.

keywords property

keywords: list[AffiliatedKeyword]

Affiliated keywords attached to this element, in document order.

Affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) that immediately precede this element in the document body are linked here during parsing. The list is empty when no affiliated keywords precede this element.

The keywords remain as independent elements in the containing body list and are not duplicated in the serialised output of this element.

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads('''
... #+CAPTION: Some Table
... |table|
... ''')
>>> document.body[0].keywords[0].value
'Some Table'

line property

line: int | None

Zero-based source line of this element's parse node, or None.

parent property writable

parent: Document | Heading | Element | None

Parent object that contains this element, if any.

text property

text: str

Stringified text representation of this element.

__getitem__

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

Return one body element (or body slice).

__iter__

__iter__() -> Iterator[Element]

Iterate over body elements.

__len__

__len__() -> int

Return number of body elements.

__repr__

__repr__() -> str

Return a semantic representation for debugging.

__str__

__str__() -> str

Render block text preserving source while parse-backed and clean.

attach_keyword

attach_keyword(keyword: AffiliatedKeyword) -> None

Attach an affiliated keyword to this element without marking it dirty.

This method is called during body post-processing to link affiliated keywords (#+CAPTION:, #+TBLNAME:, #+PLOT:, #+RESULTS:) to the element that immediately follows them. The keyword is appended to org_parser.element.Element.keywords in document order.

Parameters:

Name	Type	Description	Default
keyword	AffiliatedKeyword	The affiliated keyword to attach.	required

Example:

>>> from org_parser.element import CaptionKeyword
>>> document = loads("|table|")
>>> c = CaptionKeyword.from_source("#+CAPTION: Some table")
>>> document.body[0].attach_keyword(c)
>>> len(document.body[0].keywords)
1
>>> print(str(document))

>>> document.body = [c, document.body[0]]
>>> print(str(document))
#+CAPTION: Some table
|table|

attach_source

attach_source(
    node: Node, document: Document | None
) -> None

Attach parse-tree source backing to this element.

This method is for internal factory use — call it immediately after construction to wire up the parse-tree node and owning document.

Parameters:

Name	Type	Description	Default
node	Node	The tree-sitter node this element was built from.	required
document	Document | None	The owning org_parser.document.Document, or None.	required

from_node classmethod

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

Create a org_parser.element.VerseBlock from a verse_block node.

from_source classmethod

from_source(source: str) -> _ElementT

Parse source and return one strict semantic element.

The source must parse to exactly one non-heading semantic element.

Parameters:

Name	Type	Description	Default
source	str	Org source text containing exactly one element.	required

Returns:

Type	Description
_ElementT	The parsed semantic element instance.

Raises:

Type	Description
ValueError	If parsing fails or structure is not exactly one element.
TypeError	If the parsed element does not match cls.

mark_dirty

mark_dirty() -> None

Mark this element as dirty.

reformat

reformat() -> None

Mark contents and this block dirty for scratch-built rendering.

DirtyList

DirtyList(
    values: Iterable[_ItemT] = (),
    *,
    on_mutation: Callable[[DirtyList[_ItemT]], None]
    | None = None,
)

Bases: list[_ItemT]

List that invokes a callback after each in-place mutation.