Tree Models

Tree models model the AST nodes that may have children.

Raw and value properties

Tree models have many properties, some have a raw_ prefix (raw properties) and many raw properties have a corresponding value property without the raw_ prefix. The raw properties provide raw access to children, while the value properties provide access to the semantic value of those children. For example:

balance = p.parse('2000-01-01 balance Assets:Foo 100 * 2.00 USD ; comment', models.Balance)
_print_model(balance.raw_number)

100 * 2.00

(balance.number, balance.raw_number.value)

(Decimal('200.00'), Decimal('200.00'))

Value properties should suffice for most cases but raw properties are provided to allow more fine-grained and lossless access to the tree structure, for example, when you want to access the expression above.

Value properties sometimes also returns models, usually to make distinction between different types of values (e.g. unit cost vs total cost; string vs currency).

Not all raw properties have corresponding value properties. For example, File.raw_directives_with_comments doesn’t have a obvious way to simplify.

Required properties

Some children of a model is required by the beancount syntax, and those children are modeled in required properties.

Required properties always have values. They may be read, updated, but cannot be deleted, or created.

(balance.raw_date, balance.date)

(<Date: '2000-01-01'>, datetime.date(2000, 1, 1))

balance.date = datetime.date(2000, 1, 2)
balance.raw_currency = models.Currency.from_value('GBP')

_print_model(balance)

2000-01-02 balance Assets:Foo 100 * 2.00 GBP ; comment

Optional properties

Some children of a model is optional, and those children are modeled in optional properties.

Optional properties may be None, and may be set to and from None in order to delete or create them.

balance.raw_inline_comment = None
balance.tolerance = decimal.Decimal('0.01')

_print_model(balance)

2000-01-02 balance Assets:Foo 100 * 2.00 ~ 0.01 GBP

Repeated properties

Repeated properties returns a wrapper that implements MutableSequence.

custom = p.parse('2000-01-01 custom "type" 123.45 Assets:Foo TRUE "foo"', models.Custom)

(custom.values[1], list(custom.raw_values))

(<Account: 'Assets:Foo'>,
 [<autobean_refactor.models.number_expr.NumberExpr at 0x79168eb05cd0>,
  <Account: 'Assets:Foo'>,
  <Bool: 'TRUE'>,
  <EscapedString: '"foo"'>])

custom.values[3] = datetime.date(2000, 1, 2)
del custom.values[1:3]

_print_model(custom)

2000-01-01 custom "type" 123.45 2000-01-02

Filtered repeated properties

Filtered repeated properties is a special type of repeated properties. This can be useful when the gramma allows multiple types of children to interleave, but you are only interested in a certain type.

note = p.parse('2000-01-01 note Assets:Foo "note" #tag0 ^link0 #tag1 ^link1', models.Note)
note.tags[1] = 'updated'

_print_model(note)

2000-01-01 note Assets:Foo "note" #tag0 ^link0 #updated ^link1

Construction

Most tree models can be constructed with class methods from_children, which takes children models, or from_value, which takes semantic values. Refer to the method signature for accepted arguments.

Warning

Do not construct models directly with ModelType(...).

close1 = models.Close.from_children(
    date=models.Date.from_value(datetime.date(2000, 1, 2)),
    account=models.Account.from_value('Assets:Foo'),
    inline_comment=models.InlineComment.from_value('comment'),
)
close2 = models.Close.from_value(
    date=datetime.date(2000, 1, 2),
    account='Assets:Foo',
    inline_comment='comment',
)
_print_model(close1)
_print_model(close2)

2000-01-02 close Assets:Foo ; comment
2000-01-02 close Assets:Foo ; comment

List of all tree models

sorted([
    model.__name__ for model in models.__dict__.values()
    if isinstance(model, type) and issubclass(model, models.RawTreeModel)])

['Amount',
 'Balance',
 'Close',
 'Commodity',
 'CompoundAmount',
 'CostSpec',
 'Custom',
 'Document',
 'Event',
 'File',
 'IgnoredLine',
 'Include',
 'MetaItem',
 'Note',
 'NumberAddExpr',
 'NumberExpr',
 'NumberMulExpr',
 'NumberParenExpr',
 'NumberUnaryExpr',
 'Open',
 'Option',
 'Pad',
 'Plugin',
 'Popmeta',
 'Poptag',
 'Posting',
 'Price',
 'Pushmeta',
 'Pushtag',
 'Query',
 'RawTreeModel',
 'Tolerance',
 'TotalCost',
 'TotalPrice',
 'Transaction',
 'UnitCost',
 'UnitPrice']