Welcome to pyorg’s documentation!

pyorg is a Python library for working with Org mode files and interacting with Org mode through Emacs itself.

This project, and especially the documentation, are a work in progress.

Installation

Emacs dependencies

pyorg requires the org-json package be installed in Emacs in order to be able to extract syntax trees from files.

Installing the package

Just clone the repository and run the setup script:

git clone https://github.com/jlumpe/pyorg
cd pyorg
python setup.py install

Quickstart

Getting the data from Emacs to Python

Create the following example file in Emacs:

#+title: Example file


* Header 1
Section 1

** Header 2
Section 2

*** Header 3
Section 3

**** Header 4
Section 4


* Markup
A paragraph with *bold*, /italic/, _underline_, +strike+, =verbatim=, and ~code~
objects.


* TODO [#A] A headline with a TODO and tags                       :tag1:tag2:
DEADLINE: <2019-06-29 Sat>

Use the org-json-export-buffer command to export it as example.json. Now, read the JSON file with pyorg:

import json
from pyorg.io import org_node_from_json

with open('example.json') as f:
   data = json.load(f)

doc = org_node_from_json(data)

Explore the AST structure

doc is an OrgNode which is the root node of the AST:

>>> doc
OrgOutlineNode(type='org-data')

Its has the type org-data, which is always the root node of the buffer. Its contents are a section node and some more headline nodes:

>>> doc.contents
[OrgNode(type='section'),
 OrgOutlineNode(type='headline'),
 OrgOutlineNode(type='headline'),
 OrgOutlineNode(type='headline')]

We can print a simple representation of the outline tree with the dump_outline() method:

>>> doc.dump_outline()
Example file
  0. Header 1
    0. Header 2
      0. Header 3
        0. Header 4
  1. Markup
  2. A headline with a TODO and tags

Get the 2nd headline (3rd item in root node’s contents) and print the full AST subtree, along with each node’s properties:

>>> hl2 = doc[2]
>>> hl2.dump(properties=True)
headline
  :archivedp       = False
  :commentedp      = False
  :footnote-section-p = False
  :level           = 1
  :post-affiliated = 120
  :post-blank      = 2
  :pre-blank       = 0
  :priority        = None
  :raw-value       = 'Markup'
  :tags            = []
  :title           = ['Markup']
  :todo-keyword    = None
  :todo-type       = None
  0 section
    :post-affiliated = 129
    :post-blank      = 2
    0 paragraph
      :post-affiliated = 129
      :post-blank      = 0
      0 'A paragraph with '
      1 bold
        :post-blank      = 0
        0 'bold'
      2 ', '
      3 italic
        :post-blank      = 0
        0 'italic'
      4 ', '
      5 underline
        :post-blank      = 0
        0 'underline'
      6 ', '
      7 strike-through
        :post-blank      = 0
        0 'strike'
      8 ', '
      9 verbatim
        :post-blank      = 0
        :value           = 'verbatim'
      10 ', and '
      11 code
        :post-blank      = 0
        :value           = 'code'
      12 '\nobjects.\n'

Check third headline’s properties to get the TODO information and tags:

>>> hl3 = doc[3]
>>> hl3.props
{'title': ['A headline with a TODO and tags'],
 'deadline': OrgTimestampNode(type='timestamp'),
 'post-affiliated': 301,
 'commentedp': False,
 'archivedp': False,
 'footnote-section-p': False,
 'post-blank': 0,
 'todo-type': 'todo',
 'todo-keyword': 'TODO',
 'tags': ['tag1', 'tag2'],
 'priority': 65,
 'level': 1,
 'pre-blank': 0,
 'raw-value': 'A headline with a TODO and tags'}

Org file structure

Nodes

See OrgNodeType, OrgNode.

Outline structure

See OrgOutlineNode.

Additional specialized node types

OrgTimestampNode, OrgTableNode

Reading in Org file data

The main function of this package is to read in Org mode documents as Abstract Syntax Trees (ASTs) where they can be processed and converted/exported into other formats. See the documentation for the org element API for more information about the AST structure.

Reading from JSON export

Rather attempting to parse .org files directly, pyorg is designed to work with the output of the org-json Emacs package. This simply converts the AST generated by the org package itself into machine-readable JSON format. This has the advantage of also including all of your personal Org mode setting and customization in Emacs (such as link abbreviations).

Parsing Org files directly

pyorg has very limited capability to parse .org files without the help of Emacs. See the pyorg.parse module.

Interfacing directly with Org mode

High-level interface to Org mode

pyorg.interface.Org

Communicating with Emacs

Emacs interface

pyorg.emacs.Emacs

Representing elisp code in Python

pyorg.elisp

Converting org file data to other formats

Plain text

pyorg.convert.plaintext.to_plaintext()

Creating your own converters

Subclass pyorg.convert.base.OrgConverterBase.

The agenda

Support for the agenda is a work in progress. See pyorg.agenda.

pyorg

pyorg package

Subpackages

pyorg.convert package
Subpackages
pyorg.convert.html package
Submodules
pyorg.convert.html.converter module
class pyorg.convert.html.converter.OrgHtmlConverter(config=None, **kw)[source]

Bases: pyorg.convert.base.OrgConverterBase

DEFAULT_CONFIG = {'date_format': '%Y-%m-%d %a', 'image_extensions': ('.png', '.jpg', '.gif', '.tiff'), 'latex_delims': ('$$', '$$'), 'latex_inline_delims': ('\\(', '\\)'), 'resolve_link': {}}
INLINE_NODES = frozenset({'example-block', 'target', 'link', 'latex-fragment', 'verbatim', 'subscript', 'paragraph', 'italic', 'underline', 'inline-babel-call', 'inline-src-block', 'statistics-cookie', 'code', 'superscript', 'fixed-width', 'timestamp', 'entity', 'export-snippet', 'line-break', 'macro', 'bold', 'radio-target', 'footnote-reference', 'table-cell', 'strike-through'})
TAGS = {'babel-call': None, 'bold': 'strong', 'center-block': 'div', 'code': 'code', 'comment': None, 'example-block': 'pre', 'fixed-width': 'pre', 'headline': 'article', 'horizontal-rule': 'hr', 'italic': 'em', 'item': 'li', 'link': 'a', 'org-data': 'article', 'paragraph': 'p', 'property-drawer': None, 'quote-block': 'blockquote', 'radio-target': 'span', 'section': 'section', 'statistics-cookie': 'span', 'strike-through': 's', 'subscript': 'sub', 'superscript': 'sup', 'timestamp': 'span', 'underline': 'u', 'verbatim': 'span', 'verse-block': 'p'}
convert(node, dom=False, **kwargs)[source]

Convert org node to HTML.

Parameters:
  • node (pyorg.ast.OrgNode) – Org node to convert.
  • dom (bool) – Return HTML element instead of string.
Returns:
Return type:

str or HtmlElement
default_classes(type)[source]
default_tag(type_)[source]
make_headline_text(node, ctx=None, dom=False)[source]

Make HTML element for text content of headline node.

Resolve link into a proper URL.

pyorg.convert.html.converter.to_html(node, dom=False, **kwargs)[source]

Convert org node to HTML.

Parameters:
Returns:
Return type:

str or HtmlElement
pyorg.convert.html.element module
class pyorg.convert.html.element.HtmlElement(tag, children=None, attrs=None, inline=False, post_ws=False)[source]

Bases: object

Lightweight class to represent an HTML element.

tag

HTML tag name (minus angle brackets).

Type:str
children

List of child elements (HtmlElement or strings).

Type:list
attrs

Mapping from attributes names (strings) to values (strings or bools).

Type:dict
inline

Whether to render children in an inline context. If False each child will be rendered on its own line. If True whitespace will only be added before/after children according to the post_ws attribute of the child.

Type:bool
classes

List of class names present in the “class” attribute. Assignable property.

Type:list
post_ws

Whether to add whitespace after the tag when rendering in an inline context.

Type:bool
add_class(classes)[source]
classes
class pyorg.convert.html.element.TextNode(text, post_ws=False)[source]

Bases: object

Text node to be used within HTML.

text

Wrapped text.

Type:str
post_ws

Whether to add whitespace after the tag when rendering in an inline context.

Type:bool
pyorg.convert.html.element.html_to_string(elem, **kwargs)[source]
pyorg.convert.html.element.write_html(stream, elem, indent='\t', inline=False)[source]
Module contents

Export org mode AST nodes to HTML.

Submodules
pyorg.convert.base module
class pyorg.convert.base.OrgConverterBase(config=None, **kw)[source]

Bases: object

Abstract base class for objects which convert org mode AST to another format.

config
Type:dict
DEFAULT_CONFIG = {'date_format': '%Y-%m-%d %a', 'image_extensions': ('.png', '.jpg', '.gif', '.tiff')}
convert(node, **kwargs)[source]
pyorg.convert.json module

Convert org mode AST nodes to JSON.

class pyorg.convert.json.OrgJsonConverter(config=None, **kw)[source]

Bases: pyorg.convert.base.OrgConverterBase

DEFAULT_CONFIG = {'date_format': '%Y-%m-%d %a', 'image_extensions': ('.png', '.jpg', '.gif', '.tiff'), 'include_agenda_extra': True, 'include_agenda_headline': True, 'object_type_key': '$$data_type'}
make_object(type_, data)[source]
pyorg.convert.json.to_json(node, **kwargs)[source]
pyorg.convert.plaintext module
class pyorg.convert.plaintext.OrgPlaintextConverter(config=None, **kw)[source]

Bases: pyorg.convert.base.OrgConverterBase

convert_multi(items, blanks=False, sep=None)[source]
pyorg.convert.plaintext.to_plaintext(arg, blanks=False, sep=None, **kwargs)[source]
Module contents

Convert org AST to other formats.

pyorg.elisp package
Submodules
pyorg.elisp.ast module

Base classes for Emacs Lisp abstract syntax trees.

class pyorg.elisp.ast.ElispAstNode[source]

Bases: object

Abstract base class for Elisp AST nodes.

class pyorg.elisp.ast.Form[source]

Bases: pyorg.elisp.ast.ElispAstNode

Pretty much everything is a form, right?

class pyorg.elisp.ast.Literal(pyvalue)[source]

Bases: pyorg.elisp.ast.Form

Basic self-evaluating forms like strings, numbers, etc.

PY_TYPES = (<class 'str'>, <class 'int'>, <class 'float'>)
class pyorg.elisp.ast.Symbol(name)[source]

Bases: pyorg.elisp.ast.Form

Elisp symbol.

isconst
class pyorg.elisp.ast.Cons(car, cdr)[source]

Bases: pyorg.elisp.ast.Form

A cons cell.

class pyorg.elisp.ast.List(items)[source]

Bases: pyorg.elisp.ast.Form

A list…

islist = False
class pyorg.elisp.ast.Quote(form)[source]

Bases: pyorg.elisp.ast.Form

A quoted Elisp form.

class pyorg.elisp.ast.Raw(src)[source]

Bases: pyorg.elisp.ast.ElispAstNode

Just raw code to be pasted in at this point.

pyorg.elisp.ast.to_elisp(value)[source]

Convert a Python value to an Elisp AST node.

pyorg.elisp.ast.make_list(items)[source]

Make an Elisp list from a Python sequence, first converting its elements to Elisp.

pyorg.elisp.ast.symbols(*names)[source]

Create a list of symbols.

pyorg.elisp.ast.quote(value)[source]

Quote value, converting Python strings to symbols.

pyorg.elisp.ast.cons(car, cds)[source]

Create a Cons cell, converting arguments.

pyorg.elisp.dsl module

A DSL for writing Elisp in Python.

God help us all.

pyorg.elisp.dsl.E

Singleton object which implements the DSL.

class pyorg.elisp.dsl.ElispSingleton[source]

Bases: object

Singleton object which implements the DSL.

static C(car, cds)

Create a Cons cell, converting arguments.

static Q(value)

Quote value, converting Python strings to symbols.

R

alias of pyorg.elisp.ast.Raw

static S(*names)

Create a list of symbols.

pyorg.elisp.printing module

Print Elisp AST to code.

pyorg.elisp.printing.print_elisp(node)[source]

Print an Elisp AST node.

pyorg.elisp.printing.print_elisp_string(string)[source]

Print string to Elisp, properly escaping it (maybe).

Module contents

Build and print Emacs Lisp abstract syntax trees in Python.

Submodules

pyorg.agenda module
class pyorg.agenda.OrgAgendaItem(text, **kwargs)[source]

Bases: object

An agenda item.

text

Main text of the item, as secondary string.

Type:list
text_plain

Text as simple string.

Type:str
type

TODO type.

Type:str
keyword

TODO keyword.

Type:str
headline

Headline node item came from.

Type:OrgAstNode
headline_path

Titles of headline and its ancestors.

Type:list
file

File todo is located in, relative to org-directory

Type:str
deadline

timestamp node

Type:OrgAstNode
priority

Priority letter assigned to the item’s headline.

Type:str
priority_code

Character code for priority.

Type:int
view_priority

Relative priority assigned to the item in the agenda buffer it was exported from.

Type:int
tags

List of tags.

Type:list
category
Type:str
extra

Extra data.

Type:dict
priority_code
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)[source]

