Crate cpython[−][src]
Rust bindings to the Python interpreter.
Ownership and Lifetimes
In Python, all objects are implicitly reference counted.
In rust, we will use the PyObject
type to represent a reference to a Python object.
The method clone_ref()
(from trait PyClone
) can be used to create additional
references to the same Python object.
Because all Python objects potentially have multiple owners, the concept of Rust mutability does not apply to Python objects. As a result, this API will allow mutating Python objects even if they are not stored in a mutable Rust variable.
The Python interpreter uses a global interpreter lock (GIL)
to ensure thread-safety.
This API uses a zero-sized struct Python<'p>
as a token to indicate
that a function can assume that the GIL is held.
You obtain a Python
instance by acquiring the GIL,
and have to pass it into all operations that call into the Python runtime.
Python 2.7
The library will use the python3 bindings by default. To use the python2 bindings
you must specific the python27
feature explicitly in your Cargo.toml
.
[dependencies.cpython] version = "*" default-features = false features = ["python27-sys"]
Error Handling
The vast majority of operations in this library will return PyResult<...>
.
This is an alias for the type Result<..., PyErr>
.
A PyErr
represents a Python exception. Errors within the rust-cpython library are
also exposed as Python exceptions.
Example
extern crate cpython; use cpython::{Python, PyDict, PyResult}; fn main() { let gil = Python::acquire_gil(); hello(gil.python()).unwrap(); } fn hello(py: Python) -> PyResult<()> { let sys = py.import("sys")?; let version: String = sys.get(py, "version")?.extract(py)?; let locals = PyDict::new(py); locals.set_item(py, "os", py.import("os")?)?; let user: String = py.eval("os.getenv('USER') or os.getenv('USERNAME')", None, Some(&locals))?.extract(py)?; println!("Hello {}, I'm Python {}", user, version); Ok(()) }
Re-exports
pub use py_class::CompareOp; |
Modules
argparse |
This module contains logic for parsing a python argument list.
See also the macros |
buffer | |
exc |
This module contains the python exception types. |
py_class |
Macros
py_argparse |
This macro is used to parse a parameter list into a set of variables. |
py_class |
Defines new python extension class.
A |
py_exception |
Defines a new exception type. |
py_fn |
Creates a Python callable object that invokes a Rust function. |
py_module_initializer | |
pyobject_newtype |
Structs
GILGuard |
RAII type that represents the Global Interpreter Lock acquisition. |
GILProtected |
Mutex-like wrapper object for data that is protected by the Python GIL. |
NoArgs |
An empty struct that represents the empty argument list.
Corresponds to the empty tuple |
PyBool |
Represents a Python |
PyBytes |
Represents a Python byte string.
Corresponds to |
PyDict |
Represents a Python |
PyErr |
Represents a Python exception that was raised. |
PyFloat |
Represents a Python |
PyInt |
In Python 2.x, represents a Python |
PyIterator |
A python iterator object. |
PyList |
Represents a Python |
PyLong |
In Python 2.x, represents a Python |
PyModule |
Represents a Python module object. |
PyObject |
Represents a reference to a Python object. |
PySequence |
Represents a reference to a python object supporting the sequence protocol. |
PyString |
Represents a Python string.
Corresponds to |
PyTuple |
Represents a Python tuple object. |
PyType |
Represents a reference to a Python type object. |
PyUnicode |
Represents a Python string.
Corresponds to |
Python |
Marker type that indicates that the GIL is currently held. |
PythonObjectDowncastError |
Enums
PyStringData |
Enum of possible Python string representations. |
Traits
FromPyObject |
FromPyObject is implemented by various types that can be extracted from a Python object. |
ObjectProtocol |
Trait that contains methods |
PyClone | |
PyDrop | |
PythonObject |
Trait implemented by all Python object types. |
PythonObjectWithCheckedDowncast |
Trait implemented by Python object types that allow a checked downcast. |
PythonObjectWithTypeObject |
Trait implemented by Python object types that have a corresponding type object. |
RefFromPyObject | |
ToPyObject |
Conversion trait that allows various objects to be converted into Python objects. |
Functions
prepare_freethreaded_python |
Prepares the use of Python in a free-threaded context. |
Type Definitions
PyResult |
Represents the result of a Python call. |
Py_hash_t | |
Py_ssize_t |