Metadata-Version: 2.4
Name: native-jit
Version: 0.1.0
Summary: Cython-powered JIT decorator for Python functions and classes
Home-page: https://github.com/fanbozhou/native_jit
Author: Fanbo Zhou
Keywords: jit cython performance decorator
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: Cython>=3.0
Requires-Dist: setuptools>=65
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# native_jit

`native_jit` is a Cython-powered JIT decorator for Python functions and classes.

It tries to compile decorated objects for speed and automatically falls back to the original Python object if compilation is not available in the current environment.

## Features

- `@jit` for functions and classes
- Cython compilation pipeline (`.pyx -> .c -> extension module`)
- In-memory and disk cache for compiled modules
- Concurrent compilation deduplication
- Cross-platform compiler detection (`CC` / system compiler fallback)
- Safe fallback mode: no hard failure when compilation is unavailable

## Install

```bash
pip install native-jit
```

For local development:

```bash
pip install -e .[dev]
```

## Quick Start

```python
from native_jit import jit

@jit
def add(a: int, b: int) -> int:
    return a + b

print(add(1, 2))
```

Advanced usage:

```python
from native_jit import jit

@jit(nopython=True)
def fast_sum(n: int) -> int:
    s = 0
    for i in range(n):
        s += i
    return s

print(fast_sum(1000000))
```

## API

- `jit(...)`: decorate function/class/method
- `jit.from_pyx(func_name, pyx_code, **kwargs)`: compile raw Cython source
- `jit.warmup()`: warm up compiler flag probing
- `jit.cache_info()`: inspect cache and compiler flags
- `jit.clear_cache(disk=False)`: clear in-memory/disk cache

## Notes on Compilers

Cython does not bundle a C compiler. A system C toolchain is still required for native compilation.

`native_jit` detects compiler command from:

1. `CC` environment variable
2. Python build configuration (`sysconfig`)
3. common fallback commands (`cc`, `clang`, `gcc`, `cl`)

If no compiler is available, decorated code still runs with Python fallback mode.

## Publish to GitHub

```bash
git init
git add .
git commit -m "chore: prepare package for release"
git branch -M main
git remote add origin https://github.com/<your-user>/<your-repo>.git
git push -u origin main
```

## Build and Publish to PyPI

1. Create PyPI account and API token.
2. Export token:

```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<pypi-token>
```

3. Build package:

```bash
python -m build
```

4. Verify artifacts:

```bash
python -m twine check dist/*
```

5. Upload to TestPyPI (recommended first):

```bash
python -m twine upload --repository testpypi dist/*
```

6. Upload to PyPI:

```bash
python -m twine upload dist/*
```

## Verify Install

```bash
pip install native-jit
python -c "from native_jit import jit; print(callable(jit))"
```
