Metadata-Version: 2.4
Name: rpynative
Version: 0.1.2
Summary: Use R packages natively in Python, no R knowledge required.
Author-email: DevWebWacky <uwakmfon31@gmail.com>
Maintainer-email: DevWebWacky <uwakmfon31@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DevWebWacky/rpynative
Project-URL: Repository, https://github.com/DevWebWacky/rpynative
Project-URL: Issues, https://github.com/DevWebWacky/rpynative/issues
Keywords: r,rpy2,interoperability,statistics,data-science,cran,bridge
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rpy2>=3.6.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Dynamic: license-file

<p align="center">
  <img src="logo.svg" alt="rpynative logo" width="160">
</p>

<h1 align="center">rpynative</h1>

<p align="center">
  <a href="https://pypi.org/project/rpynative/"><img src="https://img.shields.io/pypi/v/rpynative" alt="PyPI Version"></a>
  <a href="https://pypi.org/project/rpynative/"><img src="https://img.shields.io/pypi/pyversions/rpynative" alt="Python Versions"></a>
  <a href="https://pypi.org/project/rpynative/"><img src="https://img.shields.io/pypi/l/rpynative" alt="License"></a>
</p>

**Use R packages natively in Python, no R knowledge required.**

`rpynative` lets Python developers load and use R packages as if they were normal Python packages. No R syntax, no manual object conversion, and unlike other R-Python bridges, `rpynative` even supports real IDE autocomplete for R functions.

> ⚠️ **Requires R to be installed on your system.** `rpynative` is not a pure-Python package, it's built on [rpy2](https://rpy2.github.io/), meaning the real chain is:
>
> `Python → rpynative → rpy2 → R`
>
> `pip install rpynative` will succeed even without R installed, but using it will fail until R is available on your system. See [Requirements](#requirements) below before you start.

## Why not just use rpy2?

`rpynative` is built on top of [rpy2](https://rpy2.github.io/), rpy2 is the engine, `rpynative` is what a Python-only developer actually experiences using it. rpy2 exposes R concepts directly (R vectors, manual converter contexts, raw R objects), it's a bridge for people who already know R. `rpynative` is built for people who don't, and want R's tools to feel like native Python.

Specifically, `rpynative` adds:

- **Zero R knowledge required** : pass plain Python lists/DataFrames, get back plain Python dicts/DataFrames
- **Auto-install** : missing R packages are installed from CRAN automatically
- **Preserved native reporting** : R's own nicely-formatted print output (e.g. a package's custom statistical report) is captured and shown, not just raw data
- **Object-chaining and generic dispatch handled transparently**: things like `ggplot2`'s `+` syntax, or `predict()` working across any model type, just work
- **Auto-generated IDE stubs**: real autocomplete and parameter hints in editors like VS Code for a dynamically loaded R package's functions
- **Round-tripping of complex objects**: trained models, plots, and other R objects can be passed back into other R functions without losing their identity

## Example

```python
import rpynative

stats = rpynative.load("stats")
result = stats.mean([2, 4, 6, 8, 10])
print(result)  # 6.0
```

### Real statistical reports, not raw R objects

```python
statease = rpynative.load("statease")
result = statease.ttest_interpret([88, 92, 79, 85, 90], [70, 65, 72, 68, 74])

print(result)
# -- statease T-Test Report ----------------------------------------
#   Test         : Independent Samples T-Test
#   ...

print(result['p_val'])  # still works like a normal dict
```

### Formulas, DataFrames, matrices, and S4 objects

```python
import pandas as pd

data = pd.DataFrame({"score": [...], "group": [...]})
result = statease.anova_interpret("score ~ group", data=data)
print(result)
```

### Visual/plotting packages

```python
ggplot2 = rpynative.load("ggplot2")

plot = ggplot2.ggplot(data, ggplot2.aes(x="x", y="y")) + ggplot2.geom_point()
ggplot2.ggsave("plot.png", plot=plot)
```

### Real machine learning workflows

```python
randomForest = rpynative.load("randomForest")

model = randomForest.randomForest("outcome ~ feature1 + feature2", data=data)
predictions = randomForest.predict(model, new_data)
```

### IDE autocomplete for R functions

```python
from rpynative.core import load_typed
from rpynative.stubs.statease import StateaseStub

statease = load_typed("statease", StateaseStub)
statease.  # <- VS Code shows real autocomplete here
```

**Note:** autocomplete currently requires generating a stub once per package (`rpynative.stub_generator.generate_stub("packagename")`). Automatic stub generation on `load()` is a planned improvement.

## Features

- Load any R package with one line, auto-installs it from CRAN if missing
- Automatic conversion: lists, numbers, pandas DataFrames, R formulas, matrices (as numpy arrays), S4 objects (as dicts)
- Rich report output preserved alongside clean programmatic access
- Object-chaining support (`+` operator) for packages like `ggplot2`
- Generic function dispatch (`predict`, `summary`, etc.) works across any model type
- Built-in R datasets accessible directly as pandas DataFrames
- Auto-generated IDE stubs for real autocomplete
- Clean Python errors instead of raw R tracebacks

## Requirements

- Python 3.9+
- **R installed and available on your system**, download from [r-project.org](https://www.r-project.org/) if you don't have it
- R must be discoverable on your system PATH (on Windows, this sometimes requires adding R's `bin` folder to PATH manually after installing R, see [R's Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html) if `R --version` doesn't work in your terminal)

Individual R packages (like `stats`, `ggplot2`, etc.) do **not** need to be pre-installed, `rpynative` installs them automatically from CRAN the first time you load them.

## Installation

```bash
pip install rpynative
```

Then verify your R installation is discoverable:

```bash
python -c "import rpynative; v = rpynative.load('base').getRversion(); print('R version:', '.'.join(str(x) for x in v))"
```

If this raises an error instead of printing an R version string, `rpynative` is installed correctly, but R itself isn't discoverable yet, check the PATH note above.

## Installation

```bash
pip install rpynative
```

## Known limitations

- IDE autocomplete requires a manual one-time stub generation step per package
- Not yet tested against every R object type across all ~20,000 CRAN packages, common types (S3, S4, matrices, data.frames, formulas) are covered and tested; more exotic types may surface new edge cases
- Windows, macOS, and Linux should all work (R + rpy2 support all three), but development and testing so far has been primarily on Windows

## Status

Actively developed. Core engine, report handling, plotting support, matrix/S4 support, and IDE autocomplete are all working and tested against real published R packages, including real machine learning workflows.

## Author

Built by [DevWebWacky](https://github.com/DevWebWacky), also the author of the [statease](https://cran.r-project.org/package=statease) R package used throughout development and testing, and [triageR](https://cran.r-project.org/package=triageR)

## License

MIT
