https://github.com/iplitharas/pycompile
A CLI tool for compiling and benchmarking python source code using Cython or Nuitka
https://github.com/iplitharas/pycompile
benchmark cli compiling cython nuitka pytest python
Last synced: 26 days ago
JSON representation
A CLI tool for compiling and benchmarking python source code using Cython or Nuitka
- Host: GitHub
- URL: https://github.com/iplitharas/pycompile
- Owner: iplitharas
- License: mit
- Created: 2023-02-26T11:51:00.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-27T00:09:20.000Z (4 months ago)
- Last Synced: 2025-11-01T17:13:02.532Z (3 months ago)
- Topics: benchmark, cli, compiling, cython, nuitka, pytest, python
- Language: Python
- Homepage: https://iplitharas.github.io/pycompile/
- Size: 5.41 MB
- Stars: 5
- Watchers: 0
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# pycompile
```python
""" _ _
_ __ _ _ ___ ___ _ __ ___ _ __ (_) | ___
| '_ \| | | |/ __/ _ \| '_ ` _ \| '_ \| | |/ _ \
| |_) | |_| | (_| (_) | | | | | | |_) | | | __/
| .__/ \__, |\___\___/|_| |_| |_| .__/|_|_|\___|
|_| |___/ |_|
"""
```
A CLI tool for compiling and benchmarking python source code using [Cython](https://cython.org/) or
[Nuitka](https://nuitka.net/).
[](https://github.com/iplitharas/pycompile/actions/workflows/test.yaml)
### Latest docs 📝
[here](https://iplitharas.github.io/pycompile/)
## Table of contents
1. [Installation 🔨](#installation)
2. [Compile](#compile)
3. [Benchmark](#benchmark)
4. [Dry run](#dry-run)
5. [Local-development 💻🏭](#local-development)
### Installation
```bash
pip install pycompile
```
### Compile
```bash
Usage: pycompile compile [OPTIONS]
Compile the python files using `cython` or `nuitka`.
Options:
-i, --input-path PATH Specify the file/folder input path, by
default it will exclude any `test` and
`__init__.py` files [required]
-ex, --exclude-glob-paths TEXT glob files patterns of the files to be
excluded, example: **/ignore_this_module.py
-v, --verbose verbose level
-e, --engine [cython|nuitka] CompilerWrapper to be used, defaults to:
`cython`
-cs, --clean-source Clean source (.py) files
-kb, --keep-builds Keep temporary build files
-ce, --clean-executables Clean final executables (.so) files
--help Show this message and exit.
```
```bash
pycompile compile -i your_python_files --clean-source --engine nuitka
```
 or
After the compilation the `input` dir will have the following structure.
```text
examples
├── fib.py.py
├── fib.cpython-310-darwin.so
├── test_fib.py
```
### Benchmark
```bash
Usage: pycompile benchmark [OPTIONS]
Run a memory and cpu benchmark.
Options:
-i, --input-path PATH Specify the file/folder input path
[required]
-e, --engine [cython|nuitka|both|none]
compiler wrapper(s) to be used for the
benchmark, defaults to `both`.
-t, --type [memory|cpu|both] type of benchmark to execute, defaults to
`both`.
-p, --profile_func_pattern TEXT
function name pattern for profiling,
defaults to `benchmark`. All the functions
with a name that matches this pattern will
be decorated with `@profile` from: `memory-
profiler`, in addition their module needs to
follow the pattern
(`something_prof_func_name.py` to be
excluded from compilation).
-v, --verbose verbose level
--help Show this message and exit.
```
It starts a `memory` and a `cpu` benchmark, starting with
* `python`,
* `cython` and,
* `nuitka`
```bash
pycompile benchmark -i src/examples -vvv
```
> [!IMPORTANT]
> The python package must have a `test_module.py` because both benchmark types are invoked
> with `pytest` runs
The following structure is required for the `benchmark` subcommand.
```text
module
├── sample_funcs.py # implementation
├── main.py # entrypoint with a `main` function, during compilation will be excluded
├── test_sample_funcs.py # test cases
```
### Dry run
```bash
pycompile dry_run -i ./src
```
### Local-development
For local development run the following command
```bash
make setup-local-dev
```
All available `make` commands
```bash
make help
```