pocketpy

pocketpy: python interpreter in 1 file

English | 简体中文

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.

License

pkpy is licensed under the MIT License.