Time¶

This section documents clocking primitives and timestamps.

time ¶

Time-related semantic objects for Org content.

Classes:

Name	Description
`Timestamp`	Parsed Org timestamp with component-level fields.
`Clock`	Clock log line element.

Timestamp ¶

Timestamp(
    *,
    is_active: bool,
    start_year: int,
    start_month: int,
    start_day: int,
    start_dayname: str | None = None,
    start_hour: int | None = None,
    start_minute: int | None = None,
    end_year: int | None = None,
    end_month: int | None = None,
    end_day: int | None = None,
    end_dayname: str | None = None,
    end_hour: int | None = None,
    end_minute: int | None = None,
    repeater: Repeater | None = None,
    repeater_cap: Repeater | None = None,
    delay: Repeater | None = None,
    parent: Heading
    | Clock
    | Repeat
    | RichText
    | None = None,
)

Bases: InlineObject

Parsed Org timestamp with component-level fields.

All fields are mutable. Mutating any field marks the instance dirty; a dirty org_parser.time.Timestamp rebuilds its string representation from the component fields rather than returning the original raw source text.

Parameters:

Name	Type	Description	Default
`is_active`	`bool`	Whether the timestamp uses active delimiters (`<...>`).	required
`start_year`	`int`	Start year.	required
`start_month`	`int`	Start month (1-12).	required
`start_day`	`int`	Start day (1-31).	required
`start_dayname`	`str \| None`	Optional start day name token (e.g. `"Mon"`).	`None`
`start_hour`	`int \| None`	Optional start hour (0-23).	`None`
`start_minute`	`int \| None`	Optional start minute (0-59).	`None`
`end_year`	`int \| None`	Optional end year for ranges.	`None`
`end_month`	`int \| None`	Optional end month for ranges.	`None`
`end_day`	`int \| None`	Optional end day for ranges.	`None`
`end_dayname`	`str \| None`	Optional end day name token.	`None`
`end_hour`	`int \| None`	Optional end hour.	`None`
`end_minute`	`int \| None`	Optional end minute.	`None`
`repeater`	`Repeater \| None`	Optional repeater component.	`None`
`repeater_cap`	`Repeater \| None`	Optional repeater cap component.	`None`
`delay`	`Repeater \| None`	Optional warning delay component.	`None`

Example:

>>> from org_parser.time import Timestamp
>>> timestamp = Timestamp.from_source("<2026-03-29 Sun 10:00>")
>>> timestamp.start.year
2026

Initialize a mutable timestamp value.

Methods:

Name	Description
`__eq__`	Compare timestamps by semantic component fields only.
`__repr__`	Return a developer-friendly semantic representation.
`__str__`	Render the timestamp as an Org source string.
`from_datetime`	Create a timestamp from one Python `datetime` start value.
`from_node`	Create a org_parser.time.Timestamp from a tree-sitter timestamp-like node.
`from_source`	Parse source and return one strict org_parser.time.Timestamp.
`mark_dirty`	Mark this timestamp dirty and bubble to parent chain.
`reformat`	Mark this timestamp as dirty for scratch-built rendering.
`to_datetime`	Return this timestamp as `datetime.datetime` using `start`.

Attributes:

Name	Type	Description
`delay`	`Repeater \| None`	Delay component, if present.
`dirty`	`bool`	Whether this timestamp has been mutated since creation.
`end`	`datetime \| None`	Return the end value as `datetime.datetime`, if available.
`end_day`	`int \| None`	Optional end day for ranges.
`end_dayname`	`str \| None`	Optional end day-name token.
`end_hour`	`int \| None`	Optional end hour for ranges.
`end_minute`	`int \| None`	Optional end minute for ranges.
`end_month`	`int \| None`	Optional end month for ranges.
`end_year`	`int \| None`	Optional end year for ranges.
`is_active`	`bool`	Whether this timestamp uses active delimiters (`<...>`).
`parent`	`Heading \| Clock \| Repeat \| RichText \| None`	Parent object that owns this timestamp, if any.
`repeater`	`Repeater \| None`	Repeater component, if present.
`repeater_cap`	`Repeater \| None`	Repeater cap component, if present.
`start`	`datetime`	Return the start value as `datetime.datetime`.
`start_day`	`int`	Start day value.
`start_dayname`	`str \| None`	Optional start day-name token.
`start_hour`	`int \| None`	Optional start hour.
`start_minute`	`int \| None`	Optional start minute.
`start_month`	`int`	Start month value.
`start_year`	`int`	Start year value.

