Basic Usage

Baron provides two main functions:

• parse to transform a string into Baron’s FST;
• dumps to transform the FST back into a string.

In [1]: from baron import parse, dumps

In [2]: source_code = "def f(x = 1):\n    return x\n"

In [3]: fst = parse(source_code)

In [4]: generated_source_code = dumps(fst)

In [5]: generated_source_code
Out[5]: 'def f(x = 1):\n    return x\n'

In [6]: source_code == generated_source_code
Out[6]: True

Like said in the introduction, the FST keeps the formatting unlike ASTs. Here the following 3 codes are equivalent but their formatting is different. Baron keeps the difference so when dumping back the FST, all the formatting is respected:

In [7]: dumps(parse("a = 1"))
Out[7]: 'a = 1'

In [8]: dumps(parse("a=1"))
Out[8]: 'a=1'

In [9]: dumps(parse("a   =   1"))
Out[9]: 'a   =   1'

Helpers

Baron also provides 3 helper functions show, show_file and show_node to explore the FST (in iPython for example). Those functions will print a formatted version of the FST so you can play with it to explore the FST and have an idea of what you are playing with.

Show

show is used directly on a string:

In [10]: from baron.helpers import show

In [11]: show("a = 1")
[
    {
        "first_formatting": [
            {
                "type": "space", 
                "value": " "
            }
        ], 
        "annotation_first_formatting": [], 
        "target": {
            "type": "name", 
            "value": "a"
        }, 
        "annotation_second_formatting": [], 
        "operator": "", 
        "type": "assignment", 
        "annotation": {}, 
        "value": {
            "section": "number", 
            "type": "int", 
            "value": "1"
        }, 
        "second_formatting": [
            {
                "type": "space", 
                "value": " "
            }
        ]
    }
]

In [12]: show("a +=  b")
[
    {
        "first_formatting": [
            {
                "type": "space", 
                "value": " "
            }
        ], 
        "annotation_first_formatting": [], 
        "target": {
            "type": "name", 
            "value": "a"
        }, 
        "annotation_second_formatting": [], 
        "operator": "+", 
        "type": "assignment", 
        "annotation": {}, 
        "value": {
            "type": "name", 
            "value": "b"
        }, 
        "second_formatting": [
            {
                "type": "space", 
                "value": "  "
            }
        ]
    }
]

Show_file

show_file is used on a file path:

from baron.helpers import show_file

show_file("/path/to/a/file")

Show_node

show_node is used on an already parsed string:

In [13]: from baron.helpers import show_node

In [14]: fst = parse("a = 1")

In [15]: show_node(fst)
[
    {
        "first_formatting": [
            {
                "type": "space", 
                "value": " "
            }
        ], 
        "annotation_first_formatting": [], 
        "target": {
            "type": "name", 
            "value": "a"
        }, 
        "annotation_second_formatting": [], 
        "operator": "", 
        "type": "assignment", 
        "annotation": {}, 
        "value": {
            "section": "number", 
            "type": "int", 
            "value": "1"
        }, 
        "second_formatting": [
            {
                "type": "space", 
                "value": " "
            }
        ]
    }
]

Under the hood, the FST is serialized into JSON so the helpers are simply encapsulating JSON pretty printers.