File: basics.rst

package info (click to toggle)
python-redbaron 0.9.2-4
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid, trixie
  • size: 772 kB
  • sloc: python: 6,650; makefile: 145; sh: 28
file content (242 lines) | stat: -rw-r--r-- 6,654 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
.. ipython:: python
    :suppress:

    import sys
    sys.path.append("..")

    import redbaron
    redbaron.ipython_behavior = False

    from redbaron import RedBaron


Basics
======

RedBaron is very simple to use, you just need to import it and feed him with a string:

.. code-block:: python

    from redbaron import RedBaron

    red = RedBaron("print('hello world!')")

But what you should be really doing is using RedBaron directly into a shell (I
recommend `IPython <http://ipython.org/>`_ but
`bpython <http://bpython-interpreter.org/>`_ is cool too), it has been thought
for it, like BeautifulSoup.

.. ipython:: python
    :suppress:

    import sys
    sys.path.append("..")

    import redbaron
    redbaron.ipython_behavior = False

.. ipython:: python

    from redbaron import RedBaron
    red = RedBaron("hello = 'Hello World!'\nprint(hello)")
    red

As you can see, when displayed in a shell, a RedBaron instance renders to the actual
content so you easily see what you are doing when playing interactively with it
(just like a BeautifulSoup instance).

There are 2 families of Node in RedBaron: NodeList and standalone Node. Since a
Python program is a list of operations, RedBaron will always be a list.
This is why when displayed you see integers on the left, those are the index in
the list of the nodes of the right, so as expected:

.. ipython::

    In [4]: red[1]

You get the `print` Node that was located at 2. As you can see, here we are on a
standalone Node, so we don't get the list of indexes of the left.

.. _help():

.help()
-------

Another useful function is :file:`.help()`. It displays the RedBaron nodes tree
helping you understand how is it composed and how you can use it:

.. ipython::

    In [5]: red[0]

    In [6]: red[0].help()

Here, as you can see, :file:`hello = 'Hello World!'` is an
:file:`AssignmentNode` and it has 2 attributes: :file:`target` and
:file:`value`. Those 2 attributes are 2 other nodes, a :file:`NameNode` for the
variable :file:`hello` and a :file:`StringNode` for the string. Those 2 nodes
each have one attribute :file:`value` that is their content.

One rule with Baron: **every node has a value attribute** that contains its
value (in case of a node with multiple data, :file:`value` points to the most
obvious one, for example, in a function definition it's the body of the
function). The **only exceptions** are nodes where it doesn't make any sense,
for example a :file:`PassNode` (representing the keyword :file:`pass`) simply
doesn't contain anything.

Like the :file:`repr`, :file:`.help()` has also a display showing index number
when called on a :file:`NodeList`:

.. ipython::

    In [14]: red.help()

The best way to understand how :file:`.help()` works is to remember that
RedBaron is mapping from Baron FST which is JSON. This means that RedBaron node
can be composed of either: string, bool, numbers, list or other nodes and the
key are always string.

helpers
~~~~~~~

Some nodes come with helpers method, :file:`.help()` displays them when they
are present:

.. ipython:: python

    red = RedBaron("import a, b, c as d")
    red.help(deep=1)

You can read their documentation using the :file:`?` magic of ipython:

.. ipython:: python

    print(red[0].names.__doc__)  # you can do "red[0].names?" in IPython shell
    red[0].names()

    print(red[0].modules.__doc__)
    red[0].modules()

If you come with cool helpers, don't hesitate to propose them in a `pull
request <https://github.com/Psycojoker/redbaron>`_!

deep
~~~~

:file:`.help()` accept a deep argument on how far in the tree it should show
the :file:`.help()` of subnode. By default its value is :file:`2`. You can pass
the value :file:`True` if you want to display the whole tree.

.. ipython:: python

    red = RedBaron("a = b if c else d")
    red.help()
    red.help(0)
    red.help(deep=1)  # you can name the argument too
    red.help(True)

with_formatting
~~~~~~~~~~~~~~~

:file:`.help()` accepts the option :file:`with_formatting` that is set at
:file:`False` by default. If set at :file:`True` it will also display the
attributes responsible for holding the formatting of the node (they are always
node list):

.. ipython::

    In [12]: red.help(with_formatting=True)

Those attributes are always surrounding syntax element of Python like
:file:`[](),.{}` or keywords. You should, normally, not have a lot of reasons
to play with them. You can find a detailed version of each nodes here:
:doc:`nodes_reference`.

nodes structure
---------------

Nodes can have 3 kind of attributes (which can be accessed like normal object
attributes):

* data attributes, which are nearly always strings. They are shown with a :file:`=` in
  :file:`.help()`. :file:`.value` here for example.

.. ipython::

    In [1]: red = RedBaron("variable")

    In [2]: red[0].help()

    In [3]: red[0].value

* node attributes, which are other nodes. They are shown with a :file:`->` followed by the name of the other node
  at the next line in :file:`.help()`. :file:`.target` and :file:`.value` here for example.

.. ipython::

    In [19]: red = RedBaron("a = 1")

    In [20]: red[0].help()

    In [21]: red[0].target.help()

* nodelist attributes, which are lists of other nodes. They are shown with a :file:`->` followed by a series of names
  of the other nodes starting with a :file:`*` for every item of the list. :file:`.value` here for example:

.. ipython::

    In [17]: red = RedBaron("[1, 2, 3]")

    In [18]: red[0].help()

    In [19]: red[0].value[0].help()

.dumps(), transform the tree into source code
---------------------------------------------

To transform a RedBaron tree back into source code, use the
:file:`.dumps()` method. This will transform the **current selection** back
into code.

.. ipython::

    In [26]: red = RedBaron("a = 1")

    In [27]: red.dumps()

    In [28]: red[0].target.dumps()

.fst(), transform the RedBaron tree into Baron FST
--------------------------------------------------

To transform a RedBaron tree into Baron Full Syntax Tree, just use the
:file:`.fst()` method. This will transform the **current selection** into FST.

.. ipython::

    In [28]: red = RedBaron("a = 1")

    In [29]: red.fst()

    In [30]: red[0].target.fst()

While I don't see a lot of occasions where you might need this, this will
allow you to better understand how Baron and RedBaron are working.

.copy()
-------

If you want to copy a RedBaron node you can use the :file:`.copy()` method this
way:

.. ipython::

    In [45]: red = RedBaron("a = b")

    In [52]: red[0].target.copy()


Next
~~~~

To learn how to find things in RedBaron read :doc:`querying`.