Repository files navigation

Baron is a Full Syntax Tree (FST) library for Python. By opposition to anAST whichdrops some syntax information in the process of its creation (like empty lines,comments, formatting), a FST keeps everything and guarantees the operationfst_to_code(code_to_fst(source_code)) == source_code.

Current roadmap is as boring as needed:

• bug fixs
• new small features (walker pattern, maybe code generation) and performance improvement.

pip install baron

frombaronimportparse,dumpsfst=parse(source_code_string)source_code_string==dumps(fst)

Unless you want to do low level things,useRedBaron instead of using Barondirectly. Think of Baron as the "bytecode of python source code" and RedBaronas some sort of usable layer on top of it.

If you don't know what Baron is or don't understand yet why it might beuseful for you, read the« Why is this important? » section.

Baron documentation is available onRead The Docs.

If you want to implement new grammar elements for newer python versions, hereare the documented steps for that:https://github.com/PyCQA/baron/blob/master/add_new_grammar.md

Also note that reviewing most grammar modifications takes several hours ofadvanced focusing (we can't really afford bugs here) so don't despair if you PRseems to be hanging around, sorry for that :/

And thanks in advance for your work!

Baron and RedBaron are a very advanced piece of engineering that requires a lotof time of concentration to work on. Until the end of 2018, the developmenthas been a full volunteer work mostly done byBram,but now, to reach the next level and bring those projects to the stability andquality you expect, we need your support.

You can join our contributors and sponsors on our transparentOpenCollective, every contribution willcount and will be mainly used to work on the projects stability and quality butalso on continuing, on the side, the R&D side of those projects.

The usage of a FST might not be obvious at first sight so let's consider aseries of problems to illustrate it. Let's say that you want to write a program that will:

• rename a variable in a source file... without clashing with things that are not a variable (example: stuff inside a string)
• inline a function/method
• extract a function/method from a series of line of code
• split a class into several classes
• split a file into several modules
• convert your whole code base from one ORM to another
• do custom refactoring operation not implemented by IDE/rope
• implement the class browser of smalltalk for python (the whole one where you can edit the code of the methods, not just showing code)

It is very likely that you will end up with the awkward feeling of writingclumpsy weak code that is very likely to break because you didn't thought aboutall the annoying special cases and the formatting keeps bothering you. You mayend up playing withast.py untilyou realize that it removes too much information to be suitable for thosesituations. You will probably ditch this task as simply too complicated andreally not worth the effort. You are missing a good abstraction that will takecare of all of the code structure and formatting for you so you can concentrateon your task.

The FST tries to be this abstraction. With it you can now work on a tree whichrepresents your code with its formatting. Moreover, since it is the exactrepresentation of your code, modifying it and converting it back to a stringwill give you back your code only modified where you have modified the tree.

Said in another way, what I'm trying to achieve with Baron is a paradigm change inwhich writing code that will modify code is now a realist task that is worththe price (I'm not saying a simple task, but a realistic one: it's still acomplex task).

Having a FST (or at least a good abstraction build on it) also makes it easierto do code generation and code analysis while those two operations are alreadyquite feasible (usingast.pyand a templating engine for example).

Baron produces a FST in the form of JSON (and by JSON I mean Python listsand dicts that can be dumped into JSON) for maximum interoperability.

Baron FST is quite similar to Python AST with some modifications to be moreintuitive to humans, since Python AST has been made for CPython interpreter.

Since playing directly with JSON is a bit raw I'm going to build an abstractionon top of it that will looks like BeautifulSoup/jQuery.

Currently, Baron has been tested on the top 100 projects and the FST convertsback exactly into the original source code. So, it can be considered quitestable, but it is far away from having been battle tested.

Since the project is very young and no one is already using it except myproject, I'm open to changes of the FST nodes but I will quickly becomeconservative once it gets some adoption and will probably accept tomodify it only once or twice in the future with clear indications on how tomigrate.

Baron is supporting python 2 grammar and up to python 3.7 grammar.

Run eitherpy.test tests/ ornosetests in the baron directory.

You can reach us onirc.freenode.net#baron orirc.freenode.net##python-code-quality.

As a member ofPyCQA, Baron follows itsCode of Conduct.

Old blog post announcing the project. Not that much up to date.