• Stars
    star
    838
  • Rank 54,406 (Top 2 %)
  • Language
    C++
  • License
    BSD 3-Clause "New...
  • Created almost 8 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Implementation of the Jupyter kernel protocol in C++

xeus

GithubActions Documentation Status Join the Gitter Chat

C++ implementation of the Jupyter Kernel protocol

Introduction

xeus is a library meant to facilitate the implementation of kernels for Jupyter. It takes the burden of implementing the Jupyter Kernel protocol so developers can focus on implementing the interpreter part of the kernel.

Several Jupyter kernels are built upon xeus, such as xeus-cling, a kernel for the C++ programming language, and xeus-python, an alternative Python kernel for Jupyter.

Installation

xeus has been packaged on all platforms for the mamba (or conda) package manager.

mamba install xeus -c conda-forge

Documentation

To get started with using xeus, check out the full documentation

http://xeus.readthedocs.io/

Usage

xeus enables custom kernel authors to implement Jupyter kernels more easily. It takes the burden of implementing the Jupyter Kernel protocol so developers can focus on implementing the interpreter part of the Kernel.

The easiest way to get started with a new kernel is to inherit from the base interpreter class xeus::xinterpreter and implement the private virtual methods:

  • execute_request_impl
  • complete_request_impl
  • inspect_request_impl
  • is_complete_request_impl

as seen in the documentation.

#include "xeus/xinterpreter.hpp"

#include "nlohmann/json.hpp"

using xeus::xinterpreter;

namespace nl = nlohmann;

namespace custom
{
    class custom_interpreter : public xinterpreter
    {

    public:

        custom_interpreter() = default;
        virtual ~custom_interpreter() = default;

    private:

        void configure() override;

        nl::json execute_request_impl(int execution_counter,
                                      const std::string& code,
                                      bool silent,
                                      bool store_history,
                                      const nl::json::node_type* user_expressions,
                                      bool allow_stdin) override;

        nl::json complete_request_impl(const std::string& code,
                                       int cursor_pos) override;

        nl::json inspect_request_impl(const std::string& code,
                                      int cursor_pos,
                                      int detail_level) override;

        nl::json is_complete_request_impl(const std::string& code) override;

        nl::json kernel_info_request_impl() override;
    };
}

Kernel authors can then rebind to the native APIs of the interpreter that is being interfaced, providing richer information than with the classical approach of a wrapper kernel capturing textual output.

Building from Source

xeus depends on the following libraries: nlohmann_json and xtl.

xeus xtl nlohmann json
master >=0.7.0,<0.8.0 ^3.2.0
3.x >=0.7.0,<0.8.0 ^3.2.0

Versions prior to version 3 also depend on the following libraries: ZeroMQ, cppzmq, and OpenSSL.

xeus ZeroMQ cppzmq xtl nlohmann json OpenSSL
2.4.1 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.4.0 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.3.1 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.3.0 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.2.0 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.1.1 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.1.0 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
2.0.0 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
1.0.4 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
1.0.3 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
1.0.2 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
1.0.1 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1
1.0.0 ^4.2.5 ^4.7.1 >=0.7.0,<0.8.0 ^3.2.0 ^1.0.1

On Linux platforms, xeus also requires libuuid, which is available in all linux distributions (uuid-dev on Debian).

We have packaged all these dependencies on conda-forge. The simplest way to install them is to run:

mamba install cmake pkg-config xtl nlohmann_json -c conda-forge

On Linux platforms, you will also need libuuid:

mamba install libuuid -c conda-forge

Once you have installed the dependencies, you can build and install xeus. From the build directory, run:

cmake -D CMAKE_BUILD_TYPE=Release ..
make
make install

Installing the Dependencies from Source

The dependencies can also be installed from source. Simply clone the directories and run the following cmake (cmake >= 3.8) and make instructions.

ZeroMQ

ZeroMQ is the messaging library underlying the Jupyter kernel protocol.

cmake -D WITH_PERF_TOOL=OFF -D ZMQ_BUILD_TESTS=OFF -D ENABLE_CPACK=OFF
-D CMAKE_BUILD_TYPE=Release
make
make install

OpenSSL

OpenSSL is packaged for most package managers (apt-get, rpm, mamba). We recommend making use of an off-the-shelf build of OpenSSL for your system.

For more information on building OpenSSL, check out the official OpenSSL wiki.

cppzmq

cppzmq is a header only library:

cmake -D CMAKE_BUILD_TYPE=Release
make install

json for modern cpp

nlohmann_json is a header only library

cmake
make install

xtl

xtl is a header only library:

cmake -D CMAKE_BUILD_TYPE
make install

Contributing

See CONTRIBUTING.md to know how to contribute and set up a development environment.

License

We use a shared copyright model that enables all contributors to maintain the copyright on their contributions.

This software is licensed under the BSD-3-Clause license. See the LICENSE file for details.

More Repositories

1

xeus-cling

Jupyter kernel for the C++ programming language
C++
2,682
star
2

cpp-terminal

C++ library for writing multiplatform terminal applications
C++
447
star
3

xeus-python

Jupyter kernel for the Python programming language
C++
431
star
4

xeus-sqlite

Jupyter kernel for SQLite
C++
156
star
5

xeus-sql

Jupyter kernel for SQL databases
C++
148
star
6

xwidgets

C++ backend for Jupyter interactive widgets
C++
131
star
7

xleaflet

C++ backend for the jupyter leaflet widget
C++
77
star
8

xeus-octave

Jupyter kernel for GNU Octave
Jupyter Notebook
57
star
9

xeus-lua

Jupyter kernel for the Lua programming language
C++
40
star
10

xproperty

Traitlets-like C++ properties and implementation of the observer pattern
C++
36
star
11

xeus-robot

Jupyter kernel for Robot Framework
Jupyter Notebook
30
star
12

xeus-calc

Jupyter kernel for a simple calculator
C++
17
star
13

xeus-python-wheel

Building a PyPI wheel for xeus-python
CMake
12
star
14

xena

The world needs Xena, stay tuned!
CMake
8
star
15

xeus-nelson

Jupyter kernel for Nelson
C++
7
star
16

xeus-cookiecutter

Cookiecutter for xeus-based Jupyter kernels
CMake
5
star
17

xhale

Converter from sphinx and breathe inventory files to doxygen tag files
Python
5
star
18

xeus-qt

ZeroMQ-based middleware for xeus integrated in the Qt event loop
CMake
5
star
19

xeus-wren

Jupyter kernel for the Wren programming language
C++
5
star
20

xeus-zmq

ZeroMQ-based middleware for xeus
C++
5
star
21

xcanvas

C++ back-end for ipycanvas
C++
5
star
22

robotframework-interpreter

Utilities for building a Robot Framework interpreter
Python
3
star
23

xvega-bindings

xvega bindings for xeus
C++
3
star
24

xeus-lite

Emscripten-based middleware for xeus
C++
2
star
25

xeus-python-shell

Core Python code for xeus-python
Python
2
star