delay `property` `writable` ¶

delay: Repeater | None

Delay component, if present.

dirty `property` ¶

dirty: bool

Whether this timestamp has been mutated since creation.

end `property` ¶

end: datetime | None

Return the end value as datetime.datetime, if available.

Example:

>>> from org_parser.time import Timestamp
>>> timestamp = Timestamp.from_source("<2026-03-29 Sun 10:00-20:00>")
>>> timestamp.end is not None
True

end_day `property` `writable` ¶

end_day: int | None

Optional end day for ranges.

end_dayname `property` `writable` ¶

end_dayname: str | None

Optional end day-name token.

end_hour `property` `writable` ¶

end_hour: int | None

Optional end hour for ranges.

end_minute `property` `writable` ¶

end_minute: int | None

Optional end minute for ranges.

end_month `property` `writable` ¶

end_month: int | None

Optional end month for ranges.

end_year `property` `writable` ¶

end_year: int | None

Optional end year for ranges.

is_active `property` `writable` ¶

is_active: bool

Whether this timestamp uses active delimiters (<...>).

parent `property` `writable` ¶

parent: Heading | Clock | Repeat | RichText | None

Parent object that owns this timestamp, if any.

repeater `property` `writable` ¶

repeater: Repeater | None

Repeater component, if present.

repeater_cap `property` `writable` ¶

repeater_cap: Repeater | None

Repeater cap component, if present.

start `property` ¶

start: datetime

Return the start value as datetime.datetime.

Example:

>>> from org_parser.time import Timestamp
>>> timestamp = Timestamp.from_source("<2026-03-29 Sun 10:00>")
>>> timestamp.start.year
2026

start_day `property` `writable` ¶

start_day: int

Start day value.

start_dayname `property` `writable` ¶

start_dayname: str | None

Optional start day-name token.

start_hour `property` `writable` ¶

start_hour: int | None

Optional start hour.

start_minute `property` `writable` ¶

start_minute: int | None

Optional start minute.

start_month `property` `writable` ¶

start_month: int

Start month value.

start_year `property` `writable` ¶

start_year: int

Start year value.

eq ¶

__eq__(other: object) -> bool

Compare timestamps by semantic component fields only.

repr ¶

__repr__() -> str

Return a developer-friendly semantic representation.

str ¶

__str__() -> str

Render the timestamp as an Org source string.

Returns the original source text when clean. Once dirty, rebuilds the string from component fields.

from_datetime `classmethod` ¶

from_datetime(
    value: datetime, *, is_active: bool = True
) -> Timestamp

Create a timestamp from one Python datetime start value.

The datetime is mapped onto the timestamp start components. End, repeater, and delay components are left unset.

Parameters:

Name	Type	Description	Default
`value`	`datetime`	Source datetime for the timestamp start components.	required
`is_active`	`bool`	Whether to render the timestamp with active delimiters.	`True`

from_node `classmethod` ¶

from_node(node: Node, document: Document) -> Timestamp

Create a org_parser.time.Timestamp from a tree-sitter timestamp-like node.

from_source `classmethod` ¶

from_source(source: str) -> Timestamp

Parse source and return one strict org_parser.time.Timestamp.

The source must parse to a single inline timestamp object with no surrounding text.

Parameters:

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

Returns:

Type	Description
`Timestamp`	Parsed org_parser.time.Timestamp.

Raises:

Type	Description
`ValueError`	If parsing fails or the structure is not one timestamp.
`TypeError`	If the parsed inline object is not a timestamp.

mark_dirty ¶

mark_dirty() -> None

Mark this timestamp dirty and bubble to parent chain.

reformat ¶

reformat() -> None

Mark this timestamp as dirty for scratch-built rendering.

to_datetime ¶

to_datetime() -> datetime

Return this timestamp as datetime.datetime using start.

Example:

>>> from org_parser.time import Timestamp
>>> timestamp = Timestamp.from_source("<2026-03-29 Sun 10:00>")
>>> timestamp.to_datetime()
datetime.datetime(2026, 3, 29, 10, 0)

Clock ¶

Clock(
    *,
    timestamp: Timestamp | None = None,
    duration: str | None = None,
    parent: Document | Heading | Element | None = None,
)

Bases: Element

Clock log line element.

Parameters:

