API Reference

Parser functions

stage_left.parse_file(fp)

Parse a [x]it file

Parameters:: fp (IO) – File-like object containing a todo list in [x]it format
Return type:: List[Group]
Returns:: A list of group objects
Raises:: ParseError –

stage_left.parse_text(text)

Parse a [x]it string

Parameters:: text (str) – String containing a todo list in [x]it format
Return type:: List[Group]
Returns:: A list of group objects
Raises:: ParseError –

Exceptions

exception stage_left.ParseError

Data Types

class stage_left.types.State(value)

State of an Item

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#checkbox

OPEN = ' '

CHECKED = 'x'

ONGOING = '@'

OBSOLETE = '~'

IN_QUESTION = '?'

class stage_left.types.Tag(value='', key=None)

An annotation for categorising or filtering the data

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#tag

value: str = ''

key: Optional[str] = None

class stage_left.types.Item(state, description, tags=<factory>, priority=0, due_date=None)

An entry in a checklist or todo list

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#item

state: State

description: str

Meaning of the Item. The Item.description property stores the raw item text, but formatting options are available via Item.format_description().

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#description

tags: Set[Tag]

priority: int = 0

Int represation of the Item importance

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#priority

due_date: Optional[date] = None

Date object representing the item due date. Due dates specified using the numbered week syntax e.g: 2022-W01 are parsed assuming Monday is the first day of the week. All days in a new year preceding the first Monday are considered to be in week 0 (W00).

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#due-date

format_description(*, normalize_whitespace=False, with_priority=True, with_tags=True, with_due_date=True)

Output a formatted version of the item description.

Parameters:

normalize_whitespace (bool) – Remove duplicate whitespace from the output item description
with_priority (bool) – Include priority in the output item description
with_tags (bool) – Include tags in the output item description
with_due_date (bool) – Include due date in the output item description

Return type:

str

class stage_left.types.Group(title, items=<factory>)

A group of one or more Items

Ref:: https://github.com/jotaen/xit/blob/v1.1/Specification.md#group

title: Optional[str]

items: List[Item]