Bases: pyorg.util.SingleDispatchBase

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

format_key(key)[source]
get_key(node)[source]

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

pyorg.ast.NODE_CLASSES = {'headline': <class 'pyorg.ast.OrgOutlineNode'>, 'org-data': <class 'pyorg.ast.OrgOutlineNode'>, '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.OrgNode(type_, props=None, contents=None, keywords=None, parent=None, outline=None)[source]

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
props

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
keywords

Dictionary of keyword values.

Type:dict
parent

Parent AST node.

Type:OrgNode
outline

Most recent outline node in the node’s ancestors (not including self).

Type:OrgOutlineNode
is_outline

Whether this node is an outline node.

Type:bool
children

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

dump(index=None, properties=False, indent=' ', _level=0)[source]

Print a debug representation of the node and its descendants.

is_outline = False
class pyorg.ast.OrgNodeType[source]

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_, *args, title=None, id=None, **kw)[source]

Bases: pyorg.ast.OrgNode

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
title

Title of outline node as plain text.

Type:str
id

Unique ID for TOC tree.

Type:str
section

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

Type:OrgNode
has_todo

Whether this outline has a TODO keyword.

Type:bool
priority_chr

Priority character if headline with priority, otherwise None.

Type:str
dump_outline()[source]

Print representation of node’s outline subtree.

