[Architecture] Cover more topics and mention in Contributing
This commit is contained in:
kngwyu
parent
cca560649e
commit
78c41831f3
|
|
@ -17,29 +17,40 @@ protocol traits (e.g., `PyIterProtocol`) for supporting object protocols (i.e.,
|
|||
Since implementing `PyClass` requires lots of boilerplate, we have a proc-macro `#[pyclass]`.
|
||||
|
||||
To summarize, there are five main parts to the PyO3 codebase.
|
||||
1. Low-level bindings of Python C/API.
|
||||
- [`src/ffi`]
|
||||
2. Bindings to Python objects.
|
||||
- [`src/instance.rs`], [`src/types`]
|
||||
3. `PyClass<T>` and related functionalities
|
||||
- [`src/pycell.rs`], [`src/pyclass.rs`]
|
||||
4. Protocol methods like `__getitem__`.
|
||||
- [`src/class`]
|
||||
5. Procedural macros to simplify usage for users.
|
||||
- [`src/derive_utils.rs`]
|
||||
- [`pyo3-macros`], [`pyo3-macros-backend`]
|
||||
1. [Low-level bindings of Python C/API.](#1-low-level-bindings-of-python-capi)
|
||||
- [`src/ffi`]
|
||||
2. [Bindings to Python objects.](#2-bindings-to-python-objects)
|
||||
- [`src/instance.rs`] and [`src/types`]
|
||||
3. [`PyClass<T>` and related functionalities.](#3-pyclasst-and-related-functionalities)
|
||||
- [`src/pycell.rs`], [`src/pyclass.rs`], and more
|
||||
4. [Protocol methods like `__getitem__`.](#4-protocol-methods)
|
||||
- [`src/class`]
|
||||
5. [Procedural macros to simplify usage for users.](#5-procedural-macros-to-simplify-usage-for-users)
|
||||
- [`src/derive_utils.rs`], [`pyo3-macros`] and [`pyo3-macros-backend`]
|
||||
6. [`build.rs`](#6-buildrs)
|
||||
- [`build.rs`](https://github.com/PyO3/pyo3/tree/master/build.rs)
|
||||
|
||||
## Low-level bindings of CPython API
|
||||
## 1. Low-level bindings of Python C/API
|
||||
[`src/ffi`] contains wrappers of [Python C/API](https://docs.python.org/3/c-api/).
|
||||
|
||||
We aim to provide straight-forward Rust wrappers resembling the file structure of
|
||||
We aim to provide straight-forward Rust wrappers resembling the file structure of
|
||||
[`cpython/Include`](https://github.com/python/cpython/tree/v3.9.2/Include).
|
||||
|
||||
However, we still lack some APIs and are continuously updating the the module to match
|
||||
the file contents upstream in CPython.
|
||||
The tracking issue is [#1289](https://github.com/PyO3/pyo3/issues/1289), and contribution is welcome.
|
||||
|
||||
## Bindings to Python objects
|
||||
In the [`src/ffi`] module, you see lots of feature gates such as `#[cfg(Py_LIMITED_API)]`,
|
||||
`#[cfg(Py_37)]`, and `#[cfg(PyPy)]`.
|
||||
`Py_LIMITED_API` corresponds to `#define Py_LIMITED_API` macro in Python C/API.
|
||||
With `Py_LIMITED_API`, we can build Python-version-agnostic binary called
|
||||
[abi3 wheel](https://pyo3.rs/v0.13.2/building_and_distribution.html#py_limited_apiabi3).
|
||||
`Py_37` means that the API is available from Python >= 3.7.
|
||||
There are also `Py_38`, `Py_39`, and so on.
|
||||
`PyPy` means that the API definition is for PyPy.
|
||||
Those flags are set in [`build.rs`](#6-buildrs).
|
||||
|
||||
## 2. Bindings to Python objects
|
||||
[`src/types`] contains bindings to [built-in types](https://docs.python.org/3/library/stdtypes.html)
|
||||
of Python, such as `dict` and `list`.
|
||||
For historical reasons, Python's `object` is called `PyAny` in PyO3 and located in [`src/types/any.rs`].
|
||||
|
|
@ -80,7 +91,7 @@ Since we need lots of boilerplate for implementing common traits for these types
|
|||
(e.g., `AsPyPointer`, `AsRef<PyAny>`, and `Debug`), we have some macros in
|
||||
[`src/types/mod.rs`].
|
||||
|
||||
## PyClass
|
||||
## 3. `PyClass<T>` and related functionalities
|
||||
[`src/pycell.rs`], [`src/pyclass.rs`], and [`src/type_object.rs`] contain types and
|
||||
traits to make `#[pyclass]` work.
|
||||
Also, [`src/pyclass_init.rs`] and [`src/pyclass_slots.rs`] have related functionalities.
|
||||
|
|
@ -115,11 +126,11 @@ See [the documentation](https://docs.rs/pyo3/latest/pyo3/pycell/struct.PyCell.ht
|
|||
This trait is somewhat complex and derives many traits, but the most important one is `PyTypeObject`
|
||||
in [`src/type_object.rs`].
|
||||
`PyTypeObject` is also implemented for built-in types.
|
||||
Type objects are singletons, and all Python types have their unique type objects.
|
||||
In Python, all objects have their types, and types are also objects of `type`.
|
||||
For example, you can see `type({})` shows `dict` and `type(type({}))` shows `type` in Python REPL.
|
||||
`T: PyTypeObject` implies that `T` has a corresponding type object.
|
||||
|
||||
## Protocol methods
|
||||
## 4. Protocol methods
|
||||
Python has some built-in special methods called dunder, such as `__iter__`.
|
||||
They are called [abstract objects layer](https://docs.python.org/3/c-api/abstract.html) in
|
||||
Python C/API.
|
||||
|
|
@ -135,13 +146,30 @@ sets `iter<T>` on the type object of `T`.
|
|||
Also, [`src/class/methods.rs`] has utilities for `#[pyfunction]` and [`src/class/impl_.rs`] has
|
||||
some internal tricks for making `#[pyproto]` flexible.
|
||||
|
||||
## Procedural macros
|
||||
## 5. Procedural macros to simplify usage for users.
|
||||
[`pyo3-macros`] provides six proc-macro APIs: `pymodule`, `pyproto`, `pyfunction`, `pyclass`,
|
||||
`pymethods`, and `#[derive(FromPyObject)]`.
|
||||
[`pyo3-macros-backend`] has the actual implementations of these APIs.
|
||||
[`src/derive_utils.rs`] contains some utilities used in code generated by these proc-macros,
|
||||
such as parsing function arguments.
|
||||
|
||||
## 6. `build.rs`
|
||||
PyO3's `build.rs` is relatively long (about 900 lines) to support some complex build cases.
|
||||
Here we list up some of its functionalities:
|
||||
- Check if we are building a Python-extension or not.
|
||||
- If we are building an extesion (e.g., Python library installable by `pip`),
|
||||
we don't link `libpython`.
|
||||
Currently we use `extension-module` feature for this purpose, but it can change in the future.
|
||||
See [#1123](https://github.com/PyO3/pyo3/pull/1123).
|
||||
- Find the interpreter for build and detect the Python version.
|
||||
- We have to set some version flags like `Py_37`.
|
||||
- Also, if the interpreter is PyPy, we set `PyPy`.
|
||||
- Cross-compiling support.
|
||||
- If `TARGET` architecture and `HOST` architecture differ, we find cross compile information
|
||||
from environmental variable (`PYO3_CROSS_INCLUDE_DIR` and `PYO3_CROSS_PYTHON`) or system files.
|
||||
|
||||
[`build.rs`]: https://github.com/PyO3/pyo3/tree/master/src/build.rs
|
||||
|
||||
<!-- External Links -->
|
||||
[Python C/API](https://docs.python.org/3/c-api/).
|
||||
<!-- Crates -->
|
||||
|
|
|
|||
|
|
@ -4,6 +4,9 @@ Thank you for your interest in contributing to PyO3! All are welcome - please co
|
|||
|
||||
If you are searching for ideas how to contribute, please read the "Getting started contributing" section. Once you've found an issue to contribute to, you may find the section "Writing pull requests" helpful.
|
||||
|
||||
If you want to become familiar with the codebase, check
|
||||
[Architecture.md](https://github.com/PyO3/pyo3/tree/master/Architecture.md).
|
||||
|
||||
## Getting started contributing
|
||||
|
||||
Please join in with any part of PyO3 which interests you. We use Github issues to record all bugs and ideas. Feel free to request an issue to be assigned to you if you want to work on it.
|
||||
|
|
|
|||
Loading…
Reference in New Issue