Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork464
Improve partial branch documentation: add missing branch examples#2092
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Improve partial branch documentation: add missing branch examples#2092
Conversation
nedbat commentedNov 20, 2025
Thanks for getting this started! I think all the examples should be put in branch.rst, since they will be helpful for people looking at the HTML report also. You can put something in cmd_report.rst that explains what For the formatting, try using |
Ayisha-Mohammed commentedNov 20, 2025
@nedbat made changes as requested. |
nedbat left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This is great. You've removed more text than I wanted you to, so we need to find the right balance.
| The HTML report gives information about which lines had missing branches. Lines | ||
| that were missing some branches are shown in yellow, with an annotationat the | ||
| far right showingbranch destination line numbers that were not exercised. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I'm not sure why you removed "at the far right". I thought people might not notice it at the edge that usually has no information, so I wanted to direct their attention there.
| also include branch information, including separate statement and branch | ||
| coverage percentages. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I like having extra space before headings. Can we keep the double-blank lines?
| flagged. | ||
| Generator expressions | ||
| ===================== |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This was meant to be a section within "Structurally partial branches", which is why it has a different header rule style.
doc/branch.rst Outdated
| executions divided by the execution opportunities. Each line in the file is an | ||
| execution opportunity, as is each branch destination. | ||
| covered total for each file. Each line in the file is an execution opportunity, | ||
| as is each branch destination. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
The last sentence mentions "execution opportunity", which was part of the sentence you dropped. I'm not sure the last sentence makes sense without it.
doc/branch.rst Outdated
| will not be marked as a partial branch. | ||
| Here the ``while`` loop will never exit normally, so it doesn't take both of | ||
| its "possible" branches. For some of these constructs, such as ``while True:`` | ||
| and ``if 0:``, coverage.py understands what is going on. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Again, I feel like something important is lost by dropping the last sentence of the paragraph.
doc/branch.rst Outdated
| Missing: | ||
| 12 -> 10 | ||
| Coverage.py will report:: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
We can probably skip this, since you've already said "12 -> 10" just above.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
you mean to remove the case2 block?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I meant that we show "12->10" here on line 164 but we already showed it on line 160. But this whole example needs to be re-thought.
doc/branch.rst Outdated
| If ``flag`` is always true, the false branch is never taken. | ||
| The report will show:: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
we should include the word "missing" here somehow to underscore that the branches reported are the missing branches.
doc/branch.rst Outdated
| A ``for`` loop has: | ||
| * ``20->21`` (enter body) | ||
| * ``21->20`` (repeat) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You used bullets here, but not above. We should choose a consistent style.
doc/commands/cmd_report.rst Outdated
| Missing branches | ||
| ---------------- | ||
| Missing branches are shown such as ``12->10``.why is it backward? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This make it sound like branches are always reported in reverse. We should be clear that it's only sometimes.
doc/commands/cmd_report.rst Outdated
| For detailed examples of how branch coverage works in loops and other control | ||
| flow constructs (``if/else``, ``for`` loops, ``while`` loops, ``try/except``), | ||
| see:doc:`branch</branch>`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This reads as "see branch." which isn't the form we want. Use:
see :ref:`branch`.Ayisha-Mohammed commentedNov 21, 2025
@nedbat i've made the changes you requested. Thank you for the guidance , learnt a lot though this process. |
doc/branch.rst Outdated
| Case 2 — ``items = [1]``:: | ||
| Missing: | ||
| 12 -> 10 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I'm sorry i didn't realize this earlier: this code doesn't have a branch from 12->10, because branches only occur where a statement can go next to two different places. Line 12 always goes to line 10, even on the last iteration of the loop. So we need to re-think this example.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
It's important to test the example to see that coverage.py actually reports the missing branches we're claiming.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@nedbat thank you , i fixed it
doc/branch.rst Outdated
| Case 2 — ``items = [1]``:: | ||
| Missing: | ||
| 12 -> 10 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
It's important to test the example to see that coverage.py actually reports the missing branches we're claiming.
| Case 2 — ``items = [1]``:: | ||
| Missing: | ||
| 4 -> 2 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This case is correct.
| Missing: | ||
| 2 -> 3 | ||
| 4 -> 2 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You have to actually run these examples to see what coverage produces:
% cat empty.pyitems = []for x in items: print(x) if x: print("x is true")print("done")% coverage run --branch empty.pydone% coverage report -mName Stmts Miss Branch BrPart Cover Missing------------------------------------------------------empty.py 6 3 4 1 40% 3-5------------------------------------------------------TOTAL 6 3 4 1 40%Here the report only says3-5 because none of those lines are run at all. Branches that are missing because the target line isn't run aren't reported as missing because that would create too much noise.
Ayisha-MohammedDec 16, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
i understand , coverage doesn't report any missing branches . because when item is empty ,(enter loop) never executes hence branch lines never executes.
This PR improves the partial branch coverage documentation by adding the missing examples.
Fixes#1597