|
1 |
| -# Python package structure information |
| 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 |
5 |
| -is for you. |
| 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 |
| 5 | +is for you. |
6 | 6 |
|
7 | 7 | <!-- TODO: move this either to the top of this section or the landing page?-->
|
8 | 8 |
|
9 | 9 | ```{note}
|
10 |
| -Have a look at the |
| 10 | +Have a look at the |
11 | 11 | 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 |
| -performs before a review begins. These checks are useful to explore |
13 |
| -for both authors planning to submit a package to us for review and for |
14 |
| -anyone who is just getting started with creating a Python package. |
| 12 | +performs before a review begins. These checks are useful to explore |
| 13 | +for both authors planning to submit a package to us for review and for |
| 14 | +anyone who is just getting started with creating a Python package. |
15 | 15 |
|
16 |
| -In general these are basic items that should be in any open software repository. |
| 16 | +In general these are basic items that should be in any open software repository. |
17 | 17 | ```
|
18 | 18 |
|
19 |
| -## Guidelines for pyOpenSci's packaging recommendations |
| 19 | +## Guidelines for pyOpenSci's packaging recommendations |
20 | 20 |
|
21 | 21 | <!-- Might belong on the LANDING page for this entire guide?-->
|
22 | 22 |
|
23 |
| -Python is a flexible programming language that is used across numerous |
24 |
| -disciplines and domains. Python is so flexible that it is one of the few |
| 23 | +Python is a flexible programming language that is used across numerous |
| 24 | +disciplines and domains. Python is so flexible that it is one of the few |
25 | 25 | languages that can be used to wrap around other languages.
|
26 | 26 |
|
27 |
| -If you are building a pure Python package, then your packaging setup can be |
28 |
| -simple. However, some scientific packages have complex requirements as they may |
| 27 | +If you are building a pure Python package, then your packaging setup can be |
| 28 | +simple. However, some scientific packages have complex requirements as they may |
29 | 29 | need to support extensions or tools written in other languages such as C or C++.
|
30 | 30 |
|
31 |
| -To support the many different uses of Python, there are many ways to create a |
32 |
| -Python package. |
| 31 | +To support the many different uses of Python, there are many ways to create a |
| 32 | +Python package. |
33 | 33 |
|
34 | 34 | The ecosystem is dynamic, and constantly evolving to support
|
35 |
| -the numerous needs that developers (and scientists) have using Python. |
| 35 | +the numerous needs that developers (and scientists) have using Python. |
36 | 36 |
|
37 |
| -This dynamic yet flexible environment is what many love about Python. |
| 37 | +This dynamic yet flexible environment is what many love about Python. |
38 | 38 |
|
39 |
| -## What you will learn here |
| 39 | +## What you will learn here |
40 | 40 |
|
41 | 41 | In this section of our Python packaging guide, we try to:
|
42 | 42 |
|
43 |
| -* Provide an overview of the options available to you when packaging your tool |
44 |
| -* Suggest tools and approaches that both meet your needs and also support existing standards. |
45 |
| -* 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. |
| 43 | +* Provide an overview of the options available to you when packaging your tool |
| 44 | +* Suggest tools and approaches that both meet your needs and also support existing standards. |
| 45 | +* 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. |
46 | 46 | * Align our suggestions with the most current, accepted
|
47 |
| -[PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community SPECs](https://scientific-python.org/specs/). |
48 |
| -* In an effort to maintain consistency withint our community , we also align with existing best practices being implemented by developers of core Scientific Python packages such as numpy, scipy and others. |
| 47 | +[PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community SPECs](https://scientific-python.org/specs/). |
| 48 | +* In an effort to maintain consistency withint our community , we also align with existing best practices being implemented by developers of core Scientific Python packages such as numpy, SciPy and others. |
49 | 49 |
|
50 | 50 |
|
51 |
| - |
52 |
| - |
53 |
| -<!-- |
54 |
| -
|
55 |
| -These checks include several items |
56 |
| -
|
57 |
| -- **Sufficient Documentation** The package has sufficient documentation available online (README, sphinx docs) to allow us to evaluate package function and scope *without installing the package*. This includes: |
58 |
| - Get started tutorials or vignettes that help a user understand how to use the package and what it can do for them (often these have a name like "Getting started") |
59 |
| -- **API documentation** - this includes clearly written doc strings with variables defined using a standard docstring format --> |
60 |
| -<!-- |
| 51 | +<!-- |
61 | 52 | ```{tip}
|
62 |
| -### Python packaging resources that we love |
| 53 | +### Python packaging resources that we love |
63 | 54 |
|
64 |
| -We think the resources below are excellent but each have particular opinions |
| 55 | +We think the resources below are excellent but each have particular opinions |
65 | 56 | that you may or may not find in our packaging guide. For instance, the PyPA
|
66 | 57 | guide encourages users to store their package in a `src/package-name` directory.
|
67 |
| -While we accept that approach many of our community members prefer to not use |
68 |
| -the `src` directory. |
| 58 | +While we accept that approach many of our community members prefer to not use |
| 59 | +the `src` directory. |
69 | 60 |
|
70 | 61 | * [Python packaging for research software engineers](https://merely-useful.tech/py-rse/)
|
71 | 62 | * [PyPA packaging guide](https://packaging.python.org/en/latest/)
|
72 | 63 | ```
|
73 |
| ---> |
| 64 | +--> |
0 commit comments