pocketpy: python interpreter in 1 file

pkpy is a lightweight(~15K 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.

Supported Platforms

pkpy should work on any platform with a C++17 compiler. These platforms are officially tested.

Windows 64-bit
Linux 64-bit / 32-bit
macOS 64-bit
Android 64-bit / 32-bit
iOS 64-bit
Emscripten 32-bit
Raspberry Pi OS 64-bit

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

Compile Flags

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

--std=c++17 flag must be set
Exception must be enabled
For MSVC, /utf-8 flag must be set

For development build, use this snippet.

# prerequisites
pip install cmake
# build the repo
python cmake_build.py
# unittest
python scripts/run_tests.py

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 << py_cast<int>(vm, result);   // 6

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

    // Call the function
    PyObject* f_add = vm->_main->attr("add");
    result = vm->call(f_add, py_var(vm, 3), py_var(vm, 7));
    std::cout << py_cast<int>(vm, 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`	✅
Loop	`for/while/break/continue`	✅
Function	`def f(x,*args,y=1):`	✅
Subclass	`class A(B):`	✅
List	`[1, 2, 'a']`	✅
ListComp	`[i for i in range(5)]`	✅
Slice	`a[1:2], a[:2], a[1:]`	✅
Tuple	`(1, 2, 'a')`	✅
Dict	`{'a': 1, 'b': 2}`	✅
F-String	`f'value is {x}'`	✅
Unpacking	`a, b = 1, 2`	✅
Star Unpacking	`a, *b = [1, 2, 3]`	✅
Exception	`raise/try..catch`	✅
Dynamic Code	`eval()/exec()`	✅
Reflection	`hasattr()/getattr()/setattr()`	✅
Import	`import/from..import`	✅
Context Block	`with <expr> as <id>:`	✅
Type Annotation	`def f(a:int, b:float=1)`	✅
Generator	`yield i`	✅
Decorator	`@cache`	✅

Performance

Currently, pkpy is as fast as cpython 3.9. Performance results for cpython 3.9 are applicable to for pkpy.

See https://pocketpy.dev/performance/ for details.

And these are the results of the primes benchmark on Intel i5-12400F, WSL (Ubuntu 20.04 LTS), which roughly reflects the performance among c++, lua, pkpy and cpython.

name	version	time	file
c++	gnu++11	`0.104s ■□□□□□□□□□□□□□□□`	benchmarks/primes.cpp
lua	5.3.3	`1.576s ■■■■■■■■■□□□□□□□`	benchmarks/primes.lua
pkpy	1.2.7	`2.385s ■■■■■■■■■■■■■□□□`	benchmarks/primes.py
cpython	3.8.10	`2.871s ■■■■■■■■■■■■■■■■`	benchmarks/primes.py

Used By

	Description
TIC-80	TIC-80 is a fantasy computer for making, playing and sharing tiny games.
ct-py	Ct.py🥕 is cross-platform 2D game framework built on raylib and imgui.
MiniPythonIDE	A python ide base on pocketpy
py-js	Python3 externals for Max / MSP
crescent	Crescent is a cross-platform 2D fighting and beat-em-up game engine.

Submit a pull request to add your project here.

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

If you find pkpy useful, consider star this repository (●'◡'●)

Sponsor me

You can sponsor me via these ways.

Your sponsorship will help me develop this project continuously.

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.