You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: package-structure-code/python-package-structure.md
+8-33Lines changed: 8 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,10 @@ Below you will learn about the pros and cons of both layouts.
16
16
Currently most scientific packages use the **flat-layout** given:
17
17
18
18
* It's the most commonly found layout with the scientific Python ecosystem
19
-
* Many Python tools depend upon tools in other language and / or complex builds with compilation steps. Many developers thus appreciate features of the flat layout such as tests being included with the package when they are installed) to support troubleshooting across installations.
19
+
* Many Python tools depend upon tools in other language and / or complex builds
20
+
with compilation steps. Many developers thus appreciate features of the flat
21
+
layout such as tests being included with the package when they are installed) to
22
+
support troubleshooting across installations.
20
23
21
24
In the end, the advantages of using the **src/** layout for scientific packages
22
25
that already use this approach do not
@@ -39,15 +42,17 @@ Currently most scientific packages use the **flat-layout** given:
39
42
40
43
It would be a significant maintenance cost and burden to move all of these
41
44
packages to a different layout. The potential benefits of the source layout
42
-
for these tools is not worth the maintenance investment. To avoid dividing the scientific Python community,
45
+
for these tools is not worth the maintenance investment. To avoid dividing the
46
+
scientific Python community,
43
47
pyOpenSci supports maintainers using a flat layout for scientific packages.
44
48
```
45
49
46
50
## What does the flat layout structure look like?
47
51
48
52
The flat layout's primary characteristics are:
49
53
50
-
* The source code for your package lives in a directory with your package's name in the root of your directory
54
+
* The source code for your package lives in a directory with your package's
55
+
name in the root of your directory
51
56
* Often the `tests/` directory also lives within that same `package-name` directory.
52
57
53
58
Below you can see the recommended structure of a scientific Python package
@@ -148,16 +153,6 @@ myPackage
148
153
└── ... ┘ Package tests
149
154
```
150
155
151
-
152
-
153
-
<!-- Not sure why i added this here? -->
154
-
To install your package in editable mode use:
155
-
156
-
```bash
157
-
$ cd package-name
158
-
$ pip install -e .`
159
-
```
160
-
161
156
## Core file requirements for a Python package
162
157
163
158
In the above example, notice that all of the core documentation files that
@@ -193,26 +188,6 @@ data within your package structure. We will discuss this in more detail in a
193
188
tutorial.
194
189
```
195
190
196
-
<!--
197
-
```{note}
198
-
### Src vs. flat layouts for Python packaging
199
-
While you will see other structures, [such as the `src/`
200
-
layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/) recommended by the [Python packaging authority](https://py-pkgs.org/04-package-structure) and others, all scientific
201
-
Python packages have used a flat layout. This structure has been
202
-
prevalent for almost a decade.
203
-
204
-
Because a core goal shared by both pyOpenSci and the Scientific Python
205
-
project, is to see increased standardization in Python packaging, we
206
-
are advocating for a structure that is used by existing packages in the
207
-
ecosystem.
208
-
209
-
Many of our core scientific Python packages wrap around other compiled languages, such as C++. They thus have source code that requires compilation. It would be challenging and potentially time-consuming for all of those packages to modify their current
210
-
structure. And further it would not provide them with any core benefit.
211
-
212
-
213
-
```
214
-
-->
215
-
216
191
## Use a pyproject.toml file for your package configuration & metadata
217
192
218
193
We strongly recommend that you [include all project based metadata and build system specifications in a `pyproject.toml` file.](https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/)[Using setup.py to manage both package setup and hold metadata can present numerous risks.](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)
0 commit comments