pocketpy: python interpreter in 1 file

pkpy is a lightweight(~10000 LOC) Python interpreter for game scripting, built on C++17 with STL.

It aims to be an alternative to lua for game scripting, with elegant syntax, powerful features and competitive performance. pkpy is extremely easy to embed via a single header file pocketpy.h, without external dependencies.

Please see https://pocketpy.dev for details or try Live Demo.

Quick Start

Download the pocketpy.h on our GitHub Release page. And #include it in your project.

You can also use cmake to build it from source. See CMakeLists.txt for details. These variables can be set to control the build process:

PK_BUILD_STATIC_LIB - Build the static library
PK_BUILD_SHARED_LIB - Build the shared library

If you are working with Unity Engine, you can download our plugin PocketPython on the Asset Store.

Compile Flags

To compile it with your project, these flags must be set:

--std=c++17 flag must be set
Exception must be enabled

Example

#include "pocketpy.h"

using namespace pkpy;

int main(){
    // Create a virtual machine
    VM* vm = new VM();

    // Hello world!
    vm->exec("print('Hello world!')");

    // Create a list
    vm->exec("a = [1, 2, 3]");

    // Eval the sum of the list
    PyObject* result = vm->eval("sum(a)");
    std::cout << CAST(int, result);   // 6

    // Bindings
    vm->bind(vm->_main, "add(a: int, b: int)",
      [](VM* vm, ArgsView args){
        int a = CAST(int, args[0]);
        int b = CAST(int, args[1]);
        return VAR(a + b);
      });

    // Call the function
    PyObject* f_add = vm->_main->attr("add");
    result = vm->call(f_add, VAR(3), VAR(7));
    std::cout << CAST(int, result);   // 10

    // Dispose the virtual machine
    delete vm;
    return 0;
}

Features

Check this Cheatsheet for a quick overview of the supported features.

Name	Example	Supported
If Else	`if..else..elif`	YES
Loop	`for/while/break/continue`	YES
Function	`def f(x,*args,y=1):`	YES
Subclass	`class A(B):`	YES
List	`[1, 2, 'a']`	YES
ListComp	`[i for i in range(5)]`	YES
Slice	`a[1:2], a[:2], a[1:]`	YES
Tuple	`(1, 2, 'a')`	YES
Dict	`{'a': 1, 'b': 2}`	YES
F-String	`f'value is {x}'`	YES
Unpacking	`a, b = 1, 2`	YES
Star Unpacking	`a, *b = [1, 2, 3]`	YES
Exception	`raise/try..catch`	YES
Dynamic Code	`eval()/exec()`	YES
Reflection	`hasattr()/getattr()/setattr()`	YES
Import	`import/from..import`	YES
Context Block	`with <expr> as <id>:`	YES
Type Annotation	`def f(a:int, b:float=1)`	YES
Generator	`yield i`	YES
Decorator	`@cache`	YES

Contribution

All kinds of contributions are welcome.

Submit a Pull Request
- fix a bug
- add a new feature
Open an Issue
- any suggestions
- any questions

Check our Coding Style Guide if you want to contribute C++ code.

Reference

cpython

The official implementation of Python programming language.
byterun

An excellent learning material. It illustrates how Python's virtual machine works.
box2d

The world's best 2D physics engine, written by Erin Catto. box2d now becomes a built-in module in pkpy v1.1.3 and later.

Star History

License

MIT License

sanko/pocketpy