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: README.md
+14-10Lines changed: 14 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,6 @@ Initiatives.
24
24
25
25
## Contributing statement
26
26
27
-
28
27
## How to setup
29
28
30
29
This repository contains the source files for the [pyOpenSci Python packaging guide](https://pyopensci.org/python-package-guide).
@@ -44,44 +43,49 @@ To build, follow these steps:
44
43
1. Install `nox`
45
44
46
45
```console
47
-
$ python -m pip install nox
46
+
python -m pip install nox
48
47
```
48
+
49
49
2. Build the documentation:
50
50
51
51
```console
52
-
$ nox -s docs
52
+
nox -s docs
53
53
```
54
54
55
55
This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `_build/html`.
56
56
57
57
To build live documentation that updates when you update local files, run the following command:
58
58
59
59
```console
60
-
$ nox -s docs-live
60
+
nox -s docs-live
61
61
```
62
62
63
+
If you are a uv user, you can also skip installing `nox` and use `uvx` instead:
64
+
65
+
`uvx nox -s docs-live`
66
+
63
67
### Building for release
64
68
65
69
When building for release, the docs are built multiple times for each translation,
66
70
but translations are only included in the production version of the guide after some completion threshold.
67
71
68
72
The sphinx build environment is controlled by an environment variable `SPHINX_ENV`
69
73
70
-
- when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
74
+
* when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
71
75
and includes them in the language selector
72
-
- when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
76
+
* when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
73
77
are built and included in the language selector.
74
78
75
79
Most of the time you should not need to set `SPHINX_ENV`,
76
80
as it is forced by the primary nox sessions intended to be used for release or development:
77
81
78
82
`SPHINX_ENV=development`
79
-
-`docs-live` - autobuild english
80
-
-`docs-live-lang` - autobuild a single language
81
-
-`docs-live-langs` - autobuild all languages
83
+
*`docs-live` - autobuild english
84
+
*`docs-live-lang` - autobuild a single language
85
+
*`docs-live-langs` - autobuild all languages
82
86
83
87
`SPHINX_ENV=production`
84
-
-`build-test` - build all languages for production
88
+
*`build-test` - build all languages for production
The first round of our community-developed, how to create a Python package tutorial series for scientists is complete! Join our community review process or watch development of future tutorials in our [GitHub repo here](https://github.com/pyOpenSci/python-package-guide).
62
62
@@ -91,6 +91,7 @@ The first round of our community-developed, how to create a Python package tutor
91
91
:class-card: left-aligned
92
92
93
93
*[Introduction to Hatch](/tutorials/get-to-know-hatch)
94
+
*[Run Python scripts using Hatch](/tutorials/run-python-scripts-hatch)
94
95
95
96
:::
96
97
::::
@@ -193,7 +194,6 @@ Learn about best practices for:
193
194
194
195
## Tests
195
196
196
-
197
197
:::::{grid} 1 1 2 2
198
198
:class-container: text-center
199
199
:gutter: 3
@@ -212,7 +212,8 @@ Learn about best practices for:
:alt: xkcd comic showing a stick figure on the ground and one in the air. The one on the ground is saying. `You're flying! how?` The person in the air replies `Python!` Below is a 3 rectangle comic with the following text in each box. Box 1 - I learned it last night. Everything is so simple. Hello world is just print hello world. Box 2 - the person on the ground says - come join us programming is fun again. It's a whole new world. But how are you flying? box 3 - the person flying says - i just typed import antigravity. I also sampled everything in the medicine cabinet. But i think this is the python. The person on the ground is saying - that's it?
Copy file name to clipboardExpand all lines: package-structure-code/intro.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
This section covers everything you need to structure your Python package, configure metadata, choose build tools, and publish your package to PyPI and conda-forge.
Copy file name to clipboardExpand all lines: tests/code-cov.md
+44-15Lines changed: 44 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,31 +10,44 @@ using code coverage effectively.
10
10
A good practice is to ensure that every line of your code runs at least once
11
11
during your test suite. This helps you:
12
12
13
-
- Identify untested parts of your codebase.
14
-
- Catch bugs that might otherwise go unnoticed.
15
-
- Build confidence in your software's stability.
13
+
-**Identify untested parts:** Parts of your codebase that are not
14
+
covered by tests.
15
+
-**Catch bugs:** Bugs that might otherwise go unnoticed.
16
+
-**Build confidence:** Confidence in your software's stability.
16
17
17
18
## Limitations of code coverage
18
19
19
20
While high code coverage is valuable, it has its limits:
20
21
21
-
-**Difficult-to-test code:** Some parts of your code might be challenging to
22
-
test, either due to complexity or limited resources.
23
-
-**Missed edge cases:** Running all lines of code doesn’t guarantee that edge
24
-
cases are handled correctly.
22
+
-**Difficult-to-test code:** Some parts of your code might be
23
+
challenging to test, either due to complexity or limited resources.
24
+
-**Missed edge cases:** Running all lines of code doesn't guarantee
25
+
that edge cases are handled correctly.
25
26
26
27
Ultimately, you should focus on how your package will be used and ensure your
27
28
tests cover those scenarios adequately.
28
29
29
30
## Tools for analyzing Python package code coverage
30
31
31
-
Some common services for analyzing code coverage are [codecov.io](https://about.codecov.io/) and [coveralls.io](https://coveralls.io/). These projects are free for open source tools and will provide dashboards that tell you how much of your codebase is covered during your tests. We recommend setting up an account (on either CodeCov or Coveralls) and using it to keep track of your code coverage.
32
+
Some common services for analyzing code coverage are
33
+
[codecov.io](https://about.codecov.io/) and [coveralls.io](https://coveralls.io/).
34
+
These projects are free for open source tools and provide dashboards that
35
+
show how much of your codebase is covered during your tests. We recommend
36
+
setting up an account (on either CodeCov or Coveralls) and using it to
37
+
keep track of your code coverage.
32
38
33
39
:::{figure} ../images/code-cov-stravalib.png
34
40
:height: 450px
35
41
:alt: Screenshot of the code cov service - showing test coverage for the stravalib package. This image shows a list of package modules and the associated number of lines and % lines covered by tests. At the top of the image, you can see what branch is being evaluated and the path to the repository.
36
42
37
-
The CodeCov platform is a useful tool if you wish to track code coverage visually. Using it, you can not only get the same summary information that you can get with the **pytest-cov** extension. You can also see what lines are covered by your tests and which are not. Code coverage is useful for evaluating unit tests and/or how much of your package code is "covered". It, however, will not evaluate things like integration tests and end-to-end workflows.
43
+
The CodeCov platform is a useful tool if you wish to track code coverage
44
+
visually. Using it, you can get the same summary information that you can get
45
+
with the **pytest-cov** extension. You can also see what lines are covered by
46
+
your tests and which are not. Code coverage is useful for evaluating
47
+
[unit tests](test-types.md#unit-tests) and/or how much of your package code
48
+
is "covered". It, however, will not evaluate things like
49
+
[integration tests](test-types.md#integration-tests) and
50
+
[end-to-end workflows](test-types.md).
38
51
39
52
:::
40
53
@@ -46,21 +59,37 @@ You can also create and upload typing reports to CodeCov.
46
59
47
60
## Exporting Local Coverage Reports
48
61
49
-
In addition to using services like CodeCov or Coveralls, you can generate local coverage reports directly using the **coverage.py** tool. This can be especially useful if you want to create reports in Markdown or HTML format for offline use or documentation.
62
+
In addition to using services like CodeCov or Coveralls, you can generate
63
+
local coverage reports directly using the **coverage.py** tool. This can be
64
+
especially useful if you want to create reports in Markdown or HTML format for
65
+
offline use or documentation.
50
66
51
67
To generate a coverage report in **Markdown** format, run:
52
68
53
69
```bash
54
-
$ python -m coverage report --format=markdown
70
+
python -m coverage report --format=markdown
55
71
```
56
-
This command will produce a Markdown-formatted coverage summary that you can easily include in project documentation or share with your team.
57
72
58
-
To generate an HTML report that provides a detailed, interactive view of which lines are covered, use:
73
+
This command will produce a Markdown-formatted coverage summary that you can
74
+
include in project documentation or share with your team.
75
+
76
+
To generate an HTML report that provides a detailed, interactive view of which
77
+
lines are covered, use:
59
78
60
79
```bash
61
80
python -m coverage html
62
81
```
63
82
64
-
The generated HTML report will be saved in a directory named htmlcov by default. Open the index.html file in your browser to explore your coverage results.
83
+
The generated HTML report will be saved in a directory named `htmlcov` by
84
+
default. Open the `index.html` file in your browser to explore your coverage
85
+
results.
86
+
87
+
These local reports are an excellent way to quickly review coverage without
88
+
setting up an external service.
89
+
90
+
## Next steps
65
91
66
-
These local reports are an excellent way to quickly review coverage without setting up an external service.
92
+
Writing meaningful tests is the foundation of useful coverage.
93
+
See [Write tests](write-tests.md) and [Test types](test-types.md)
94
+
to learn more about developing better test suites. Learn how to run your tests both
95
+
[locally](run-tests.md) and in [continuous integration](tests-ci.md).
Tests are an important part of your Python package because they
5
-
provide a set of checks that ensure that your package is
4
+
Adding tests to your package provides a set of checks that ensure that its
6
5
functioning how you expect it to.
7
6
8
-
In this section, you will learn more about the importance of writing
9
-
tests for your Python package and how you can set up infrastructure
10
-
to run your tests both locally and on GitHub.
11
-
7
+
In this section, you will learn about the importance of writing
8
+
tests for your Python package, different [types of tests that you should consider](test-types) and how you can set up infrastructure
9
+
to run your tests both [locally](run-tests) and [on GitHub](tests-ci).
12
10
13
11
:::::{grid} 1 1 3 2
14
12
:class-container: text-center
@@ -20,9 +18,8 @@ to run your tests both locally and on GitHub.
20
18
:link-type: doc
21
19
:class-card: left-aligned
22
20
23
-
Learn more about the art of writing tests for your Python package.
24
-
Learn about why you should write tests and how they can help you and
25
-
potential contributors to your project.
21
+
Learn about the importance of writing tests for your Python
22
+
package and how they help you and potential contributors.
26
23
:::
27
24
::::
28
25
@@ -32,8 +29,8 @@ potential contributors to your project.
32
29
:link-type: doc
33
30
:class-card: left-aligned
34
31
35
-
There are three general types of tests that you can write for your Python
36
-
package: unit tests, integration tests and end-to-end (or functional) tests. Learn about all three.
32
+
Get to know the three test types: unit, integration, and
33
+
end-to-end tests. Learn when and how to use each.
37
34
:::
38
35
::::
39
36
@@ -43,32 +40,44 @@ package: unit tests, integration tests and end-to-end (or functional) tests. Lea
43
40
:link-type: doc
44
41
:class-card: left-aligned
45
42
46
-
If you expect your users to use your package across different versions
47
-
of Python, then using an automation tool such as nox to run your tests is useful. Learn about the various tools that you can use to run your tests across python versions here.
43
+
Learn about testing tools like pytest, nox, and tox to run
44
+
tests across different Python versions on your computer. And explore examples of using Hatch with UV as a task runner to run tests across Python versions.
48
45
:::
49
46
::::
50
47
51
48
::::{grid-item}
52
-
:::{card} ✨ Run tests online (using CI) ✨
53
-
:link: tests-ci
49
+
:::{card} ✨ Run tests locally (using nox) ✨
50
+
:link:run-tests-nox
54
51
:link-type: doc
55
52
:class-card: left-aligned
56
53
57
-
Continuous integration platforms such as GitHub Actions can be
58
-
useful for running your tests across both different Python versions
59
-
and different operating systems. Learn about setting up tests to run in Continuous Integration here.
54
+
Nox is a python powered task runner that can be used to run tests. Learn how to use nox to run tests.
60
55
:::
61
56
::::
62
57
63
-
:::::
64
-
58
+
::::{grid-item}
59
+
:::{card} ✨ Run tests online (using CI) ✨
60
+
:link: tests-ci
61
+
:link-type: doc
62
+
:class-card: left-aligned
65
63
66
-
:::{figure-md} fig-target
64
+
Set up continuous integration with GitHub Actions to run
65
+
tests across Python versions and operating systems.
0 commit comments