Debian Codegraph @

guide/src/project_layout.md

raw
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.