has_todo
is_outline = True
outline_children

Iterable over child outline nodes.

outline_tree()[source]

Create a list of (child, child_tree) pairs.

priority_chr
class pyorg.ast.OrgTableNode(type_, props=None, contents=None, keywords=None, parent=None, outline=None)[source]

Bases: pyorg.ast.OrgNode

An org node with type “table”.

rows

List of standard rows.

Type:list of OrgNode
blocks()[source]

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

Returns:
Return type:list of list of OrgNode
cells()[source]
rows
class pyorg.ast.OrgTimestampNode(type_, *args, **kwargs)[source]

Bases: pyorg.ast.OrgNode

An org node with type “timestamp”.

begin

Begin date, parsed from properties

Type:datetime
end

End date, parsed from properties

Type:datetime
pyorg.ast.as_node_type(t)[source]

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

pyorg.ast.as_secondary_string(obj)[source]

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.assign_outline_ids(root, depth=3)[source]

Assign unique IDs to outline nodes.

pyorg.ast.dispatch_node_type(parent=None)[source]

Decorator to create DispatchNodeType instance from default implementation.

pyorg.ast.get_node_type(obj, name=False)[source]

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

pyorg.ast.node_cls(type_)[source]

Register a node class for a particular type in NODE_CLASSES.

pyorg.emacs module