Name	Type	Description	Default
`timestamp`	`Timestamp \| None`	Parsed clock timestamp, if present.	`None`
`duration`	`str \| None`	Optional `H:MM` duration value.	`None`
`parent`	`Document \| Heading \| Element \| None`	Optional parent owner object.	`None`

Example:

>>> from org_parser.time import Clock, Timestamp
>>> clock = Clock(timestamp=Timestamp.from_source("<2026-03-29 Sun 10:00-11:00>"))
>>> clock.duration
'1:00'
>>> clock.timestamp.start.year
2026

Methods:

Name	Description
`__repr__`	Return a developer-friendly representation.
`__str__`	Render clock 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.time.Clock from a tree-sitter `clock` node.
`from_source`	Parse source and return one strict semantic element.
`mark_dirty`	Mark this element as dirty.
`reformat`	Mark timestamp and this clock 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.
`duration`	`str \| None`	Clock duration text in `H:MM` format, 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.
`parent`	`Document \| Heading \| Element \| None`	Parent object that contains this element, if any.
`text`	`str`	Stringified text representation of this element.
`timestamp`	`Timestamp \| None`	Clock timestamp value, when present.

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.

duration `property` `writable` ¶

duration: str | None

Clock duration text in H:MM format, when present.

Example:

>>> from org_parser.time import Clock, Timestamp
>>> clock = Clock(timestamp=Timestamp.from_source("[2026-03-29 Sun 10:00-11:00]"))
>>> clock.duration
'1:00'

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.

timestamp `property` `writable` ¶

timestamp: Timestamp | None

Clock timestamp value, when present.

Example:

>>> from org_parser.time import Clock, Timestamp
>>> clock = Clock(timestamp=Timestamp.from_source("[2026-03-29 Sun 10:00-11:00]"))
>>> clock.timestamp.start.year
2026

repr ¶

__repr__() -> str

Return a developer-friendly representation.

str ¶

__str__() -> str

Render clock 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,
) -> Clock

Create a org_parser.time.Clock from a tree-sitter clock 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 timestamp and this clock dirty for scratch-built rendering.

Time¶

time ¶

Timestamp ¶

delay property writable ¶

dirty property ¶

end property ¶

end_day property writable ¶

end_dayname property writable ¶

end_hour property writable ¶

end_minute property writable ¶

end_month property writable ¶

end_year property writable ¶

is_active property writable ¶

parent property writable ¶

repeater property writable ¶

repeater_cap property writable ¶

start property ¶

start_day property writable ¶

start_dayname property writable ¶

start_hour property writable ¶

start_minute property writable ¶

start_month property writable ¶

start_year property writable ¶

__eq__ ¶

__repr__ ¶

__str__ ¶

from_datetime classmethod ¶

from_node classmethod ¶

from_source classmethod ¶

mark_dirty ¶

reformat ¶

to_datetime ¶

Clock ¶

body_text property ¶

column property ¶

dirty property ¶

duration property writable ¶

keywords property ¶

line property ¶

parent property writable ¶

text property ¶

timestamp property writable ¶

__repr__ ¶

__str__ ¶

attach_keyword ¶

attach_source ¶

from_node classmethod ¶

from_source classmethod ¶

mark_dirty ¶

reformat ¶

delay `property` `writable` ¶

dirty `property` ¶

end `property` ¶

end_day `property` `writable` ¶

end_dayname `property` `writable` ¶

end_hour `property` `writable` ¶

end_minute `property` `writable` ¶

end_month `property` `writable` ¶

end_year `property` `writable` ¶

is_active `property` `writable` ¶

parent `property` `writable` ¶

repeater `property` `writable` ¶

repeater_cap `property` `writable` ¶

start `property` ¶

start_day `property` `writable` ¶

start_dayname `property` `writable` ¶

start_hour `property` `writable` ¶

start_minute `property` `writable` ¶

start_month `property` `writable` ¶

start_year `property` `writable` ¶

eq ¶

repr ¶

str ¶

from_datetime `classmethod` ¶

from_node `classmethod` ¶

from_source `classmethod` ¶

body_text `property` ¶

column `property` ¶

dirty `property` ¶

duration `property` `writable` ¶

keywords `property` ¶

line `property` ¶

parent `property` `writable` ¶

text `property` ¶

timestamp `property` `writable` ¶

repr ¶

str ¶

from_node `classmethod` ¶

from_source `classmethod` ¶