Permalink
Fetching contributors…
Cannot retrieve contributors at this time
359 lines (252 sloc) 7.8 KB
.. ipython:: python
    :suppress:

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

    import redbaron
    redbaron.ipython_behavior = False

    from redbaron import RedBaron


Proxy List

Problem

For a python developer, the list :file:`[1, 2, 3]` has 3 members, which is true in the python world, but in the "source code modification" world, this list has 5 elements because you have to count the 2 commas. Indeed each comma needs to be taken into account separately because they can have a different formatting.

This makes things quite annoying to deal with because you have to think about the formatting too! For example, if you want to append an item to a list, you need to take care of a lot of details:

  • if the list is empty you don't have to put a comma
  • otherwise yes
  • but wait, what happens if there is a trailing comma?
  • also, what to do if the list is declared in an indented way (with :file:`"\\n "` after every comma for example)?
  • etc...

And that's only for a comma separated list of things: you also have the same formatting details to care about for dot separated lists (e.g. :file:`a.b.c().d[plop]`) and endl separated lists (a python code block, or you whole source file).

You don't want to have to deal with this.

Solution

To avoid you to deal with all this boring low level details, RedBaron implements "proxy lists". This abstraction gives you the impression that the list of things you are dealing with behave the same way than in the python world while taking care of all the low level formatting details.

The "proxy lists" has the same API than a python list so they should be really intuitive to use.

For example:

.. ipython:: python

    red = RedBaron("[1, 2, 3]")
    red[0].value.append("42")
    red
    del red[0].value[2]
    red

There are, for now, 4 kind of proxy lists:

Be aware that the proxy list are set on the attribute that is a list, not on the node holding the list. See the 'value' attribute access in the examples below.

Usage

As said, proxy lists have the exact same API than python lists (at the exception that they don't implement the :file:`sort` and :file:`reverse` methods). Every method accepts as input the same inputs that you can use to modify a node in RedBaron. This means that you can pass a string containing source code, an FST or a RedBaron node.

Here is a session demonstrating every method of a proxy list:

.. ipython:: python

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

Please refer to python list documentation if you want to know the exact behavior or those methods (or send a patch to improve this documentation).

append

.. ipython:: python

    red
    red[0].value.append("plop")
    red
    red[0].value

insert

.. ipython:: python

    red
    red[0].value.insert(1, "42")
    red
    red[0].value

extend

.. ipython:: python

    red
    red[0].value.extend(["pif", "paf", "pouf"])
    red
    red[0].value

pop

.. ipython:: python

    red
    red[0].value.pop()
    red
    red[0].value
    red[0].value.pop(3)
    red
    red[0].value

__getitem__

.. ipython:: python

    red
    red[0].value
    red[0].value[2]

__setitem__

.. ipython:: python

    red
    red[0].value[2] = "1 + 1"
    red
    red[0].value

remove

.. ipython:: python

    red
    red[0].value.remove(red[0].value[2])
    red
    red[0].value

index

.. ipython:: python

    red
    red[0].value
    red[0].value.index(red[0].value[2])

count

.. ipython:: python

    red
    red[0].value
    red[0].value.count(red[0].value[2])

len

.. ipython:: python

    red
    red[0].value
    len(red[0].value)

__delitem__

.. ipython:: python

    red
    del red[0].value[2]
    red
    red[0].value

in

.. ipython:: python

    red
    red[0].value[2] in red[0].value

__iter__

.. ipython:: python

    red
    for i in red[0].value:
        print(i.dumps())

__getslice__

.. ipython:: python

    red
    red[0].value
    red[0].value[2:4]

__setslice__

.. ipython:: python

    red
    red[0].value[2:4] = ["1 + 1", "a", "b", "c"]
    red
    red[0].value

__delslice__

.. ipython:: python

    red
    red[0].value[2:5]
    del red[0].value[2:5]
    red
    red[0].value

Access the unproxified node list

The unproxified node list is stored under the attribute :file:`node_list` of the proxy list. Be aware that, for now, the proxy won't detect if you directly modify the unproxified node list, this will cause bugs if you modify the unproxified list then use the proxy list directly. So, for now, only use one or the other.

.. ipython:: python

    red = RedBaron("[1, 2, 3]")
    red[0].value.node_list
    red[0].value

Omitting ".value"

For convenience, and because this is a super common typo error, if a node has a proxy list on its :file:`.value` attribute, you can omit to access it and the method access will be automatically redirect to it.

This means that the 2 next lines are equivalent:

.. ipython:: python

    red[0]
    red[0].value.append("plop")
    red[0].append("plop")

CommaProxyList

CommaProxyList is the most generic and most obvious proxy list, all the examples above are made using it.

It is used everywhere where values are separated by commas.

DotProxyList

DotProxyList is nearly as generic as the CommaProxyList. The specific case of a DotProxyList is that it is intelligent enough to not add a "." before a "call" (:file:`(a, b=c, *d, **e)`) or a "getitem" (:file:`[foobar]`).

.. ipython:: python

    red = RedBaron("a.b(c).d[e]")
    red[0].value
    red[0].extend(["[stuff]", "f", "(g, h)"])
    red[0]
    red[0].value

It is used everywhere where values are separated by ".".

You can see a complete example with a DotProxyList, like for the CommaProxyList, here: :doc:`dotproxylist`.

LineProxyList

LineProxyList is used to handle lines of code, it takes care to place the correct endl node between and to set the correct indentation and not to break the indentation of the next block (if there is one).

One particularity of LineProxyList is that it shows you explicitly the empty line (while other proxy lists never show you formatting). This is done because you'll often want to be able to manage those blank lines because you want to put some space in your code or separate group of lines.

.. ipython:: python

    red = RedBaron("while 42:\n    stuff\n    other_stuff\n\n    there_is_an_empty_line_before_me")
    red
    red[0].value
    red[0].append("plouf")
    red
    red[0].value

You can see a complete example with a LineProxyList, like for the CommaProxyList, here: :doc:`lineproxylist`.

DecoratorLineProxyList

A DecoratorLineProxyList is exactly the same as a LineProxyList except it has a small modification to indent decorators correctly. Just think of it as a simple LineProxyList and everything will be fine.

Don't forget to add the :file:`@` when you add a new decorator (omitting it will raise an exception).

Example:

.. ipython:: python

    red = RedBaron("@plop\ndef stuff():\n    pass\n")
    red
    red[0].decorators.append("@plouf")
    red[0].decorators
    red

Next

To learn about various helpers and features in RedBaron, read :doc:`other`. Be sure to check the :file:`.replace()` method on that page as it can be very useful.