Interface with Emacs and run commands.

class pyorg.emacs.Emacs(cmd=('emacs', '--batch'), client=False, verbose=1)[source]

Bases: object

Interface to Emacs program.

cmd

Base command to run Emacs.

Type:str or list[str]
is_client

Whether the command runs emacsclient.

Type:bool
verbose

1 to echo stderr of Emacs command, 2 to echo stdout. 0 turns off.

Type:int
Parameters:
  • cmd (list[str]) – Base command to run Emacs.
  • client (bool) – Whether the command runs emacsclient.
  • verbose (int) – 1 to echo stderr of Emacs command, 2 to echo stdout. 0 turns off.
eval(source, process=False, **kwargs)[source]

Evaluate ELisp source code and return output.

Parameters:
  • source (str or list) – Elisp code. If a list of strings will be enclosed in progn.
  • process (bool) – If True return the subprocess.CompletedProcess object, otherwise just return the value of stdout.
  • kwargs – Passed to run().
Returns:

Command output or completed process object, depending on value of process.
Return type:

str or subprocess.CompletedProcess
getoutput(args, **kwargs)[source]

Get output of command.

Parameters:
  • args (list[str]) – List of strings.
  • kwargs – Passed to run().
Returns:

Value of stdout.
Return type:

str
getresult(source, is_json=False, **kwargs)[source]

