Skip to content

Commit 778c640

Browse files
committed
Fix: remove more commented out blocks
1 parent 510c6b5 commit 778c640

File tree

1 file changed

+8
-33
lines changed

1 file changed

+8
-33
lines changed

package-structure-code/python-package-structure.md

Lines changed: 8 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@ Below you will learn about the pros and cons of both layouts.
1616
Currently most scientific packages use the **flat-layout** given:
1717

1818
* 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.
2023

2124
In the end, the advantages of using the **src/** layout for scientific packages
2225
that already use this approach do not
@@ -39,15 +42,17 @@ Currently most scientific packages use the **flat-layout** given:
3942
4043
It would be a significant maintenance cost and burden to move all of these
4144
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,
4347
pyOpenSci supports maintainers using a flat layout for scientific packages.
4448
```
4549

4650
## What does the flat layout structure look like?
4751

4852
The flat layout's primary characteristics are:
4953

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
5156
* Often the `tests/` directory also lives within that same `package-name` directory.
5257

5358
Below you can see the recommended structure of a scientific Python package
@@ -148,16 +153,6 @@ myPackage
148153
└── ... ┘ Package tests
149154
```
150155

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-
161156
## Core file requirements for a Python package
162157

163158
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
193188
tutorial.
194189
```
195190

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-
216191
## Use a pyproject.toml file for your package configuration & metadata
217192

218193
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

Comments
 (0)