Go C TeX Batchfile
Clone or download
Latest commit 0efed2d Jul 16, 2018
Permalink
Failed to load latest commit information.
examples update examples/Display.ipynb Jun 14, 2018
files new screencasts Sep 19, 2017
fixtures Add tests for the actual Kernel Aug 30, 2017
kernel kernel: fixup Go kernel display name Aug 31, 2016
paper Update paper.bib Dec 15, 2017
vendor/github.com update GoPkg in vendor/github.com/cosmos72/gomacro/base/util.go to po… Jul 16, 2018
zmq-win update windows build for new org Sep 20, 2017
.gitignore implement code autocompletion by adapting @jpark-dev https://github.c… Jun 2, 2018
.travis.yml travis: add travis-ci Jul 4, 2018
CONTRIBUTORS update CONTRIBUTORS Jun 11, 2018
Dockerfile Dockerfile python lib is now version 3.6 not 3.5 Jul 9, 2018
Dockerfile.DS docker: import vecf32 and vecf64 from gorgonia.org Jul 9, 2018
Gopkg.lock fix #119: make interfaces insensitive to their methods declaration o… Jun 28, 2018
Gopkg.toml update vendored github.com/mattn/go-runewidth Jun 11, 2018
LICENSE Update and rename LICENSE.md to LICENSE Aug 4, 2017
README.md doc: add travis badge Jul 4, 2018
codemeta.json add JOSS paper data Dec 13, 2017
complete.go update vendored gomacro to fix bug [gomacro#28](cosmos72/gomacro#28): Jul 2, 2018
display.go automatically display image.Image or display.Data returned by REPL on… Jun 10, 2018
image.go if the only non-nil result returned by REPL is an image.Image or disp… Jun 10, 2018
kernel.go Merge branch 'display_image' of https://github.com/cosmos72/gophernotes Jun 14, 2018
kernel_test.go Update kernel_tests for the new execute_result handling Oct 21, 2017
main.go fix linting Sep 20, 2017
messages.go add file examples/Display.ipynb and link it in README.md Jun 14, 2018

README.md

alt tag

Build Status

gophernotes - Use Go in Jupyter notebooks and nteract

gophernotes is a Go kernel for Jupyter notebooks and nteract. It lets you use Go interactively in a browser-based notebook or desktop app. Use gophernotes to create and share documents that contain live Go code, equations, visualizations and explanatory text. These notebooks, with the live Go code, can then be shared with others via email, Dropbox, GitHub and the Jupyter Notebook Viewer. Go forth and do data science, or anything else interesting, with Go notebooks!

Acknowledgements - This project utilizes a Go interpreter called gomacro under the hood to evaluate Go code interactively. The gophernotes logo was designed by the brilliant Marcus Olsson and was inspired by Renee French's original Go Gopher design.

Examples

Jupyter Notebook:

nteract:

Example Notebooks (dowload and run them locally, follow the links to view in Github, or use the Jupyter Notebook Viewer):

Installation

Prerequisites

Linux

$ go get -u github.com/gopherdata/gophernotes
$ mkdir -p ~/.local/share/jupyter/kernels/gophernotes
$ cp $GOPATH/src/github.com/gopherdata/gophernotes/kernel/* ~/.local/share/jupyter/kernels/gophernotes

To confirm that the gophernotes binary is installed and in your PATH, you should see the following when running gophernotes directly:

$ gophernotes
2017/09/20 10:33:12 Need a command line argument specifying the connection file.

Note - if you have the JUPYTER_PATH environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:

$ jupyter --data-dir

Mac

Important Note - gomacro relies on the plugin package when importing third party libraries. This package works reliably on Mac OS X only with Go 1.10.2+ as long as you never execute the command strip gophernotes. If you can only compile gophernotes with Go <= 1.10.1 on Mac, consider using the Docker install and run gophernotes/Jupyter in Docker.

$ go get github.com/gopherdata/gophernotes
$ mkdir -p ~/Library/Jupyter/kernels/gophernotes
$ cp $GOPATH/src/github.com/gopherdata/gophernotes/kernel/* ~/Library/Jupyter/kernels/gophernotes

To confirm that the gophernotes binary is installed and in your PATH, you should see the following when running gophernotes directly:

$ gophernotes
2017/09/20 10:33:12 Need a command line argument specifying the connection file.

Note - if you have the JUPYTER_PATH environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:

$ jupyter --data-dir

Windows

Important Note - gomacro relies on the plugin package when importing third party libraries. This package is only supported on Linux and Mac OS X currently. Thus, if you need to utilize third party packages in your Go notebooks and you are running on Windows, you should use the Docker install and run gophernotes/Jupyter in Docker.

Make sure you have the MinGW toolchain:

Then:

  1. build and install gophernotes (using the pre-built binaries and zmq-win\build.bat):

    REM Download w/o building.
    go get -d github.com/gopherdata/gophernotes
    cd %GOPATH%\src\github.com\gopherdata\gophernotes\zmq-win
    
    REM Build x64 version.
    build.bat amd64
    move gophernotes.exe %GOPATH%\bin
    copy lib-amd64\libzmq.dll %GOPATH%\bin
    
    REM Build x86 version.
    build.bat 386
    move gophernotes.exe %GOPATH%\bin
    copy lib-386\libzmq.dll %GOPATH%\bin
    
  2. Copy the kernel config:

    mkdir %APPDATA%\jupyter\kernels\gophernotes
    xcopy %GOPATH%\src\github.com\gopherdata\gophernotes\kernel %APPDATA%\jupyter\kernels\gophernotes /s
    

    Note, if you have the JUPYTER_PATH environmental variable set or if you are using an older version of Jupyter, you may need to copy this kernel config to another directory. You can check which directories will be searched by executing:

    jupyter --data-dir
    
  3. Update %APPDATA%\jupyter\kernels\gophernotes\kernel.json with the FULL PATH to your gophernotes.exe (in %GOPATH%\bin), unless it's already on the PATH. For example:

    {
        "argv": [
          "C:\\gopath\\bin\\gophernotes.exe",
          "{connection_file}"
          ],
        "display_name": "Go",
        "language": "go",
        "name": "go"
    }
    

Docker

You can try out or run Jupyter + gophernotes without installing anything using Docker. To run a Go notebook that only needs things from the standard library, run:

$ docker run -it -p 8888:8888 gopherdata/gophernotes

Or to run a Go notebook with access to common Go data science packages (gonum, gota, golearn, etc.), run:

$ docker run -it -p 8888:8888 gopherdata/gophernotes-ds

In either case, running this command should output a link that you can follow to access Jupyter in a browser. Also, to save notebooks to and/or load notebooks from a location outside of the Docker image, you should utilize a volume mount. For example:

$ docker run -it -p 8888:8888 -v /path/to/local/notebooks:/path/to/notebooks/in/docker gopherdata/gophernotes

Getting Started

Jupyter

  • If you completed one of the local installs above (i.e., not the Docker install), start the jupyter notebook server:

    jupyter notebook
    
  • Select Go from the New drop down menu.

  • Have fun!

nteract

  • Launch nteract.

  • From the nteract menu select Language -> Go.

  • Have fun!

Limitations

gophernotes uses gomacro under the hood to evaluate Go code interactively. You can evaluate most any Go code with gomacro, but there are some limitation, which are discussed in further detail here. Most noteably, gophernotes does NOT support:

  • third party packages when running natively on Windows - This is a current limitation of the Go plugin package.
  • some corner cases on interpreted interfaces, as interface -> interface type switch and type assertion, are not implemented yet.
  • conversion from typed constant to interpreted interface is not implemented. Workaround: assign the constant to a variable, then convert the variable to the interpreted interface type.
  • goto is only partially implemented.
  • out-of-order code in the same cell is supported, but not heavily tested. It has some known limitations for composite literals.

Troubleshooting

gophernotes not found

Depending on your environment, you may need to manually change the path to the gophernotes executable in kernel/kernel.json before copying it to ~/.local/share/jupyter/kernels/gophernotes. You can put the full path to the gophernotes executable here, and you shouldn't have any further issues.

"Kernel error" in a running notebook

Traceback (most recent call last):
  File "/usr/local/lib/python2.7/site-packages/notebook/base/handlers.py", line 458, in wrapper
    result = yield gen.maybe_future(method(self, *args, **kwargs))
  File "/usr/local/lib/python2.7/site-packages/tornado/gen.py", line 1008, in run
    value = future.result()
  ...
  File "/usr/local/Cellar/python/2.7.11/Frameworks/Python.framework/Versions/2.7/lib/python2.7/subprocess.py", line 1335, in _execute_child
    raise child_exception
OSError: [Errno 2] No such file or directory

Stop jupyter, if it's already running.

Add a symlink to /go/bin/gophernotes from your path to the gophernotes executable. If you followed the instructions above, this will be:

sudo ln -s $HOME/go/bin/gophernotes /go/bin/gophernotes

Restart jupyter, and you should now be up and running.