PyO3 Playground

This serves as a personal development environment to tinker around with PyO3.

I'm mainly focusing on implementing support for Python sub-interpreters at the moment.

Overview

This repository consists of two parts, a Python module with bindings to PyO3 and a rather primitive C++ application that uses

The Python Module: playground

playground is a Python module with bindings to PyO3 that contains functions, objects, etc. that bind to whatever PyO3 code I'm testing at the moment. The sources of this module can be found in src.

The C++ Application

This (yet to be named) C++ application uses Python's C API to play around with the stuff that's in the playground module.

In the future, this application might support a REPL of some sort, but for the time being it just does whatever I want to experiment with.

Okay but why is it in C++ and not Rust?

Well, initially I thought it would be easier to just use C or C++ to quickly set up something that allows me to mess around with Python's C API - and it was! Eventually I decided to use cmake to "make my life easier" which ended up in my life being made harder.

Either way, it now builds and it's (more or less) easy to use, so I'm reluctant to rewrite the whole thing.

Instructions For The Curious

Note: Open an issue if you're actually interested in using this repository to play around with PyO3, too. These instructions may not be complete; right now, they've only been tested on my machine.

Prerequisites

• Be on some Linux distribution of your choice (WSL should probably work too)
• Python, preferably via pyenv
• GNU Make
• cmake (optionally with ctest)
• Rust
• Make sure you've cloned this repository with its submodules:

  git clone --recurse-submodules git@github.com:Aequitosh/pyo3-playground.git

• Alternatively, if you've already cloned it, run:

  git submodule update --init --recursive

Build Steps

Note: This was tested using Python 3.11. Older or newer Python versions might or might not work. Good luck!

1. Prepare and activate a virtual environment. I highly recommend using pyenv to install your desired Python version in order to not mess with your system's Python installation.

2. Congratulations, you can now build the playground module from the repo's directory:

   make install

   Yeah, it's suprisingly easy, I know!

3. To test the module, import it in the python REPL:

   >>> import playground
   >>> playground.hello_world()
   'Hello, World!'

4. After confirming that the module builds and runs correctly, you may also build the C++ application:

   make interpreter-debug

   make interpreter-release

   Or, to build both:

   make interpreter

5. Once your desired targets are build successfully, you should be able to run either of them:

   ./interpreter/build/debug/test-interpreter

   ./interpreter/build/release/test-interpreter

Once you completed the above steps and everything's built, can also run the (currently not very useful) tests for either build variant. The tests are built automatically for both builds.

6. Run the test executable directly:

   ./build/debug/tests/run_tests

   ./build/release/tests/run_tests

7. You may also run the tests with ctest:

   ctest --test-dir ./build/debug

   ctest --test-dir ./build/release

Working with the PyO3 source locally

If you're working on the PyO3 sources yourself and want to test your changes using this repository, you can point cargo to your local sources:

1. Enter the src/rust/ directory

   cd src/rust/

2. Uncomment the line regarding pyo3 in Cargo.toml and change the path to point to the directory of your local pyo3 sources
3. Run cargo update
4. cargo should now have updated all PyO3-related dependencies accordingly. You can then rebuild the Python module like above:

   cd ../..

   pip install -e .

License

Even though this is just a (more or less literal) playground for PyO3, this project is licensed under the AGPL-3.0.

Should this at any point become more relevant (which I doubt) I might adapt the license correspondingly.