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
1. Individual files in your GitHub (or GitLab) repository including:
167
-
* [A clear and to the point **README.md** file](readme-file-best-practices) that includes information about how to cite your package.
168
-
* A [**CONTRIBUTING.md** file](contributing-license-coc) that outlines how others can contribute to your package. This file should also link to your development guide and code of conduct. A well-crafted contributing guide will make it much easier for the community to contribute to your project.
169
-
* A [**CODE_OF_CONDUCT.md**](contributing-license-coc.html#the-code-of-conduct-md-file) file. This file sets up the guidelines for how your community interacts. It ideally ensures that everyone feels safe and can report inappropriate behavior if need be.
170
-
* [**A LICENSE.txt file**](contributing-license-coc.html#your-repository-should-have-a-license-md-file) A license file declaring the OSI-approved license that you select and instructions for citing your package.
171
-
* We also suggest (but don't require) that you include a development guide that details the infrastructure used in your package. Sometimes this file is included in the user-facing documentation website (discussed below).
172
-
1. [**User focused package documentation**](package-documentation-best-practices) that helps users understand how to install, setup and use your package. Documentation is most often contained in a stand-alone website. The user-focused documentation should include:
173
-
* **Tutorials and quick start code examples** that help a user get started using your package.
174
-
* **Documentation for user-facing functions, objects and methods in your package (the API).** Package API documentation refers to documentation for each class, function, method and user-facing attribute (*available for a user to see*) in your package. This means that your package methods and classes should have [thoughtful docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) that describe both the purpose of the code element and each input and output.
Copy file name to clipboardExpand all lines: package-structure-code/intro.md
+47-34Lines changed: 47 additions & 34 deletions
Original file line number
Diff line number
Diff line change
@@ -9,72 +9,87 @@ there are some great modern packaging tools that ensure that you're following
9
9
best practices. Here, we review tool features and suggest tools that might be
10
10
best fitted for your workflow.
11
11
12
-
::::{grid} 1 1 2 2
12
+
:::::{grid} 1 1 2 2
13
13
:class-container: text-center
14
14
:gutter: 3
15
15
16
-
:::{grid-item-card}
16
+
::::{grid-item}
17
+
:::{card} ✨ 1. Package file structure ✨
17
18
:link: python-package-structure
18
19
:link-type: doc
19
20
20
-
✨ 1. Package file structure ✨
21
-
^^^
22
21
src layout, flat layout and where should tests folders live? No matter what your level of packaging knowledge is, this page will help you decide upon a package structure that follows modern python best practices.
23
22
:::
23
+
::::
24
24
25
-
:::{grid-item-card}
25
+
::::{grid-item}
26
+
:::{card} ✨ 2. Learn about building your package ✨
26
27
:link: python-package-structure
27
28
:link-type: doc
28
29
29
-
✨ 2. Learn about building your package ✨
30
-
^^^
31
-
Publishing a Python package is a great way to share your code with scientists to support open science workflow. In order to publish a package, you will need to first build it. The act of "building" refers to the process of placing your package code and
32
-
metadata into a format that can be published on PyPI. Once published on PyPI, your users can easily install it locally using pip. Learn more about building a Python package here.
30
+
To publish your Python package on PyPI, you will need to first build it. The act
31
+
of "building" refers to the process of placing your package code and
32
+
metadata into a format that can be published on PyPI. Learn more about building
33
+
your Python package.
33
34
:::
35
+
::::
34
36
35
-
:::{grid-item-card}
36
-
:link: python-package-build-tools
37
+
38
+
::::{grid-item}
39
+
:::{card} ✨ 4. Add metadata ✨
40
+
:link: pyproject-toml-python-package-metadata
37
41
:link-type: doc
38
42
39
-
✨ 3. What Python package tool should you use? ✨
40
-
^^^
43
+
Learn how to add project metadata to your Python package to support both
44
+
filtering on PyPI and also the metadata that a package installer needs to
45
+
build and install your package.
46
+
:::
47
+
::::
48
+
49
+
::::{grid-item}
50
+
:::{card} ✨ 3. What Python package tool should you use? ✨
51
+
:link: python-package-build-tools
52
+
:link-type: doc
41
53
42
54
Learn more about the suite of packaging tools out there.
43
55
And learn which tool might be best for you.
44
56
:::
57
+
::::
45
58
46
-
:::{grid-item-card}
59
+
::::{grid-item}
60
+
:::{card} ✨ 4. Publish to PyPI and Conda ✨
47
61
:link: python-package-build-tools
48
62
:link-type: doc
49
63
50
-
✨ 4. Publish your package to PyPI and Conda ✨
51
-
^^^
52
-
If you have a pure python package, it's a straight forward
64
+
If you have a pure Python package, it's a straight forward
53
65
process to publish to both PyPI and then a Conda channel such as
54
66
conda-forge. Learn more here.
55
67
:::
68
+
::::
56
69
57
-
:::{grid-item-card}
70
+
::::{grid-item}
71
+
:::{card} ✨ 5. Setup package versioning ✨
58
72
:link: python-package-versions
59
73
:link-type: doc
60
74
61
-
✨ 5. Setup package versioning ✨
62
-
^^^
63
75
Semver (numeric versioning) and Calver (versioning using the date) are 2
64
76
common ways to version a package. Which one should you pick? Learn more here.
65
77
:::
78
+
::::
66
79
67
-
:::{grid-item-card}
80
+
::::{grid-item}
81
+
:::{card} ✨ 6. Code style & linters ✨
68
82
:link: code-style-linting-format
69
83
:link-type: doc
70
84
71
-
✨ 6. Code style & linters ✨
72
-
^^^
73
85
Black, blue, flake8, Ruff - which tools can help you ensure your
74
-
package follows best practices for code format? Learn more about the options and why this is important here.
86
+
package follows best practices for code format? Learn more about the options
87
+
and why this is important here.
75
88
:::
76
89
::::
77
90
91
+
:::::
92
+
78
93
:::{figure-md} packaging-tools-decision-tree
79
94
80
95
<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">
@@ -83,13 +98,13 @@ Diagram showing the various front-end build tools that you can select from.
83
98
See the packaging tools page to learn more about each tool.
84
99
:::
85
100
86
-
```{note}
101
+
:::{note}
87
102
If you are considering submitting a package for peer review, have a look
88
103
at the bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template)
89
104
that pyOpenSci performs before a review begins. These checks are useful
90
105
to explore for both authors planning to submit a package to us for review
91
106
and for anyone who is just getting started with creating a Python package.
92
-
```
107
+
:::
93
108
94
109
## What you will learn here
95
110
@@ -111,8 +126,6 @@ In this section of our Python packaging guide, we:
111
126
112
127
## Guidelines for pyOpenSci's packaging recommendations
113
128
114
-
<!-- Might belong on the LANDING page for this entire guide?-->
115
-
116
129
The flexibility of the Python programming language lends itself to a diverse
117
130
range of tool options for creating a Python package. Python is so flexible that
118
131
it is one of the few languages that can be used to wrap around other languages.
@@ -135,7 +148,7 @@ Python package. In this guide, we suggest packaging approaches and tools based o
135
148
Here, we also try to align our suggestions with the most current, accepted
136
149
[Python community](https://packaging.python.org/en/latest/) and [scientific community](https://scientific-python.org/specs/).
137
150
138
-
```{admonition} Suggestions in this guide are not pyOpenSci review requirements
151
+
:::{admonition} Suggestions in this guide are not pyOpenSci review requirements
139
152
:class: important
140
153
141
154
The suggestions for package layout in this section are made with the
@@ -145,9 +158,9 @@ package to be reviewed and accepted into our pyOpenSci open source ecosystem.
145
158
Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html)
146
159
and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#)
147
160
if you are looking for pyOpenSci's Python package review requirements!
148
-
```
161
+
:::
149
162
150
-
```{toctree}
163
+
:::{toctree}
151
164
:hidden:
152
165
:caption: Package structure & code style
153
166
@@ -159,14 +172,14 @@ Build Your Package <python-package-distribution-files-sdist-wheel>
159
172
Declare dependencies <declare-dependencies>
160
173
Package Build Tools <python-package-build-tools>
161
174
Complex Builds <complex-python-package-builds>
162
-
```
175
+
:::
163
176
164
-
```{toctree}
177
+
:::{toctree}
165
178
:hidden:
166
179
:caption: Publishing a package
167
180
168
181
Publish with Conda / PyPI <publish-python-package-pypi-conda>
Copy file name to clipboardExpand all lines: package-structure-code/pyproject-toml-python-package-metadata.md
+7-3Lines changed: 7 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -19,10 +19,13 @@ what's missing
19
19
5. There is no specific order for tables in the `pyproject.toml` file. However fields need to be placed within the correct table sections. For example `requires =` always need to be associated with the **[build-system]** table.
20
20
6.**python-requires**: is important to have in your `pyproject.toml` file as it helps pip install your package.
21
21
22
-
<!-- Commenting this out given the lessons aren't online yet
23
-
we can add this back once tutorials are published
24
22
:::
25
23
24
+
25
+
:::::{todo}
26
+
27
+
when these are published, remove this todo
28
+
26
29
::::{grid} 2
27
30
28
31
:::{grid-item}
@@ -51,7 +54,8 @@ Click here if need help migrating from setup.py/setup.cfg to pyproject.toml
0 commit comments