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
Here you will find guidelines for what we look for in your scientific
33
-
Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and documentation.
32
+
Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and documentation. Our goal is to help the
33
+
community make decisions around how to create scientific Python packages. We are working towards a shared vision of packaging that helps users better understand where to start.
34
34
35
35
::::{grid} 2
36
36
:reverse:
@@ -82,6 +82,16 @@ documentation that are
82
82
commonly used in the scientific Python community.
83
83
:::
84
84
85
+
:::{grid-item-card}
86
+
:link: package-structure-code/intro
87
+
:link-type: doc
88
+
:class-header: bg-light
89
+
90
+
✨ Python packaging tools & structure ✨
91
+
^^^
92
+
All of the modern tools discussed in this guide will help you build an efficient packaging workflow. This section helps you select the one that will work best for your workflow.
93
+
:::
94
+
85
95
86
96
:::{grid-item-card}
87
97
:link: CONTRIBUTING
@@ -98,9 +108,9 @@ contribute.
98
108
## Who this guidebook is for
99
109
We assume that you are here because you are:
100
110
111
+
1. Looking for guidance on creating a Python package.
112
+
1. Looking for resources associated with Python packaging.
101
113
1. Considering submitting a package to pyOpenSci and want to understand what we are looking for when we review your package
102
-
2. Looking for guidance on creating a Python package.
103
-
3. Looking for resources associated with Python packaging.
ELI: A complex build could mean running a python script that processes some data file and produces a pure python module file.
148
+
149
+
Probably not common in the scientific community specifically, but I've seen quite a few setup.py files that contain custom build stages which e.g. build gettext locale catalogs.
150
+
151
+
The main point is that it is more "complex" than simply copying files or directories as-is into the built wheel.
Copy file name to clipboardExpand all lines: package-structure-code/intro.md
+36-47Lines changed: 36 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,76 +1,66 @@
1
1
# Python package structure information
2
2
3
-
If you plan to submit a package for review to pyOpenSci and are looking for
4
-
some guidance on package structure, code formats and style, then this section is for you.
3
+
This section provides guidance on your Python package's structure, code formats and style. It also reviews the various packaging tools that you can use to
4
+
support building and publishing your package.
5
5
6
-
## Guidelines for pyOpenSci's packaging recommendations
7
-
8
-
<!-- Might belong on the LANDING page for this entire guide?-->
9
-
10
-
There are some differing opinions on what Python package structure should
11
-
look like and what tools to use across the Python ecosystem.
12
-
13
-
In this guide, we have made decisions around suggested standards and required
14
-
standards, based upon the commonly used approaches in the scientific Python
15
-
community. Our goal is to help standardize packaging across this ecosystem.
16
-
17
-
In some cases the suggestions here may diverge from those in the non-scientific parts of the Python ecosystem.
6
+
If you are confused by Python packaging, you are not alone!
7
+
The good news is there are some great modern packaging
8
+
tools that ensure that you're following best practices. Here, we
9
+
review tool features and suggest tools that might be best fitted for your workflow.
18
10
19
11
```{note}
20
-
The suggestions for package layout in this section are made with the
21
-
intent of being helpful; they are not specific requirements for your
22
-
package to be reviewed and accepted into our ecosystem.
23
-
```
24
-
25
-
In all cases, we try to align our suggestions with the most current, accepted
26
-
[PEP's (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community specs](https://scientific-python.org/specs/).
27
-
If you plan to submit a package for review to pyOpenSci and are looking for
28
-
some guidance on package structure, code formats and style, then this section
29
-
is for you.
30
-
31
-
<!-- TODO: move this either to the top of this section or the landing page?-->
32
-
33
-
```{note}
34
-
Have a look at the
35
-
bare-minimum [editor checks](https://www.pyopensci.org/peer-review-guide/software-peer-review-guide/editor-in-chief-guide.html#editor-checklist-template) that pyOpenSci
12
+
If you are considering submitting a package for peer review, have a look at the
13
+
bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) that pyOpenSci
36
14
performs before a review begins. These checks are useful to explore
37
15
for both authors planning to submit a package to us for review and for
38
16
anyone who is just getting started with creating a Python package.
39
17
40
18
In general these are basic items that should be in any open software repository.
41
19
```
42
20
21
+
## What you will learn here
22
+
23
+
In this section of our Python packaging guide, we:
24
+
25
+
- Provide an overview of the options available to you when packaging your tool
26
+
- Suggest tools and approaches that both meet your needs and also support existing standards.
27
+
- Suggest tools and approaches that will allow you to expand upon a workflow that may begin as a pure Python tool and evolve into a tool that requires addition layers of complexity in the packaging build.
28
+
- Align our suggestions with the most current, accepted
29
+
[PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community SPECs](https://scientific-python.org/specs/).
30
+
- In an effort to maintain consistency within our community , we also align with existing best practices being implemented by developers of core Scientific Python packages such as Numpy, SciPy and others.
31
+
43
32
## Guidelines for pyOpenSci's packaging recommendations
44
33
45
34
<!-- Might belong on the LANDING page for this entire guide?-->
46
35
47
-
Python is a flexible programming language that is used across numerous
48
-
disciplines and domains. Python is so flexible that it is one of the few
49
-
languages that can be used to wrap around other languages.
36
+
The flexibility of the Python programming language lends itself to a diverse
37
+
range of tool options for creating a Python package. Python is so flexible that
38
+
it is one of the few languages that can be used to wrap around other languages.
50
39
51
40
If you are building a pure Python package, then your packaging setup can be
52
41
simple. However, some scientific packages have complex requirements as they may
53
42
need to support extensions or tools written in other languages such as C or C++.
54
43
55
44
To support the many different uses of Python, there are many ways to create a
56
-
Python package.
45
+
Python package. In this guide, we suggest approaches for packaging approaches and tools based
46
+
upon:
57
47
58
-
The ecosystem is dynamic, and constantly evolving to support
59
-
the numerous needs that developers (and scientists) have using Python.
48
+
1. What we think will be best and easiest to adopt for those who are newer to packaging
49
+
2. Tools that we think are well maintained and documented.
50
+
3. A shared goal of standardizing packaging approaches across this (scientific) Python ecosystem.
60
51
61
-
This dynamic yet flexible environment is what many love about Python.
52
+
Here, we also try to align our suggestions with the most current, accepted
53
+
[Python community](https://packaging.python.org/en/latest/) and [scientific community](https://scientific-python.org/specs/).
62
54
63
-
## What you will learn here
55
+
```{admonition} Suggestions in this guide are not pyOpenSci review requirements
56
+
:class: important
64
57
65
-
In this section of our Python packaging guide, we try to:
66
-
67
-
* Provide an overview of the options available to you when packaging your tool
68
-
* Suggest tools and approaches that both meet your needs and also support existing standards.
69
-
* Suggest tools and approaches that will allow you to expand upon a workflow that may begin as a pure Python tool and evolve into a tool that requires addition layers of complexity in the packaging build.
70
-
* Align our suggestions with the most current, accepted
71
-
[PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community SPECs](https://scientific-python.org/specs/).
72
-
* In an effort to maintain consistency within our community , we also align with existing best practices being implemented by developers of core Scientific Python packages such as Numpy, SciPy and others.
58
+
The suggestions for package layout in this section are made with the
59
+
intent of being helpful; they are not specific requirements for your
60
+
package to be reviewed and accepted into our pyOpenSci open source ecosystem.
73
61
62
+
Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html) and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#) if you are looking for pyOpenSci's Python package review requirements!
# Use a pyproject.toml file for your package configuration & metadata
2
2
3
-
The standard file that Python packages use to specify build requirements and
4
-
metadata is called a pyproject.toml. The pyproject.toml file has become the
5
-
standard for declaring Python package metadata (including dependencies) rather
6
-
than using a setup.py file (or a setup.py + setup.cfg file).
3
+
The standard file that Python packages use to [specify build requirements and
4
+
metadata is called a **pyproject.toml**](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/). Adding metadata, build requirements
5
+
and package dependencies to a **pyproject.toml** file replaces storing that
6
+
information in a setup.py or setup.cfg file.
7
7
8
-
As such you should try to [include all project based metadata and build system specifications in a `pyproject.toml` file.](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/) Using setup.py to manage both package set up and
9
-
hold metadata [can cause problems with package development.](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)
10
-
11
-
12
-
```{admonition} Benefits of using a pyproject.toml file
13
-
:class: tip
14
-
15
-
1. Because setup.py has a mixture of code and metadata, it will be run twice when
16
-
building your package. First it will be run to extract metadata (dependencies). Then it will be run to build your package.
17
-
1. Including your package's metadata in a separate human-readable `pyproject.toml` format also allows someone to view the project's metadata without
18
-
running any Python code.
19
-
```
20
-
21
-
A pyproject.toml is written in [TOML (Tom's Obvious, Minimal Language) format](https://toml.io/en/). TOML is an easy-to-read structure that is founded on key: value pairs.
22
-
23
-
Each section in the pyproject.toml file contains a `[table identifier]`.
8
+
The **pyproject.toml** file is written in [TOML (Tom's Obvious, Minimal Language) format](https://toml.io/en/). TOML is an easy-to-read structure that is founded on key: value pairs. Each section in the **pyproject.toml** file contains a `[table identifier]`.
24
9
Below that table identifier are key value pairs that
25
10
support configuration for that particular table.
26
11
12
+
### Benefits of using a pyproject.toml file
13
+
14
+
Including your package's metadata in a separate human-readable **pyproject.toml**
15
+
format also allows someone to view the project's metadata in a GitHub repository.
16
+
27
17
<!-- setup.cfg for project metadata is being deprecated - set setuptools guide and
<!-- [PEP518 describes the move away from setup.py to the pyproject.toml file.](https://peps.python.org/pep-0518/) -->
34
-
Python package standards are moving away from including both package metadata
35
-
and Python code needed to set up a package in the same **setup.py** file.
36
-
Instead we are moving towards using a **proproject.toml** file.
22
+
```{admonition} Setup.py is still useful for complex package builds
23
+
:class: tip
37
24
38
-
In some cases where a build is complex, a **setup.py** file may still be
39
-
required. While this guide will not cover complex builds, we will provide
25
+
Using **setup.py** to manage package builds and metadata [can cause problems with package development](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html).
26
+
In some cases where a Python package build iscomplex, a **setup.py**file may
27
+
be required. While this guide will not cover complex builds, we will provide
40
28
resources working withcomplex builds in the future.
ELI: A complex build could mean running a python script that processes some data file and produces a pure python module file.
44
-
45
-
Probably not common in the scientific community specifically, but I've seen quite a few setup.py files that contain custom build stages which e.g. build gettext locale catalogs.
46
-
47
-
The main point is that it is more "complex" than simply copying files or directories as-is into the built wheel.
48
-
-->
49
30
```
50
31
51
-
## Example pyproject.toml
52
-
53
-
Below is an example build configuration for a Python project. This setup
54
-
requires:
55
-
56
-
***setuptools** to create the package structure,
57
-
***wheel** which is used by `setuptools` to create the [**.whl** (wheel) file](https://realpython.com/python-wheels/).
58
-
***setuptools build** to "build" the package
59
-
***setuptools_scm** to manage package version updates
60
-
61
-
In the example below `[build-system]` is the first table
62
-
of values. It has two keys that specify the build front end and backend for a package:
32
+
### Example pyproject.toml for building using PDM
33
+
Below is an example build configuration for a Python project. This example
34
+
package setup uses:
63
35
64
-
1.`requires =`
65
-
1.`build-backend =`
36
+
***pdm.pep517.api** to build the [package's SDist and wheels](python-package-distribution-files-sdist-wheel)
0 commit comments