Get parsed result from evaluating the Elisp code.

Parameters:
  • source (str or list) – Elisp code to evaluate.
  • is_json (bool) – True if the result of evaluating the code is already a string of JSON-encoded data.
Returns:
Return type:

Parsed value.
run(args, check=True, verbose=None)[source]

Run the Emacs command with a list of arguments.

Parameters:
  • args (list[str]) – List of strings.
  • check (bool) – Check the return code is zero.
  • verbose (int or None) – Overrides verbose attribute if not None.
Returns:
Return type:

subprocess.CompletedProcess
Raises:

subprocess.CalledProcessError – If check=True and return code is nonzero.
exception pyorg.emacs.EmacsException(src, stdout=None, stderr=None)[source]

Bases: Exception

An exception that occurred when trying to evaluate Elisp code in an emacs process.

classmethod from_calledprocess(src, cpe)[source]
pyorg.emacs.get_form(src)[source]

Get Elisp form from string, AST node, or sequence of these.

pyorg.emacs.get_forms_list(src)[source]

Get source as list of forms from string, AST node, or sequence of these.

pyorg.interface module
class pyorg.interface.Org(emacs=None, orgdir=None)[source]

Bases: object

Interface to org mode.

emacs
Type:pyorg.emacs.Emacs
orgdir

Directory org files are read from.

Type:OrgDirectory
agenda(key='t', raw=False)[source]

TODO Read agenda information.

Parameters:key (str) – TODO
Returns:
Return type:list[dict]
open_org_file(path, focus=False)[source]

Open an org file in the org directory for editing in Emacs.

Parameters:
  • path (str or pathlib.Path) – File path relative to org directory.
  • focus (bool) – Switch window/input focus to opened buffer.
read_org_file(path, assign_ids=True)[source]

Read and parse an org file.

Parameters:
Returns:
Return type:

pyorg.ast.OrgNode
Raises:

FileNotFoundError
read_org_file_direct(path, raw=False)[source]

Read and parse an org file directly from Emacs.

Always reads the current file and does not use cached data, or perform any additional processing other than parsing.

Parameters:
  • path (str or pathlib.Path) – File path relative to org directory.
  • raw (bool) – Don’t parse and just return raw JSON exported from Emacs.
Returns:
Return type:

pyorg.ast.OrgNode or dict
Raises:

FileNotFoundError
class pyorg.interface.OrgDirectory(path)[source]

Bases: object

