luxolus/pyo3
2
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge pull request #476 from Alexander-N/sync-readme

Browse source 
Bring README.md and get_started.md back in sync
This commit is contained in:
konstin 2019-05-12 15:02:25 +02:00 committed by GitHub
parent e7287bcf9a d64ba9fa3a
commit f48295c7ac
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -6,7 +6,7 @@
[![crates.io](http://meritbadge.herokuapp.com/pyo3)](https://crates.io/crates/pyo3)
[![Join the dev chat](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/PyO3/Lobby)
[Rust](http://www.rust-lang.org/) bindings for [Python](https://www.python.org/). This includes running and interacting with python code from a rust binaries as well as writing native python modules.
[Rust](http://www.rust-lang.org/) bindings for [Python](https://www.python.org/). This includes running and interacting with Python code from a Rust binary, as well as writing native Python modules.
* User Guide: [stable](https://pyo3.rs) | [master](https://pyo3.rs/master)
@ -16,12 +16,12 @@ A comparison with rust-cpython can be found [in the guide](https://pyo3.rs/maste
## Usage
PyO3 supports Python 3.5 and up. The minimum required rust version is 1.34.0-nightly 2019-02-06.
PyO3 supports Python 3.5 and up. The minimum required Rust version is 1.34.0-nightly 2019-02-06.
PyPy is also supported (via cpyext) for Python 3.5 only, targeted PyPy version is 7.0.0.
Please refer to the guide for installation instruction against PyPy.
You can either write a native Python module in rust or use Python from a Rust binary.
You can either write a native Python module in Rust, or use Python from a Rust binary.
However, on some OSs, you need some additional packages. E.g. if you are on *Ubuntu 18.04*, please run
@ -31,7 +31,7 @@ sudo apt install python3-dev python-dev
## Using Rust from Python
PyO3 can be used to generate a native python module.
PyO3 can be used to generate a native Python module.
**`Cargo.toml`**
@ -71,7 +71,7 @@ fn string_sum(py: Python, m: &PyModule) -> PyResult<()> {
}
```
On Windows and Linux, you can build normally with `cargo build --release`. On MacOS, you need to set additional linker arguments. One option is to compile with `cargo rustc --release -- -C link-arg=-undefined -C link-arg=dynamic_lookup`, the other is to create a `.cargo/config` with the following content:
On Windows and Linux, you can build normally with `cargo build --release`. On macOS, you need to set additional linker arguments. One option is to compile with `cargo rustc --release -- -C link-arg=-undefined -C link-arg=dynamic_lookup`, the other is to create a `.cargo/config` with the following content:
```toml
[target.x86_64-apple-darwin]
@ -83,18 +83,18 @@ rustflags = [
For developing, you can copy and rename the shared library from the target folder: On MacOS, rename `libstring_sum.dylib` to `string_sum.so`, on Windows `libstring_sum.dll` to `string_sum.pyd` and on Linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
To build, test and publish your crate as Python module, you can use [pyo3-pack](https://github.com/PyO3/pyo3-pack) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](examples/word-count), while pyo3-pack should work on your crate without any configuration.
To build, test and publish your crate as a Python module, you can use [pyo3-pack](https://github.com/PyO3/pyo3-pack) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](examples/word-count), while pyo3-pack should work on your crate without any configuration.
## Using python from rust
## Using Python from Rust
Add `pyo3` this to your `Cargo.toml`:
Add `pyo3` to your `Cargo.toml` like this:
```toml
[dependencies]
pyo3 = "0.7.0-alpha.1"
```
Example program displaying the value of `sys.version`:
Example program displaying the value of `sys.version` and the current user name:
```rust
use pyo3::prelude::*;

24
guide/src/get_started.md
View file

@ -6,32 +6,34 @@
* API Documentation: [master](https://pyo3.rs/master/doc)
A comparison with rust-cpython can be found [in the guide](https://pyo3.rs/master/rust-cpython.html).
A comparison with rust-cpython can be found [in the guide](https://pyo3.rs/master/rust_cpython.html).
## Usage
PyO3 supports Python 3.5 and up. The minimum required Rust version is 1.34.0-nightly 2019-02-06.
PyPy is also supported (via cpyext) for Python 3.5 only, targeted PyPy version is 7.0.0.
Please refer to the guide for installation instruction against PyPy.
You can either write a native Python module in Rust, or use Python from a Rust binary.
On some OSs, you need some additional packages.
E.g. if you are on Ubuntu 18.04, please run
However, on some OSs, you need some additional packages. E.g. if you are on *Ubuntu 18.04*, please run
```bash
sudo apt install python3-dev python-dev
```
## Using rust from python
## Using Rust from Python
PyO3 can be used to generate a native Python module.
**`Cargo.toml`:**
**`Cargo.toml`**
```toml
[package]
name = "string-sum"
version = "0.1.0"
edition = "2018"
[lib]
name = "string_sum"
@ -73,7 +75,7 @@ rustflags = [
]
```
For developing, you can copy and rename the shared library from the target folder: On macOS, rename `libstring_sum.dylib` to `string_sum.so`, on windows `libstring_sum.dll` to `string_sum.pyd` and on linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
For developing, you can copy and rename the shared library from the target folder: On MacOS, rename `libstring_sum.dylib` to `string_sum.so`, on Windows `libstring_sum.dll` to `string_sum.pyd` and on Linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
To build, test and publish your crate as a Python module, you can use [pyo3-pack](https://github.com/PyO3/pyo3-pack) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](examples/word-count), while pyo3-pack should work on your crate without any configuration.
@ -83,7 +85,7 @@ Add `pyo3` to your `Cargo.toml` like this:
```toml
[dependencies]
pyo3 = "0.6"
pyo3 = "0.7.0-alpha.1"
```
Example program displaying the value of `sys.version` and the current user name:
@ -97,11 +99,9 @@ fn main() -> PyResult<()> {
let py = gil.python();
let sys = py.import("sys")?;
let version: String = sys.get("version")?.extract()?;
let locals = [("os", py.import("os")?)].into_py_dict(py);
let user: String = py.eval("os.getenv('USER') or os.getenv('USERNAME')",
None, Some(&locals))?.extract()?;
let code = "os.getenv('USER') or os.getenv('USERNAME') or 'Unknown'";
let user: String = py.eval(code, None, Some(&locals))?.extract()?;
println!("Hello {}, I'm Python {}", user, version);
Ok(())
}