Metadata-Version: 2.4
Name: small-python
Version: 0.2.0
Summary: Run Small Python, a small embeddable Python runtime, from CPython.
Author-email: Ju Lin <soasme@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/soasme/small-python
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: csrc/licenses/python.txt
License-File: csrc/licenses/unicode.txt
Dynamic: license-file

# Small Python

Small Python is a small and embeddable Python runtime. This package,
`small-python`, runs it from CPython: create isolated interpreters, run code in
them, and give that code exactly the functions, modules, and files you choose.

![logo](docs/assets/logo-sm.png)

## Features

* Small, just a few C files, no external dependencies.
* No Python Libs. Attach your own modules.
* Almost complete Python 3.15 support.
* Run code generated by AI against only the functions you expose.
* Each runtime runs in its own worker process: an engine crash raises an
  exception instead of taking down your program.
* Limits on steps, memory, time, and message size.
* Can compile Python code to executables with no external dependency.
* GC uses reference counting with cycle removal.

## Install

```sh
pip install small-python
```

Requires CPython 3.10 or newer on Linux, macOS, or Windows (x86_64).

## Example

```python
import small_python

with small_python.Runtime(step_limit=1_000_000, memory_limit=64 << 20, timeout=5) as rt:
    @rt.function
    def fetch(key, *, default=None):
        return {"answer": 42}.get(key, default)

    rt.register_module("host", {"fetch": fetch}, source="def twice(n): return n * 2")
    rt.exec("from host import twice")
    print(rt.eval("twice(fetch('answer'))"))  # 84
```

## Documentation

- [Getting started](docs/getting-started.md)
- [Embedding guide](docs/embedding.md): host functions, modules, output, files, errors
- [Limits and safety](docs/safety.md)
- [API reference](docs/api.md)
- [Development](docs/development.md): building, testing, and releasing

## Build

Requires a C11 compiler. Manage the project with [uv](https://docs.astral.sh/uv/):

```sh
uv sync --locked
uv run python -c "import small_python"
uv build
```

See [Development](docs/development.md) for tests and the release process.
