pyorg.ast module

Work with org file abstract syntax trees.

See https://orgmode.org/worg/dev/org-syntax.html for a description of the org syntax.

class pyorg.ast.DispatchNodeType(default, registry=None, doc=None)

Bases: pyorg.util.SingleDispatchBase

Generic function which dispatches on the node type of its first argument.

format_key(key)

get_key(node)

Get the key to look up the correct implementation for the given argument.

pyorg.ast.NODE_CLASSES = {'headline': <class 'pyorg.ast.OrgHeadlineNode'>, 'org-data': <class 'pyorg.ast.OrgDataNode'>, 'table': <class 'pyorg.ast.OrgTableNode'>, 'timestamp': <class 'pyorg.ast.OrgTimestampNode'>}

Mapping from org element/node types to their Python class

pyorg.ast.ORG_NODE_TYPES = {'babel-call': OrgNodeType('babel-call'), 'bold': OrgNodeType('bold'), 'center-block': OrgNodeType('center-block'), 'clock': OrgNodeType('clock'), 'code': OrgNodeType('code'), 'comment': OrgNodeType('comment'), 'comment-block': OrgNodeType('comment-block'), 'diary-sexp': OrgNodeType('diary-sexp'), 'drawer': OrgNodeType('drawer'), 'dynamic-block': OrgNodeType('dynamic-block'), 'entity': OrgNodeType('entity'), 'example-block': OrgNodeType('example-block'), 'export-block': OrgNodeType('export-block'), 'export-snippet': OrgNodeType('export-snippet'), 'fixed-width': OrgNodeType('fixed-width'), 'footnote-definition': OrgNodeType('footnote-definition'), 'footnote-reference': OrgNodeType('footnote-reference'), 'headline': OrgNodeType('headline'), 'horizontal-rule': OrgNodeType('horizontal-rule'), 'inline-babel-call': OrgNodeType('inline-babel-call'), 'inline-src-block': OrgNodeType('inline-src-block'), 'inlinetask': OrgNodeType('inlinetask'), 'italic': OrgNodeType('italic'), 'item': OrgNodeType('item'), 'keyword': OrgNodeType('keyword'), 'latex-environment': OrgNodeType('latex-environment'), 'latex-fragment': OrgNodeType('latex-fragment'), 'line-break': OrgNodeType('line-break'), 'link': OrgNodeType('link'), 'macro': OrgNodeType('macro'), 'node-property': OrgNodeType('node-property'), 'org-data': OrgNodeType('org-data'), 'paragraph': OrgNodeType('paragraph'), 'plain-list': OrgNodeType('plain-list'), 'planning': OrgNodeType('planning'), 'property-drawer': OrgNodeType('property-drawer'), 'quote-block': OrgNodeType('quote-block'), 'radio-target': OrgNodeType('radio-target'), 'section': OrgNodeType('section'), 'special-block': OrgNodeType('special-block'), 'src-block': OrgNodeType('src-block'), 'statistics-cookie': OrgNodeType('statistics-cookie'), 'strike-through': OrgNodeType('strike-through'), 'subscript': OrgNodeType('subscript'), 'superscript': OrgNodeType('superscript'), 'table': OrgNodeType('table'), 'table-cell': OrgNodeType('table-cell'), 'table-row': OrgNodeType('table-row'), 'target': OrgNodeType('target'), 'timestamp': OrgNodeType('timestamp'), 'underline': OrgNodeType('underline'), 'verbatim': OrgNodeType('verbatim'), 'verse-block': OrgNodeType('verse-block')}

Mapping from names of all AST node types to OrgNodeType instances.

class pyorg.ast.OrgDataNode(type_, *args, **kw)

Bases: pyorg.ast.OrgOutlineNode

Root node for an org mode parse tree.

Doesn’t do anything special, aside from being the outline node at level 0.

class pyorg.ast.OrgDocument(root, properties=None, meta=None)

Bases: object

Represents an entire Org mode document.

root

The root of the document’s Abstract Syntax Tree.

Type:OrgOutlineNode

properties

Additional file-level properties attached to the document, such as the author or date. Values may be strings or secondary strings.

Type:dict

meta

A dictionary containing arbitrary application-specific metadata.

Type:dict

assign_header_ids(depth=3)

Assign unique IDs to headers.

class pyorg.ast.OrgHeadlineNode(type_, *args, title=None, id=None, **kw)

Bases: pyorg.ast.OrgOutlineNode

Org header element.

title

Title of headline as plain text.

Type:str

id

Unique ID for TOC tree.

Type:str

has_todo

Whether this outline has a TODO keyword.

Type:bool

priority_chr

Priority character if headline with priority, otherwise None.

Type:str

scheduled

The timestamp in the “scheduled” property of the headline, if present.

Type:OrgTimestamp

deadline

The timestamp in the “deadline” property of the headline, if present.

Type:OrgTimestamp

closed

The timestamp in the “closed” property of the headline, if present.

Type:OrgTimestamp

closed

deadline

has_todo

priority_chr

scheduled

