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/intro.md
+38-24Lines changed: 38 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,59 +1,71 @@
1
1
# Python package structure information
2
2
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
3
+
This section provides guidance on your Python package's structure, code formats
4
+
and style. It also reviews the various packaging tools that you can use to
4
5
support building and publishing your package.
5
6
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.
7
+
If you are confused by Python packaging, you are not alone! The good news is
8
+
there are some great modern packaging tools that ensure that you're following
9
+
best practices. Here, we review tool features and suggest tools that might be
10
+
best fitted for your workflow.
10
11
11
12
:::{figure-md} fig-target
12
13
13
-
<imgsrc="../images/python-package-tools-decision-tree.png"alt="Figure showing a decision tree with the various packaging tool frontend and backend options."width="700px">
14
+
<imgsrc="../images/python-package-tools-decision-tree.png"alt="Figure showing a decision tree with the various packaging tool front-end and back-end options."width="700px">
14
15
15
-
Diagram showing the various from end build tools that you can select from. See the packaging tools page to learn more about each tool.
16
+
Diagram showing the various front-end build tools that you can select from.
17
+
See the packaging tools page to learn more about each tool.
16
18
:::
17
19
18
20
```{note}
19
-
If you are considering submitting a package for peer review, have a look at the
20
-
bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) that pyOpenSci
21
-
performs before a review begins. These checks are useful to explore
22
-
for both authors planning to submit a package to us for review and for
23
-
anyone who is just getting started with creating a Python package.
24
-
21
+
If you are considering submitting a package for peer review, have a look
22
+
at the bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template)
23
+
that pyOpenSci performs before a review begins. These checks are useful
24
+
to explore for both authors planning to submit a package to us for review
25
+
and for anyone who is just getting started with creating a Python package.
25
26
```
26
27
27
28
## What you will learn here
28
29
29
30
In this section of our Python packaging guide, we:
30
31
31
-
- Provide an overview of the options available to you when packaging your tool
32
-
- Suggest tools and approaches that both meet your needs and also support existing standards.
33
-
- 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.
32
+
- Provide an overview of the options available to you when packaging your
33
+
tool.
34
+
- Suggest tools and approaches that both meet your needs and also support
35
+
existing standards.
36
+
- Suggest tools and approaches that will allow you to expand upon a workflow
37
+
that may begin as a pure Python tool and evolve into a tool that requires
38
+
addition layers of complexity in the packaging build.
34
39
- Align our suggestions with the most current, accepted
35
-
[PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community SPECs](https://scientific-python.org/specs/).
36
-
- 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.
and the [Scientific Python community SPECs](https://scientific-python.org/specs/).
42
+
- In an effort to maintain consistency within our community, we also align
43
+
with existing best practices being implemented by developers of core
44
+
Scientific Python packages such as Numpy, SciPy and others.
37
45
38
46
## Guidelines for pyOpenSci's packaging recommendations
39
47
40
48
<!-- Might belong on the LANDING page for this entire guide?-->
41
49
42
50
The flexibility of the Python programming language lends itself to a diverse
43
51
range of tool options for creating a Python package. Python is so flexible that
44
-
it is one of the few languages that can be used to wrap around other languages. The ability of Python to wrap other languages one the reasons why you will often hear Python described as a ["glue" language](https://numpy.org/doc/stable/user/c-info.python-as-glue.html)"
52
+
it is one of the few languages that can be used to wrap around other languages.
53
+
The ability of Python to wrap other languages is one the reasons you will often
54
+
hear Python described as a ["glue" language](https://numpy.org/doc/stable/user/c-info.python-as-glue.html)"
45
55
46
56
If you are building a pure Python package, then your packaging setup can be
47
57
simple. However, some scientific packages have complex requirements as they may
48
58
need to support extensions or tools written in other languages such as C or C++.
49
59
50
60
To support the many different uses of Python, there are many ways to create a
51
-
Python package. In this guide, we suggest approaches for packaging approaches and tools based
52
-
upon:
61
+
Python package. In this guide, we suggest approaches for packaging approaches
62
+
and tools based on:
53
63
54
-
1. What we think will be best and easiest to adopt for those who are newer to packaging
64
+
1. What we think will be best and easiest to adopt for those who are newer to
65
+
packaging.
55
66
2. Tools that we think are well maintained and documented.
56
-
3. A shared goal of standardizing packaging approaches across this (scientific) Python ecosystem.
67
+
3. A shared goal of standardizing packaging approaches across this (scientific)
68
+
Python ecosystem.
57
69
58
70
Here, we also try to align our suggestions with the most current, accepted
59
71
[Python community](https://packaging.python.org/en/latest/) and [scientific community](https://scientific-python.org/specs/).
@@ -65,7 +77,9 @@ The suggestions for package layout in this section are made with the
65
77
intent of being helpful; they are not specific requirements for your
66
78
package to be reviewed and accepted into our pyOpenSci open source ecosystem.
67
79
68
-
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!
80
+
Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html)
81
+
and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#)
82
+
if you are looking for pyOpenSci's Python package review requirements!
0 commit comments