Welcome to RedBaron’s documentation! — RedBaron 0.8 documentation

# Welcome to RedBaron’s documentation!

## Introduction

RedBaron is a python library and tool powerful enough to be used into IPython solely that intent to make the process of writing code that modify source code as easy and as simple as possible. That include writing custom refactoring, generic refactoring, tools, IDE or directly modifying you source code into IPython with a higher and more powerful abstraction than the advanced texts modification tools that you find in advanced text editors and IDE.

RedBaron guaranteed you that it will only modify your code where you ask him to. To achieve this, it is based on Baron a lossless AST for Python that guarantees the operation `fst_to_code(code_to_fst(source_code)) == source_code`.

RedBaron API and feel is heavily inspired by BeautifulSoup. It tries to be simple and intuitive and that once you’ve get the basics principles, you are good without reading the doc for 80% of your operations.

## A note about the examples

This documentation is full of example for nearly everything. But in fact, those aren’t really “example”: those are real life code that are executed at the compilation time of this documentation, this guaranteed the example you see to work exactly the same way for you.

Funny side effect: this make it possible to “break” this documentation.

## Code

https://github.com/PyCQA/redbaron

## Installation

    pip install redbaron[pygments]

Or if you don’t want to have syntax highlight in your shell or don’t need it:

    pip install redbaron

## Basic usage

Simple API: give string, get string back.

    In [1]: from redbaron import RedBaron

    In [2]: red = RedBaron("some_value = 42")

    In [3]: red.dumps()  # get code back
    Out[3]: 'some_value = 42'

Though to be used in IPython directly:

    In [4]: red  # direct feedback like BeautifulSoup, "0" here is the index of the node in our source code
    Out[4]: 0   some_value = 42

    In [5]: red.help()  # helper function that describe nodes content so you don't have to read the doc
    0 -----------------------------------------------------
    AssignmentNode()
      # identifiers: assign, assignment, assignment_, assignmentnode
      operator=''
      target ->
        NameNode()
          # identifiers: name, name_, namenode
          value='some_value'
      annotation ->
        None
      value ->
        IntNode()
          # identifiers: int, int_, intnode
          value='42'

Easy nodes modifications, you already know how to code in python, so pass python code (in a string) on the attribute you want to modify (wonder what `.value` is? look at the output of `.help()` in the previous example):

    In [6]: red[0].value = "1 + 4"

    In [7]: red
    Out[7]: 0   some_value = 1 + 4

Easy queries, just like in BeautifulSoup:

    In [8]: red.find("int", value=4)

    In [9]: red.find_all("int")  # can also be written red("int") like in BeautifulSoup
    Out[9]:
    0   1
    1   4

Queries can be very powerful, you can test each attributes with value/lambda/regex/special syntax for regex/globs.

Now let’s pretend that we are editing a django settings.py (notice that we are extending our source code using the same API than the one of a python list since we are in a list of lines):

    In [10]: red.extend(["\n", "INSTALLED_APPLICATIONS = (\n    'django',\n)"])  # here "\n" is to had a blank line

    In [11]: red
    Out[11]:
    0   some_value = 1 + 4
    1   INSTALLED_APPLICATIONS = (
            'django',
        )

And let’s install another django application! (again: same API than a python list)

    In [12]: red.find("assignment", target=lambda x: x.dumps() == "INSTALLED_APPLICATIONS").value.append("'another_app'")

    In [13]: red
    Out[13]:
    0   some_value = 1 + 4
    1   INSTALLED_APPLICATIONS = (
            'django',
            'another_app',
        )

Notice that the formatting of the tuple has been detected and respected when adding the new django application.

And let’s see the result of our work:

    In [14]: print(red.dumps())
    some_value = 1 + 4
    INSTALLED_APPLICATIONS = (
        'django',
        'another_app',
    )

## Financial support

Baron and RedBaron are a very advanced piece of engineering that requires a lot of time of concentration to work on. Until the end of 2018, the development has been a full volunteer work mostly done by [Bram](https://github.com/psycojoker), but now, to reach the next level and bring those projects to the stability and quality you expect, we need your support.

You can join our contributors and sponsors on our transparent [OpenCollective](https://opencollective.com/redbaron), every contribution will count and will be mainly used to work on the projects stability and quality but also on continuing, on the side, the R&D side of those projects.

### Our supporters

Become our first sponsor!

## Table of content

- Learn how to use RedBaron
  - Basic principles
  - Use it in a shell
  - Querying
  - Modification
  - Playing with list of nodes
  - Misc things
- Why is this important?
  - Other usages
- Basics
  - .help()
  - nodes structure
  - .dumps(), transform the tree into source code
  - .fst(), transform the RedBaron tree into Baron FST
  - .copy()
- Querying
  - .find()
  - .find_all()
  - Advanced querying
- Modifying
  - Principle
  - Code block modifications
  - Details
  - Auto assignment of .parent and .on_attribute
- Proxy List
  - Problem
  - Solution
  - Usage
  - Access the unproxified node list
  - Omitting “.value”
  - CommaProxyList
  - DotProxyList
  - LineProxyList
  - DecoratorLineProxyList
- Other
  - .parent
  - .parent_find()
  - .next .previous .next_recursive .previous_recursive .next_generator() .previous_generator()
  - .next_intuitive/.previous_intuitive
  - .root
  - .index_on_parent
  - .index_on_parent_raw
  - .filtered()
  - .indentation
  - .increase_indentation() and .decrease_indentation()
  - .to_python()
  - .path()
  - Path class
  - .map .filter .apply
  - .replace()
  - .edit()
  - .absolute_bounding_box
  - .bounding_box
  - .find_by_position()
  - .at()
  - Node.from_fst()
  - NodeList.from_fst()
  - .insert_before .insert_after

## Reference

- Nodes References Page
- TopClass
  - CodeBlockNode
- Nodes
  - ArgumentGeneratorComprehensionNode
  - AssertNode
  - AssignmentNode
  - AssociativeParenthesisNode
  - AtomtrailersNode
  - BinaryNode
  - BinaryOperatorNode
  - BooleanOperatorNode
  - CallNode
  - CallArgumentNode
  - ClassNode
  - CommaNode
  - ComparisonNode
  - ComprehensionIfNode
  - ComprehensionLoopNode
  - DecoratorNode
  - DefNode
  - DefArgumentNode
  - DelNode
  - DictArgumentNode
  - DictNode
  - DictComprehensionNode
  - DottedAsNameNode
  - DotNode
  - ElifNode
  - ElseNode
  - EllipsisNode
  - EndlNode
  - ExceptNode
  - ExecNode
  - FinallyNode
  - ForNode
  - FromImportNode
  - GeneratorComprehensionNode
  - GetitemNode
  - GlobalNode
  - IfNode
  - IfelseblockNode
  - ImportNode
  - IntNode
  - KwargsOnlyMarkerNode
  - LambdaNode
  - ListArgumentNode
  - ListComprehensionNode
  - ListNode
  - NameAsNameNode
  - NonlocalNode
  - PrintNode
  - RaiseNode
  - ReprNode
  - ReturnNode
  - SetNode
  - SetComprehensionNode
  - SliceNode
  - SpaceNode
  - StarExpressionNode
  - StringChainNode
  - TernaryOperatorNode
  - TryNode
  - TupleNode
  - UnitaryOperatorNode
  - YieldNode
  - YieldAtomNode
  - YieldFromNode
  - WhileNode
  - WithContext
  - WithContextItemNode
  - WithNode

# Indices and tables

- Index
- Module Index
- Search Page