| 1 |
# Project Layout |
| 2 |
|
| 3 |
Maturin expects a particular project layout depending on the contents of the |
| 4 |
package. |
| 5 |
|
| 6 |
## Pure Rust project |
| 7 |
|
| 8 |
For a pure Rust project, the structure is as expected and what you get from `cargo new`: |
| 9 |
|
| 10 |
``` |
| 11 |
my-rust-project/ |
| 12 |
├── Cargo.toml |
| 13 |
├── pyproject.toml # required for maturin configuration |
| 14 |
└── src |
| 15 |
├── lib.rs # default for library crates |
| 16 |
└── main.rs # default for binary crates |
| 17 |
``` |
| 18 |
|
| 19 |
Maturin will add a necessary `__init__.py` to the package when building the |
| 20 |
wheel. For convenience, this file includes the following: |
| 21 |
|
| 22 |
```python |
| 23 |
from .my_project import * |
| 24 |
|
| 25 |
__doc__ = my_project.__doc__ |
| 26 |
if hasattr(my_project, "__all__"): |
| 27 |
__all__ = my_project.__all__ |
| 28 |
``` |
| 29 |
|
| 30 |
such that the module functions may be called directly with: |
| 31 |
|
| 32 |
```python |
| 33 |
import my_project |
| 34 |
my_project.foo() |
| 35 |
``` |
| 36 |
|
| 37 |
rather than: |
| 38 |
|
| 39 |
```python |
| 40 |
from my_project import my_project |
| 41 |
``` |
| 42 |
|
| 43 |
> **Note**: there is currently no way to tell maturin to include extra data (e.g. |
| 44 |
`package_data` in setuptools) for a pure Rust project. Instead, consider using |
| 45 |
the layout described below for the mixed Rust/Python project. |
| 46 |
|
| 47 |
## Mixed Rust/Python project |
| 48 |
|
| 49 |
To create a mixed Rust/Python project, add a directory with your package name |
| 50 |
(i.e. matching `lib.name` in your `Cargo.toml`) to contain the Python source: |
| 51 |
|
| 52 |
``` |
| 53 |
my-rust-and-python-project |
| 54 |
├── Cargo.toml |
| 55 |
├── my_project # <<< add this directory and put Python code in here |
| 56 |
│ ├── __init__.py |
| 57 |
│ └── bar.py |
| 58 |
├── pyproject.toml |
| 59 |
├── README.md |
| 60 |
└── src |
| 61 |
└── lib.rs |
| 62 |
``` |
| 63 |
|
| 64 |
Note that in a mixed Rust/Python project, maturin _does not_ modify the |
| 65 |
existing `__init__.py` in the root package, so now to import the rust module in |
| 66 |
Python you must use: |
| 67 |
|
| 68 |
```python |
| 69 |
from my_project import my_project |
| 70 |
``` |
| 71 |
|
| 72 |
You can modify `__init__.py` yourself (see above) if you would like to import |
| 73 |
Rust functions from a higher-level namespace. |
| 74 |
|
| 75 |
You can specify a different python source directory in `pyproject.toml` by setting `tool.maturin.python-source`, for example |
| 76 |
|
| 77 |
**pyproject.toml** |
| 78 |
|
| 79 |
```toml |
| 80 |
[tool.maturin] |
| 81 |
python-source = "python" |
| 82 |
``` |
| 83 |
|
| 84 |
then the project structure would look like this: |
| 85 |
|
| 86 |
``` |
| 87 |
my-rust-and-python-project |
| 88 |
├── Cargo.toml |
| 89 |
├── python |
| 90 |
│ └── my_project |
| 91 |
│ ├── __init__.py |
| 92 |
│ └── bar.py |
| 93 |
├── pyproject.toml |
| 94 |
├── README.md |
| 95 |
└── src |
| 96 |
└── lib.rs |
| 97 |
``` |
| 98 |
|
| 99 |
> **Note** |
| 100 |
> |
| 101 |
> This structure is recommended to avoid [a common `ImportError` pitfall](https://github.com/PyO3/maturin/issues/490) |
| 102 |
|
| 103 |
|
| 104 |
### Alternate Python source directory (src layout) |
| 105 |
|
| 106 |
Having a directory with `package_name` in the root of the project can |
| 107 |
occasionally cause confusion as Python allows importing local packages and |
| 108 |
modules. A popular way to avoid this is with the `src`-layout, where the Python |
| 109 |
package is nested within a `src` directory. Unfortunately this interferes with |
| 110 |
the structure of a typical Rust project. Fortunately, Python is not particular |
| 111 |
about the name of the parent source directory. |
| 112 |
|
| 113 |
maturin will detect the following src layout automatically: |
| 114 |
|
| 115 |
``` |
| 116 |
my-rust-and-python-project |
| 117 |
├── src # put python code in src folder |
| 118 |
│ └── my_project |
| 119 |
│ ├── __init__.py |
| 120 |
│ └── bar.py |
| 121 |
├── pyproject.toml |
| 122 |
├── README.md |
| 123 |
└── rust # put rust code in rust folder |
| 124 |
|── Cargo.toml |
| 125 |
└── src |
| 126 |
└── lib.rs |
| 127 |
``` |
| 128 |
#### Import Rust as a submodule of your project |
| 129 |
|
| 130 |
If the Python module created by Rust has the same name as the Python package in a mixed Rust/Python project, IDEs might get confused. |
| 131 |
You might also want to discourage end users from using the Rust functions directly by giving it a different name, say '\_my_project'. |
| 132 |
This can be done by adding `module-name = <package name>.<rust pymodule name>` to the `[tool.maturin]` in your `pyproject.toml`. For example: |
| 133 |
|
| 134 |
```toml |
| 135 |
[tool.maturin] |
| 136 |
module-name = "my_project._my_project" |
| 137 |
``` |
| 138 |
|
| 139 |
Update the module name in `lib.rs` to match the expected module name: |
| 140 |
|
| 141 |
```diff |
| 142 |
#[pymodule] |
| 143 |
- fn my_project(...) |
| 144 |
+ fn _my_project(...) |
| 145 |
``` |
| 146 |
|
| 147 |
If you are using the `pyo3` bindings, you can alternatively add `#[pyo3(name = ...)]` to the `#[pymodule]` declaration: |
| 148 |
|
| 149 |
```diff |
| 150 |
#[pymodule] |
| 151 |
+ #[pyo3(name = "_my_project")] |
| 152 |
fn my_project(...) |
| 153 |
``` |
| 154 |
|
| 155 |
You can then import your Rust module inside your Python source as follows: |
| 156 |
|
| 157 |
```python |
| 158 |
from my_project import _my_project |
| 159 |
``` |
| 160 |
|
| 161 |
IDEs can then recognize the `_my_project` module as separate from your main Python source module. This allows for code completion of the types inside your Rust Python module for certain IDEs. |
| 162 |
|
| 163 |
|
| 164 |
## Adding Python type information |
| 165 |
|
| 166 |
To distribute typing information, you need to add: |
| 167 |
|
| 168 |
* an empty marker file called `py.typed` in the root of the Python package |
| 169 |
* inline types in Python files and/or `.pyi` "stub" files |
| 170 |
|
| 171 |
In a pure Rust project, add type stubs in a `<module_name>.pyi` file in the |
| 172 |
project root. Maturin will automatically include this file along with the |
| 173 |
required `py.typed` file for you. |
| 174 |
|
| 175 |
``` |
| 176 |
my-rust-project/ |
| 177 |
├── Cargo.toml |
| 178 |
├── my_project.pyi # <<< add type stubs for Rust functions in the my_project module here |
| 179 |
├── pyproject.toml |
| 180 |
└── src |
| 181 |
└── lib.rs |
| 182 |
``` |
| 183 |
|
| 184 |
In a mixed Rust/Python project, additional files in the Python source dir (but |
| 185 |
not in `.gitignore`) will be automatically included in the build outputs |
| 186 |
(source distribution and/or wheel). Type information can be therefore added to |
| 187 |
the root Python package directory as you might do in a pure Python package. |
| 188 |
This requires you to add the `py.typed` marker file yourself. |
| 189 |
|
| 190 |
``` |
| 191 |
my-project |
| 192 |
├── Cargo.toml |
| 193 |
├── python |
| 194 |
│ └── my_project |
| 195 |
│ ├── __init__.py |
| 196 |
│ ├── py.typed # <<< add this empty file |
| 197 |
│ ├── my_project.pyi # <<< add type stubs for Rust functions in the my_project module here |
| 198 |
│ ├── bar.pyi # <<< add type stubs for bar.py here OR type bar.py inline |
| 199 |
│ └── bar.py |
| 200 |
├── pyproject.toml |
| 201 |
├── README.md |
| 202 |
└── src |
| 203 |
└── lib.rs |
| 204 |
``` |
| 205 |
|
| 206 |
## Data |
| 207 |
|
| 208 |
You can add wheel data by creating a `<module_name>.data` folder or setting its location as `data` in pyproject.toml under `[tool.maturin]` or in Cargo.toml under `[project.metadata.maturin]`. |
| 209 |
|
| 210 |
The data folder may have the following subfolder: |
| 211 |
|
| 212 |
* `data`: The contents of this folder will simply be unpacked into the virtualenv |
| 213 |
* `scripts`: Treated similar to entry points, files in there are installed as standalone executable |
| 214 |
* `headers`: For `.h` C header files |
| 215 |
* `purelib`: This also exists, but seems to be barely used |
| 216 |
* `platlib`: This also exists, but seems to be barely used |
| 217 |
|
| 218 |
If you add a symlink in the data directory, we'll include the actual file so you have more flexibility. |