class pyorg.ast.OrgNode(type_, properties=None, contents=None, keywords=None, ref=None, meta=None)

Bases: object

A node in an org file abstract syntax tree.

Implements the sequence protocol as a sequence containing its child nodes (identically to contents). Also allows accessing property values by indexing with a string key.

type

Node type, obtained from org-element-type.

Type:OrgNodeType

properties

Dictionary of property values, obtained from org-element-property.

Type:dict

contents

List of contents (org nodes or strings), obtained from org-element-contents.

Type:list

ref

A unique ID assigned to the node during the export process.

Type:str

keywords

Dictionary of keyword values.

Type:dict

meta

A dictionary containing arbitrary application-specific metadata.

Type:dict

is_outline

Whether this node is an outline node.

Type:bool

children

Iterator over all child AST nodes (in contents or keyword/property values.

descendants(incself=False, properties=False)

Recursively iterate over all of the node’s descendants.

Parameters:

• incself (bool) – Include self.
• properties (bool) – Include children in the node’s properties, not just contents (see children).

Yields:

.OrgNode

dump(properties=False, indent=' ')

Print a debug representation of the node and its descendants.

Parameters:

• value (OrgNode) –
• properties (bool) – Also print node properties.
• indent (str) –
• to indent with. (Characters) –

is_outline = False

class pyorg.ast.OrgNodeType

Bases: pyorg.ast.OrgNodeType

The properties of an org AST node type.

name

The unique name of this node type.

Type:str

is_element

Whether this node type is an element. “An element defines syntactical parts that are at the same level as a paragraph, i.e. which cannot contain or be included in a paragraph.”

Type:bool

is_object

Whether this node type is an object. All nodes which are not elements are objects. “An object is a part that could be included in an element.”

Type:bool

is_greater_element

Whether this node type is a greater element. “Greater elements are all parts that can contain an element.”

Type:bool

is_recursive

Whether this node type is a recursive object.

Type:bool

is_object_container

Whether this node type is an object container, i.e. can directly contain objects.

Type:bool

References

Org Syntax

is_object

class pyorg.ast.OrgOutlineNode(type_, properties=None, contents=None, keywords=None, ref=None, meta=None)

Bases: pyorg.ast.OrgNode

Abstract base class for org node that is a component of the outline tree.

Corresponds to the root org-data node or a headline node.

level

Outline level. 0 corresponds to the root node of the file.

Type:int

section

Org node with type “section” that contains the outline node’s direct content (not part of any nested outline nodes).

Type:OrgNode

subheadings

List of nested headings.

Type:list

dump_outline(depth=None, indent=' ')

Print representation of node’s outline subtree.

Parameters:

• depth (int) – Maximum depth to print.
• indent (str) – String to indent with.

is_outline = True

outline_tree()

Create a list of (child, child_tree) pairs.

section

subheadings

class pyorg.ast.OrgTableNode(type_, properties=None, contents=None, keywords=None, ref=None, meta=None)

Bases: pyorg.ast.OrgNode

An org node with type “table”.

rows

List of standard rows.

Type:list of OrgNode

nrows

Number of (non-rule) rows in table. This includes the header.

Type:int

ncols

Number of columns in table.

Type:int

blocks()

Standard rows divided into “blocks”, which were separated by rule rows.

Returns: Return type:list of list of OrgNode

cells()

ncols

nrows

rows

class pyorg.ast.OrgTimestamp(tstype, start, end=None, repeater=None, warning=None)

Bases: object

Stores Org mode timestamp data, without the whole AST node.

tstype

Type:str

start

Type:datetime.datetime

end

Type:datetime.datetime

repeater

Type:OrgTimestampInterval

warning

Type:OrgTimestampInterval

interval

is_range

class pyorg.ast.OrgTimestampInterval(type_, unit, value)

Bases: object

An interval of time stored in an Org mode time stamp’s repeater or warning.

type

Type:str

unit

Type:str

value

Type:float

class pyorg.ast.OrgTimestampNode(type_, *args, **kwargs)

Bases: pyorg.ast.OrgNode, pyorg.ast.OrgTimestamp

An org node with type “timestamp”.

pyorg.ast.as_node_type(t)

Convert to node type object, looking up strings by name.

pyorg.ast.as_secondary_string(obj)

Convert argument to a “secondary string” (list of nodes or strings).

Parameters:obj (OrgNode or str or list) – Returns: Return type:list Raises:TypeError : if obj is not a str or OrgNode or iterable of these.

pyorg.ast.dispatch_node_type(parent=None)

Decorator to create DispatchNodeType instance from default implementation.

pyorg.ast.dump_ast(value, properties=False, indent=' ', _level=0)

Print a debug representation of an org AST node and its descendants.

Parameters:

• value (OrgNode) –
• properties (bool) – Also print node properties.
• indent (str) – Characters to indent with.

pyorg.ast.get_node_type(obj, name=False)

Get type of AST node, returning None for other Python types.

pyorg.ast.node_cls(type_)

Register a node class for a particular type in NODE_CLASSES.