The directory where the user’s org files are kept.

path : pathlib.Path
Absolute path to org directory.
get_abs_path(path)[source]

Get absolute path from path relative to org directory.

Path will be normalized with “..” components removed.

Returns:
Return type:pathlib.Path
Raises:ValueError – If the path is not relative or is outside of the org directory (can happen if it contains “..” components).
list_files(path=None, recursive=False, hidden=False)[source]

List org files within the org directory.

Paths are relative to the org directory.

Parameters:
  • path (str or pathlib.Path) – Optional subdirectory to search through.
  • recursive (bool) – Recurse through subdirectories.
  • hidden (bool) – Include hidden files.
Returns:
Return type:

Iterator over pathlib.Path instances.
pyorg.io module

Read (and write) org mode data from JSON and other formats.

pyorg.io.agenda_item_from_json(data)[source]

Parse an agenda item from JSON data.

Parameters:data (dict) –
Returns:
Return type:OrgAgendaItem
pyorg.io.org_node_from_json(data)[source]

Parse an org AST node from JSON data.

Returns:
Return type:OrgNode
pyorg.parse module

(Partially) parse org files.

pyorg.parse.parse_tags(string)[source]

Parse tags from string.

Parameters:string (str) – Tags separated by colons.
Returns:List of tags.
Return type:list[str]
pyorg.parse.read_file_keywords(file)[source]

Read file-level keywords from an .org file (without using Emacs).

Limitations: only reads up to the first element in the initial section (excluding comments). If the initial section does contain such an element, any keywords directly preceding it (not separated with a blank line) will be considered affiliated keywords of that element and ignored.

Will not parse org markup in keyword values.

All keys are converted to uppercase.

Keys which appear more than once will have values in a list.

Parameters:file – String or open file object or stream in text mode.
Returns:
Return type:dict
pyorg.util module

Misc. utility code.

class pyorg.util.SingleDispatch(default, registry=None, doc=None)[source]

Bases: pyorg.util.SingleDispatchBase

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

iter_keys(arg)[source]
validate_key(key)[source]

Validate and possibly replace a key before an implementation is registered under it.

Default implementation simply returns the argument. Subclasses may wish to override this. An error should be raised for invalid keys.

Parameters:key – Key passed to register().
Returns:
Return type:Key to use for registration, which may be different than argument.
class pyorg.util.SingleDispatchBase(default, registry=None, doc=None)[source]

Bases: abc.ABC

ABC for a generic function which dispatches on some trait of its first argument.

May be bound to an object or class as a method.

Concrete subclasses must implement one of the get_key() or iter_keys() method.

default

Default implementation.

Type:callable
registry

Stores the specialized implementation functions by key.

Type:dict
bind(instance, owner=None)[source]

Get a version of the function bound to the given instance as a method.

Parameters:
  • instance – Object instance to bind to.
  • owner –
copy()[source]
dispatch(arg)[source]

Get the actual function implementation for the given argument.

get_key(arg)[source]

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

iter_keys(arg)[source]
register(key, impl=None)[source]

Register an implementation for the given key.

Parameters:
  • key – Key to register method under. May also be a list of keys.
  • impl (callable) – Implementation to register under the given key(s). If None will return a decorator function that completes the registration.
Returns:

None if method is given. Otherwise returns a decorator that will register the function it is applied to.
Return type:

function or None
validate_key(key)[source]

Validate and possibly replace a key before an implementation is registered under it.

Default implementation simply returns the argument. Subclasses may wish to override this. An error should be raised for invalid keys.

Parameters:key – Key passed to register().
Returns:
Return type:Key to use for registration, which may be different than argument.
class pyorg.util.SingleDispatchMethod(func, instance, owner=None)[source]

Bases: object

Version of a SingleDispatchBase which acts as a method.

func
Type:SingleDispatchBase
instance

Instance the function is bound to, or None.

owner
default
dispatch(arg)[source]

Module contents

Root package for pyorg.

Package for woring with Emacs org-mode files

Indices and tables