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.

Compile flags

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

• --std=c++17 flag must be set
• Exception must be enabled
• RTTI is not required

!!! For maximum performance, we recommend to use clang++ with -O2 flag. !!!

Example

#include "pocketpy.h"

using namespace pkpy;

int main(){
    // Create a virtual machine
    VM* vm = new VM();
    
    // Hello world!
    vm->exec("print('Hello world!')", "main.py", EXEC_MODE);

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

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

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.

License

pkpy is licensed under the MIT License.