Grumpy: Go running Python - Deploy & Usage Guide

Prerequisites

• Go (version 1.7 or later)
• Python 2.7 (Grumpy targets CPython 2.7 compatibility)
• Git for cloning the repository
• GNU Make for building the project

Installation

1. Clone the repository:

   git clone https://github.com/google/grumpy.git
   cd grumpy
   

2. Build the project:

   make
   

3. Set up environment variables:

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

4. Verify installation:

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

Configuration

Environment Variables

• PATH: Add $PWD/build/bin to access grumpc and grumprun
• GOPATH: Set to $PWD/build for Go package resolution
• PYTHONPATH: Set to $PWD/build/lib/python2.7/site-packages for Python modules

GOPATH Structure

Grumpy expects Python source code in the __python__ subdirectory of GOPATH:

$GOPATH/src/__python__/your_module.py

Build & Run

Method 1: Using make run (Simple)

For quick testing of Python code:

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

Method 2: Using grumpc and grumprun (Advanced)

1. Compile Python to Go:

   grumpc -modname=hello $GOPATH/src/__python__/hello.py > $GOPATH/src/__python__/hello/module.go
   

2. Run the compiled code:

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

Method 3: Manual Go Build

1. Create a Go package from Python:

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

2. Build and run with Go:

   go build -o hello_app main.go
   ./hello_app
   

Deployment

Local Development

For local development and testing, use the make run or grumprun methods. Grumpy programs are statically linked, so all dependencies must be available in the GOPATH.

Production Deployment

Since Grumpy compiles Python to native Go binaries, deployment is straightforward:

1. Build your application:

   grumpc -modname=your_app your_app.py > your_app/module.go
   go build -o your_app_binary main.go
   

2. Deploy the binary:

   • Copy the compiled binary to your production server
   • No Python runtime required on the server
   • Ensure all static data files are included

Platform Considerations

• Linux/Unix: Native Go binaries run on any Linux/Unix system with compatible architecture
• Docker: Create a minimal Docker image with just the binary
• Cloud Functions: Deploy as a standalone binary to platforms supporting custom runtimes

Troubleshooting

Common Issues

1. "ImportError: No module named..."

   • Ensure the module is in $GOPATH/src/__python__/
   • Check that the module was compiled with grumpc

2. Build failures with make

   • Verify Go version is 1.7 or later
   • Check that GOPATH is set correctly
   • Ensure all dependencies are available

3. Runtime errors

   • Grumpy has limited support for dynamic features like exec, eval, and compile
   • C extension modules are not supported
   • Some standard library modules may be missing or incomplete

Debugging Tips

1. Check compilation:

   grumpc -modname=your_module your_module.py
   

2. Verify GOPATH structure:

   ls -la $GOPATH/src/__python__/
   

3. Test with minimal code:

   echo "print 'test'" | make run
   

Limitations to Remember

• No support for exec, eval, or compile
• No C extension modules
• Limited standard library support
• No old-style classes
• Some operators and built-in functions may be missing

Performance Considerations

• Grumpy compiles to native code, so performance should be comparable to Go
• Static linking means all dependencies are included in the binary
• No Python interpreter overhead during execution