# pocketpy: portable python 3.x interpreter
pocketpy is a portable Python 3.x interpreter, written in C11.
It aims to be an alternative to Lua for game scripting, with elegant syntax, powerful features and competitive performance.
pocketpy has no dependencies other than the C standard library, which can be easily integrated into your C/C++ project.
Developers are able to write Python bindings via C-API or pybind11 compatible interfaces.
Please see https://pocketpy.dev for details and try the following resources.
+ [Live Python Demo](https://pocketpy.dev/static/web/): Run Python code in your browser
+ [Live C Examples](https://pocketpy.github.io/examples/): Explore C-APIs in your browser
+ [Godot Extension](https://github.com/pocketpy/godot-pocketpy): Use pocketpy in Godot Engine
+ [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=pocketpy.pocketpy): Debug and profile pocketpy scripts in VSCode
+ [Flutter Plugin](https://pub.dev/packages/pocketpy): Use pocketpy in Flutter apps
+ [Raylib Bindings](https://github.com/pocketpy/raylib-bindings): Use raylib with pocketpy
## Supported Platforms
pkpy should work on any platform with a C11 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
+ [Luckfox Pico SDK](https://github.com/LuckfoxTECH/luckfox-pico) 32-bit
On Windows platform, only MSVC compiler is officially supported.
## Quick Start
You have two options to integrate pkpy into your project.
#### Use CMake (Recommended)
Clone the whole repository as a submodule into your project,
In your CMakelists.txt, add the following lines:
```cmake
add_subdirectory(pocketpy)
target_link_libraries( pocketpy)
```
See [CMakeLists.txt](https://github.com/pocketpy/pocketpy/blob/main/CMakeLists.txt) for details.
It is safe to use `main` branch in production if CI badge is green.
#### Use the single header file
Download the `pocketpy.h` and `pocketpy.c` on our [GitHub Release](https://github.com/pocketpy/pocketpy/releases) page.
And `#include` it in your project.
### Compile Flags
To compile it with your project, these flags must be set:
+ `--std=c11` flag must be set
+ For MSVC, `/utf-8` and `/experimental:c11atomics` flag must be set
+ `NDEBUG` macro should be defined for release build, or you will get poor performance
For amalgamated build, run `python amalgamate.py` to generate `pocketpy.c` and `pocketpy.h` in `amalgamated/` directory.
### Example
```
…
```
## 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..except..` | ✅ |
| Dynamic Code | `eval()/exec()` | ✅ |
| Reflection | `hasattr()/getattr()/setattr()` | ✅ |
| Import | `import/from..import` | ✅ |
| Context Block | `with as :` | ✅ |
| Type Annotation | `def f(a:int, b:float=1)` | ✅ |
| Generator | `yield i` | ✅ |
| Decorator | `@cache` | ✅ |
| Match Case | `match code: case 200:` | ✅ |
## 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](https://github.com/pocketpy/pocketpy/blob/9481d653b60b81f4590a4d48f2be496f6962261e/benchmarks/primes.cpp) |
| lua | 5.3.3 | `1.576s ■■■■■■■■■□□□□□□□` | [benchmarks/primes.lua](https://github.com/pocketpy/pocketpy/blob/9481d653b60b81f4590a4d48f2be496f6962261e/benchmarks/primes.lua) |
| pkpy | 1.2.7 | `2.385s ■■■■■■■■■■■■■□□□` | [benchmarks/primes.py](https://github.com/pocketpy/pocketpy/blob/9481d653b60b81f4590a4d48f2be496f6962261e/benchmarks/primes.py) |
| cpython | 3.8.10 | `2.871s ■■■■■■■■■■■■■■■■` | [benchmarks/primes.py](https://github.com/pocketpy/pocketpy/blob/9481d653b60b81f4590a4d48f2be496f6962261e/benchmarks/primes.py) |
## Used By
| | Description |
|-----------------------------------------------------------------|--------------------------------------------------------------------------|
| [Tesselmax.EM](https://fdtd.io) | Distributed electromagnetic field simulator for silicon photonics and RF/interconnect design. |
| [godot-pocketpy](https://github.com/pocketpy/godot-pocketpy) | Godot extension for using pocketpy in Godot Engine. |
| [TIC-80](https://github.com/nesbox/TIC-80) | TIC-80 is a fantasy computer for making, playing and sharing tiny games. |
| [py-js](https://github.com/shakfu/py-js) | Python3 externals for Max / MSP. |
| [crescent](https://github.com/chukobyte/crescent) | Crescent is a cross-platform 2D fighting and beat-em-up game engine. |
| [orxpy](https://github.com/orx/orx) | Python extension for orx engine. |
| [CANopenTerm](https://canopenterm.de/python-api) | Open-source software tool for CANopen CC networks and devices. |
Submit a pull request to add your project here.
## Contribution
All kinds of contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, build, testing, and PR guidance.
- 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 this project
You can sponsor this project via these ways.
+ [Github Sponsors](https://github.com/sponsors/blueloveTH)
+ [Buy me a coffee](https://www.buymeacoffee.com/blueloveth)
Your sponsorship will help us develop pkpy continuously.
## Premium supporter
Special thanks to our premium supporter, Tesselmax, for sponsoring the development of pocketpy.
Tesselmax builds Tesselmax.EM, a distributed electromagnetic field simulator for silicon
photonics and RF/interconnect design (FDTD, FDFD, and mode solving across GPU clusters).
Tesselmax embeds pocketpy as the scripting engine in our simulation console, so user scripts drive
geometry, materials, sources, and post-processing.
Website: [https://fdtd.io](https://fdtd.io)
## Reference
+ [cpython](https://github.com/python/cpython)
The official implementation of Python programming language.
+ [byterun](https://www.aosabook.org/en/500L/a-python-interpreter-written-in-python.html)
An excellent learning material. It illustrates how Python's virtual machine works.
## Star History
## License
[MIT License](http://opensource.org/licenses/MIT)