|
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