Repository files navigation

Grumpy is a Python to Go source code transcompiler and runtime that is intendedto be a near drop-in replacement for CPython 2.7. The key difference is that itcompiles Python source code to Go source code which is then compiled to nativecode, rather than to bytecode. This means that Grumpy has no VM. The compiled Gosource code is a series of calls to the Grumpy runtime, a Go library serving asimilar purpose to the Python C API (although the API is incompatible withCPython's).

1. exec,eval andcompile: These dynamic features of CPython are notsupported by Grumpy because Grumpy modules consist of statically-compiled Gocode. Supporting dynamic execution would require bundling Grumpy programswith the compilation toolchain, which would be unwieldy and impracticallyslow.

2. C extension modules: Grumpy has a different API and object layout thanCPython and so supporting C extensions would be difficult. In principle it'spossible to support them via an API bridge layer like the one thatJyNI provides for Jython, but it would be hard to maintain andwould add significant overhead when calling into and out of extensionmodules.

There are three basic categories of incomplete functionality:

1. Language features:Most language features are implemented with the notable exception ofold-style classes.There are also a handful of operators that aren't yet supported.

2. Builtin functions and types:There are a number of missing functions and types in__builtins__ that havenot yet been implemented. There are also a lot of methods on builtin typesthat are missing.

3. Standard library:The Python standard library is very large and much of it is pure Python, soas the language features and builtins get filled out, many modules willjust work. But there are also a number of libraries in CPython that are Cextension modules which will need to be rewritten.

4. C locale support: Go doesn't support locales in the same way that C does. As such,some functionality that is locale-dependent may not currently work the same as inCPython.

The simplest way to execute a Grumpy program is to usemake run, which wraps ashell script called grumprun that takes Python code on stdin and builds and runsthe code under Grumpy. All of the commands below are assumed to be run from theroot directory of the Grumpy source code distribution:

echo "print 'hello, world'" | make run

For more complicated programs, you'll want to compile your Python source code toGo using grumpc (the Grumpy compiler) and then build the Go code usinggo build. Since Grumpy programs are statically linked, all the modules in aprogram must be findable by the Grumpy toolchain on the GOPATH. Grumpy looks forGo packages corresponding to Python modules in the __python__ subdirectoryof the GOPATH. By convention, this subdirectory is also used for staging Pythonsource code, making it similar to the PYTHONPATH.

The first step is to set up the shell so that the Grumpy toolchain and librariescan be found. From the root directory of the Grumpy source distribution run:

makeexport PATH=$PWD/build/bin:$PATHexport GOPATH=$PWD/buildexport PYTHONPATH=$PWD/build/lib/python2.7/site-packages

You will know things are working if you see the expected output from thiscommand:

echo 'import sys; print sys.version' | grumprun

Next, we will write our simple Python module into the __python__ directory:

echo 'def hello(): print "hello, world"' > $GOPATH/src/__python__/hello.py

To build a Go package from our Python script, run the following:

mkdir -p $GOPATH/src/__python__/hellogrumpc -modname=hello $GOPATH/src/__python__/hello.py > \    $GOPATH/src/__python__/hello/module.go

You should now be able to build a Go program that imports the package"__python__/hello". We can also import this module into Python programsthat are built using grumprun:

echo 'from hello import hello; hello()' | grumprun

grumprun is doing a few things under the hood here:

1. Compiles the given Python code to a dummy Go package, the same way weproduced __python__/hello/module.go above
2. Produces a main Go package that imports the Go package from step 1. andexecutes it as our __main__ Python package
3. Executesgo run on the main package generated in step 2.

There are three main components and depending on what kind of feature you'rewriting, you may need to change one or more of these.

Grumpy converts Python programs into Go programs andgrumpc is the toolresponsible for parsing Python code and generating Go code from it.grumpc iswritten in Python and uses thepythonparsermodule to accomplish parsing.

The grumpc script itself lives attools/grumpc. It is supported by a number ofPython modules in thecompiler subdir.

The Go code generated bygrumpc performs operations on data structures thatrepresent Python objects in running Grumpy programs. These data structures andoperations are defined in thegrumpy Go library (source is in the runtimesubdir of the source distribution). This runtime is analogous to the Python CAPI and many of the structures and operations defined bygrumpy havecounterparts in CPython.

Much of the Python standard library is written in Python and thus "just works"in Grumpy. These parts of the standard library are copied from CPython 2.7(possibly with light modifications). For licensing reasons, these files are keptin thethird_party subdir.

The parts of the standard library that cannot be written in pure Python, e.g.file and directory operations, are kept in thelib subdir. In CPython thesekinds of modules are written as C extensions. In Grumpy they are written inPython but they use native Go extensions to access facilities not otherwiseavailable in Python.

• compiler: Python package implementating Python -> Go transcompilation logic.
• lib: Grumpy-specific Python standard library implementation.
• runtime: Go source code for the Grumpy runtime library.
• third_party/ouroboros: Pure Python standard libraries copied from theOuroboros project.
• third_party/pypy: Pure Python standard libraries copied from PyPy.
• third_party/stdlib: Pure Python standard libraries copied from CPython.
• tools: Transcompilation and utility binaries.

Questions? Comments? Drop us a line atgrumpy-users@googlegroups.comor join ourGitter channel